Locomotive Roster

The Roster section is where you build and maintain your digital locomotive fleet. Each locomotive entry stores its DCC address, display name, road name, color, sound capability, decoder function mappings, and consist configuration. All data is stored in Firebase Firestore under layouts/{layoutId}/throttles and is immediately available to the Throttle app for real-time control.

Roster List

The main roster view displays your locomotives in a responsive card grid (single column on mobile, two columns on tablet, three on desktop). Each card shows the locomotive's name, DCC address, road name, and assigned color. Cards use animated transitions powered by FormKit Auto-Animate for smooth entry and exit effects when locomotives are added or removed.

An "Add" tile appears at the beginning of the grid as a visual prompt to add new locomotives.

If no locomotives have been added yet, an empty state is shown with the message "No Locomotives Yet" and a description of what the roster is for. It includes quick-links highlighting key capabilities: programming DCC decoders, configuring functions and lights, and building consists.

Adding a Locomotive

Navigate to the roster and click the Add tile, or go directly to /locos/new. The add form collects the following information:

The road name selection uses a chip group with filter-style selection. Each road name comes from the ROADNAMES constant in @repo/modules/locos, which defines a value, label, and default color for each railroad.

After filling in the form, click Submit to create the locomotive. The createLoco function from useLocos() writes the document to Firestore. Click Close to return to the roster list without saving.

Editing a Locomotive

Click any locomotive card in the roster grid to open the edit view at /locos/:address. The edit form is divided into three sections: basic information, consist management, and function configuration.

Basic Information

The top card ("Edit Loco") contains:

• DCC Address -- The decoder address (editable).
• Name -- The display name.
• Road Name -- A chip group selector with the same railroad options as the add form.
• Color -- A color picker button that opens a dialog for choosing a display color. The chosen color is applied to UI elements associated with this locomotive throughout all apps.
• Locomotive has onboard sound -- A toggle switch.

Click Submit to save changes or Close to discard and return to the roster.

Consist Management

Below the basic information card is a Consist section. If the locomotive has consist members, they are displayed as a row of chips showing each unit's DCC address and direction indicator. The lead locomotive is marked with a left-arrow icon, and trailing units show directional arrows based on their orientation (forward or reversed).

Click Edit Consist to open a dialog where you can add or remove consist members. The consist editor component (EditConsist from @repo/ui) allows you to:

• Add locomotives by DCC address
• Set each unit's direction (forward or reversed relative to the lead unit)
• Remove units from the consist

Changes to the consist are saved along with the lead locomotive's document.

Function Configuration

The Functions card lists all 29 DCC decoder functions (F0 through F28). Each function row can be customized with:

• Label -- A human-readable name (e.g., "Headlight", "Bell", "Horn").
• Icon -- A display icon for the function button.
• Visibility -- Whether the function appears in the Throttle app's control panel.

The function list is pre-populated from defaultFunctions in @repo/modules/locos, which provides standard labels and icons for common decoder functions. You can override any default to match your specific decoder's function mapping.

After making changes, click Save (enabled only when modifications have been detected) to persist the updated function configuration.

Viewing Raw Data

At the bottom of the edit page, expandable "View JSON" panels show the raw Firestore document data for both the locomotive and its consist. This is useful for debugging or verifying the exact data structure stored in the database.

Data Flow

When you save a locomotive in the Cloud app:

1. The useLocos() composable writes the document to Firestore at layouts/{layoutId}/throttles/{address}.
2. The Throttle app's VueFire bindings pick up the change in real time.
3. If the locomotive is currently being controlled, the Throttle app reflects the updated name, color, and function labels immediately.

Related Pages

• Cloud App Overview -- Navigate back to the main Cloud app guide.
• Turnouts Configuration -- Set up turnouts for your layout.
• Routes Configuration -- Define automated turnout sequences.