Effects Management

The Effects section lets you define interactive effects for your layout -- lights, sounds, LED strips, relays, and automated macros. Each effect is tied to a hardware device and can be triggered from the Throttle app, the Tour app, or through route and sensor automation. Effect data is stored in Firebase Firestore at layouts/{layoutId}/effects.

Effects List

The main effects view (/effects) shows your effects in a card grid. The toolbar provides:

• List Menu -- Options for filtering and display (view modes are handled through the shared ListMenu component).
• Sort -- Opens a drag-and-drop sorter dialog where you can reorder effects by dragging them into position, then saving the new order.

An "Add" tile at the beginning of the grid lets you create new effects.

Effect Types

DEJA.js supports ten effect types, each designed for a specific hardware use case:

Each effect type has a require array that determines which form fields are shown. For example, a Light requires a device and pin, while a Macro requires neither since it executes a sequence of other commands.

Creating an Effect

Navigate to /effects/new or click the Add tile. The effect form adapts dynamically based on the selected type.

Step 1: Select a Device (if required)

If the effect type requires a device, a device selector appears. All devices registered in your layout are shown as large toggle buttons. Select the device that controls this effect. Some effect types have a default device (for example, Sound effects default to deja-server).

Step 2: Select the Effect Type

A type selector displays all ten effect types as large buttons with icons and labels. Click the type that matches your hardware setup. Once selected, the type cannot be changed for an existing effect (only shown when creating new effects).

Step 3: Configure Fields

After selecting a type, the form displays the relevant fields:

Sound File Selection

For Sound effects, a dedicated sound file picker dialog lets you browse the available sound library. The dialog shows all uploaded sound files organized by category. Select a file and confirm the selection. The selected file path is displayed with a green checkmark indicator. You can clear the selection or change it at any time.

Macro Configuration

For Macro effects, the macro form lets you define two lists of commands:

• On commands -- DCC commands executed when the macro is activated.
• Off commands -- DCC commands executed when the macro is deactivated.

Each list accepts raw DCC command strings that are sent directly to the CommandStation.

IALED Configuration

For IALED (addressable LED strip) effects, a specialized form provides fields for:

• Strip -- The LED strip number on the controller.
• Pattern -- The animation pattern to apply.
• Range -- Which LEDs on the strip to control.
• Config -- A JSON configuration object displayed in an LCD-style preview panel.

Display and Access Options

All effect types share these additional settings:

• Color -- Pick a display color from the color picker dialog.
• Tags -- Assign tags for filtering and organization.
• Guest Access -- A toggle switch to allow visitors to control the effect from the Tour app. When enabled, unauthenticated users can trigger this effect. The label dynamically shows "Enabled" or "Disabled" with a corresponding icon.

Click Submit to save the effect, or Close to discard changes.

Editing an Effect

Click any effect card in the list to navigate to /effects/:effectId. The edit form shows all the same fields, pre-populated with the existing configuration. The effect type is locked and displayed as a chip at the top of the form. Modify fields and click Submit to save.

Sorting Effects

Click the sort button in the toolbar to open the Sort Effects dialog. Drag and drop effect tiles to reorder them, then click Save to persist the new sort order across all apps.

Data Structure

Each effect document in Firestore has the following shape:

How Effects Execute

When an effect is triggered:

1. The effect's state field is updated in Firestore.
2. The server's Firestore listener in modules/effects.ts detects the change.
3. Depending on the effect type:
   • Pin-based effects (light, LED, relay, etc.) -- The server sends <Z pin state> to the appropriate device.
   • Sound effects -- The server plays the audio file through its local sound system using play-sound.
   • Macro effects -- The server sends each command in the on/off array sequentially.
   • IALED effects -- The server sends the pattern and configuration to the device over MQTT.

Related Pages

• Turnouts Configuration -- Link effects to turnout actions.
• Signals Configuration -- Configure signal heads, which are similar to multi-pin effects.
• Layout Configuration -- Manage the devices that host your effects.