Layout Configuration

The Layout section is where you manage the hardware infrastructure behind your model railroad. This includes registering hardware devices (CommandStations, Arduino boards, Raspberry Pi Pico W controllers), viewing available serial ports, reviewing loaded firmware modules, and organizing your layout with tags. Layout data is stored in Firebase Firestore at layouts/{layoutId}.

Layout Overview

The layout page (/layout) opens with the layout name displayed as a prominent header. Below it, the page is organized into four sections: Devices, Tags, Ports, and Modules.

Devices

The Devices section displays all hardware controllers registered in your layout as a responsive card grid (one column on mobile, two on tablet, three on desktop). Each device card shows the device ID, type, and a visual indicator of its connection status.

Adding a Device

Click the Add tile to expand the device registration form. The form lets you register a new hardware device by specifying:

• Device ID -- A unique identifier for the device (e.g., commandstation-1, turnout-board-east).
• Device Type -- The type of hardware. Supported device types include DCC-EX CommandStation, DEJA Arduino boards, Raspberry Pi Pico W, and others defined in the deviceTypes constant.
• Connection -- How the device connects to the server (USB serial, WiFi/MQTT, etc.).
• Port -- The serial port path (for USB-connected devices).
• Topic -- The MQTT topic (for WiFi-connected devices).

After filling in the form, save the device to register it in your layout's Firestore document.

Device Details

Click any device card to navigate to the device details page at /layout/device/:deviceId. This view provides a comprehensive overview of the selected device:

Connection Status

A row of chips at the top shows:

• Connection type -- USB or WiFi, shown as a colored chip.
• Port -- The serial port path (for USB devices), e.g., /dev/ttyACM0.
• Topic -- The MQTT topic (for WiFi devices).
• Status -- Connected or Disconnected, with a pulsing status indicator for connected devices.

Assigned Turnouts

A table lists all turnouts assigned to this device with columns for:

Assigned Effects

A table lists all effects assigned to this device with columns for:

Developer Configuration

For DCC-EX and DEJA Arduino devices, an expandable "Developer Configuration" panel generates a config.h code snippet that can be used in the Arduino firmware. This auto-generated configuration includes:

• Device ID definition
• Feature enable/disable flags based on assigned turnouts and effects
• Servo PWM constants
• Output pin arrays derived from the device's effects
• Signal pin arrays
• Sensor pin arrays
• Turnout pulser configuration

LCD-style display panels show additional developer-friendly views:

• PULSER CODE -- TurnoutPulser() constructor calls for each turnout.
• PIN CONFIG -- Straight/divergent pin pairs for each turnout.
• TURNOUT LABELS -- Turnout names for labeling in firmware.
• EFFECT LABELS -- Effect names for reference.

This section is designed to help firmware developers quickly generate the configuration code needed when flashing new Arduino or Pico W boards.

Tags

The Tags section provides a management interface for layout-wide tags. Tags are reusable labels that you can assign to turnouts, routes, effects, and signals for filtering and organization.

• View tags -- The tag list displays all defined tags for the layout.
• Add a tag -- Click the "Add Tag" chip to open the tag creation form.
• Edit a tag -- Click any tag to open the edit form where you can modify its name, color, or other properties.

Tags are shared across all sections of the Cloud app. For example, a tag called "East Yard" could be applied to turnouts, routes, and effects that are all located in the east yard area of your layout.

Ports

The Ports card displays a list of serial/USB ports detected by the DEJA.js server. This is useful for identifying which port your CommandStation is connected to.

• Each port is listed by its system path (e.g., /dev/ttyACM0, /dev/ttyUSB0, or COM3 on Windows).
• Click the Refresh button to re-scan for available ports. This sends a listPorts command through the DEJA command pipeline to the server, which queries the system for connected serial devices and returns the updated list.

Ports are reported by the server and stored in the layout document. They update automatically when the server detects new USB connections or disconnections.

Modules

The Modules card lists the firmware modules currently loaded on the CommandStation. These are reported by the DCC-EX CommandStation during its startup sequence and stored in the layout document. Common modules include:

• Motor driver configurations
• WiFi module status
• Ethernet module status
• Sensor input configurations

This list is read-only and reflects what the CommandStation reported. It is useful for verifying that the expected firmware configuration is active.

Data Structure

The layout document in Firestore has the following top-level fields:

Each device document has:

Layout Selection

If you need to switch to a different layout, navigate to /select-layout. The layout selector shows all layouts available to your account. Select a layout to set it as the active layout. The selection is persisted in local storage and used by all sections of the Cloud app.

Related Pages

• Cloud App Overview -- Return to the main Cloud app guide.
• DCC-EX Console -- Send commands to devices configured here.
• Turnouts Configuration -- Assign turnouts to the devices you register.
• Effects Management -- Assign effects to the devices you register.