Layout Configuration
The Layout section is where you manage the hardware infrastructure behind your model railroad. This includes registering hardware devices (EX-CommandStations, Arduino Mega boards, ESP32 boards over USB or WiFi, and Raspberry Pi Pico W controllers) and viewing available serial ports.
Layout Overview
The Devices page (/devices) opens with the layout name displayed as a prominent header. It lists your DEJA Server and registered hardware devices, with a serial Ports panel below. Layout-wide Tags are managed separately under Settings → Layout.
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: DCC-EX EX-CommandStation (
dcc-ex), DEJA Arduino Mega (deja-arduino), ESP32 over USB (deja-esp32), ESP32 over WiFi/MQTT (deja-esp32-wifi), Raspberry Pi Pico W (deja-mqtt), and others. - 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.
Device Details
Click any device card to navigate to the device details page at /devices/: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:
| Column | Description |
|---|---|
| Idx | The DCC turnout index |
| Name | Turnout display name |
| Pins | Straight and divergent pin values (color-coded green/orange) |
| Type | Turnout mechanism type (Kato, Servo, etc.) |
| State | Current state indicator (arrow up for straight, arrow down-right for divergent) |
Assigned Effects
A table lists all effects assigned to this device with columns for:
| Column | Description |
|---|---|
| Name | Effect display name with type-specific icon |
| ID | The effect document ID |
| Type | Effect type (light, LED, relay, etc.) |
| Pin | Output pin number |
Developer Configuration
For DCC-EX, DEJA Arduino, and ESP32 devices, an expandable "Developer Configuration" panel generates a code snippet that can be used in the Arduino/ESP32 firmware. For WiFi-connected ESP32 devices it also bakes in the WiFi and MQTT credentials. The panel also surfaces the exact PlatformIO and Arduino CLI build/upload commands for the device, matching what deja deploy runs. 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, ESP32, or Pico W boards. See Arduino & ESP32 Setup and Pico W Setup for the full firmware setup walkthroughs.
Tags
Layout-wide tags are managed under Settings → Layout. 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 EX-CommandStation is connected to.
- Each port is listed by its system path (e.g.,
/dev/ttyACM0,/dev/ttyUSB0, orCOM3on Windows). - Click the Refresh button to re-scan for available ports.
Ports are reported by the server and update automatically when it detects new USB connections or disconnections.
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. Your selection is remembered 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.