How ThrottleCard Syncs Your Roster with iCloud

Running trains should feel effortless—no matter which device you’re holding.

Many of you run ThrottleCard across multiple devices: a phone for quick sessions, an iPad for layout-side control, or a new device after an upgrade. You’ve told us you want your rosters, consists, and settings to be there—without rebuilding everything each time.

With ThrottleCard 3.0, we introduced iCloud Sync to make that happen—carefully and intentionally.

The goal is simple:

• Your configuration follows you across devices
• Sync is always opt-in and under your control
• Live train operation stays local and predictable

This guide explains what iCloud Sync does, what it doesn’t do, and how to use it with confidence.

---

What iCloud Sync Does

When enabled, iCloud Sync keeps the following data automatically synchronized across your Apple devices:

• Locomotive roster
• Saved consists
• Per-locomotive settings (themes, control layouts, knob preferences)
• Accessories and routes
• General UI and app preferences

Changes made on one device are propagated to your other devices using your Apple ID. There are no separate ThrottleCard accounts, no manual exports, and no setup beyond enabling the feature.

---

What iCloud Sync Does Not Do

Just as important as what syncs is what always remains local.

iCloud Sync never syncs:

• Active throttle connections
• Live speed, direction, or function state
• Command station connections
• Session-specific or real-time control data

This separation ensures that syncing configuration data can never interfere with live train operation. Every operating session remains fully local and fully under your control.

---

How iCloud Sync Works

ThrottleCard uses a local-first sync model:

1. Your data is stored locally on your device
2. When changes occur, they are written to iCloud
3. Other devices receive and merge those updates automatically
4. Sync happens quietly in the background

All synced data is stored in your iCloud Drive in a human-readable JSON format. This means:

• You can back up your ThrottleCard data yourself at any time
• Your data isn’t locked into a proprietary or opaque format
• The structure is designed with future extensibility in mind

This approach allows us to keep your data portable today, while leaving the door open for additional sync options—such as other cloud providers—down the road.

ThrottleCard does not run its own cloud service and does not store your data on external servers. All syncing happens through Apple’s iCloud infrastructure using your existing Apple ID.

---

Conflict Handling & Data Safety

iCloud Sync is designed to behave predictably.

• Changes sync shortly after they’re made
• If multiple devices edit the same item, the most recent change wins
• Sync pauses gracefully when offline and resumes when connectivity returns
• Data is never modified unless you explicitly change it

For best results, we recommend allowing changes to finish syncing before making major edits on another device—especially when managing large rosters.

---

How to Enable iCloud Sync

iCloud Sync is opt-in and disabled by default.

To enable it:

1. Open ThrottleCard Settings
2. Navigate to iCloud Sync
3. Toggle Enable iCloud Sync
4. Ensure iCloud Drive is enabled for ThrottleCard in iOS Settings

Once enabled, syncing begins automatically.

💡 Tip: After first enabling sync, give it a moment to propagate before opening ThrottleCard on another device.

---

Choosing How to Enable iCloud Sync

Each time you enable iCloud Sync, ThrottleCard asks how you’d like to handle existing data.

This ensures you are always in control of which data is used—especially if you’ve made changes locally, on another device, or in iCloud while sync was turned off.

When enabling iCloud Sync, you’ll be presented with three options:

Use Local Data

Copies the data from this device into iCloud.

Choose this if:

• This device contains the roster and settings you want to keep
• You’ve made recent changes locally
• You want this device to become the source of truth

This option uploads your current local data to iCloud.

---

Use Cloud Data

Replaces this device’s local data with what’s already in iCloud.

Choose this if:

• Another device already has the correct setup
• You want this device to match your iCloud data
• You haven’t made changes locally that you need to keep

This option downloads the iCloud version and applies it to this device.

---

Merge Data

Combines local and cloud data, keeping local data when conflicts occur.

Choose this if:

• Both local and iCloud data contain useful changes
• You want to preserve as much as possible
• You’re unsure which version to prefer

When merging:

• Locomotives, consists, and settings are combined
• If the same item exists in both places, the local version is kept

---

Cancel

Leaves iCloud Sync disabled and makes no changes. You can enable it again at any time from Settings.

💡 Tip: This choice only affects the initial sync. After iCloud Sync is enabled, updates happen automatically in the background, with the most recent saved change taking precedence.

---

Best Practices

While iCloud Sync is designed to stay out of your way, a few simple habits help ensure smooth results:

• Make large roster or consist changes on one device at a time
• Allow sync to complete before opening the app on another device
• Keep iCloud Drive enabled and signed in on all devices
• Treat one device as your “primary editor” during major changes

These aren’t requirements—just recommendations for predictable behavior.

---

Why We Built iCloud Sync This Way

We chose iCloud intentionally.

Using Apple’s native sync infrastructure allows us to:

• Keep your data private and under your Apple ID
• Avoid additional accounts or logins
• Eliminate external servers and custom cloud logic
• Integrate cleanly with the Apple ecosystem

We also waited to introduce sync until ThrottleCard itself was ready. Configuration sync touches core data, and it needed to be stable, intentional, and trustworthy before shipping.

---

Getting Started

If you use ThrottleCard on more than one device, iCloud Sync removes friction and keeps your setup consistent—quietly and reliably.

Enable it once, and let ThrottleCard follow you wherever you run trains.

👉 Download or update ThrottleCard on the App Store

---

As always, your feedback helps shape where ThrottleCard goes next. If you have questions, edge cases, or ideas you’d like us to explore, we’d love to hear from you.