Automations

An automation is a little program for your layout. It watches for something to happen, checks that it is safe to go ahead, and then does a series of things -- throw a turnout, start a train, wait for it to reach a sensor, stop it, blow the horn. Automations run on your DEJA server, so they keep going even if you close the app.

What an Automation Is

An automation is a stack of chunky, coloured blocks that lock together like puzzle pieces, read from top to bottom. The studio shows the automation's name as the page title (tap it to rename), with Test run, Cancel and Save beside it, and the stack below. On the right (below the stack on a tablet) is the help column -- help for the block you have open, or a short How it works guide when none is (see Help as You Build below) -- and Start from a template; on a phone they fold away behind Help & templates under the stack. DejaBot, a little pixel robot, walks a dotted lane down the left of the stack and points at whatever you are working on: the block you selected, the Add step slot whose menu is open, or the trigger when nothing is selected.

• The hat -- the block at the top is the event that starts the automation. It reads When [EN0 is divergent] only if [BNSF 5801 #1 is moving]. Selected, it holds everything that is not a step: the Name and Description, what Starts it, the optional Only if conditions, the Parameters, the Enabled and Guest access switches, and Advanced.
• The steps -- run in order from top to bottom, below the hat. Each one shows what it acts on and a small value tag (ON, STRAIGHT, 40…); a delay shows its seconds as a row of segments.

Every block works the same way: tap a block to select it, and its editor opens right below it. Change what you need and tap Done to keep it; tap the block again to close the editor without keeping your changes. The hat keeps what you type and pick as you go, so its chips follow along. Nothing is saved until you tap Save. Only one block is selected at a time. Each kind of block has its own colour, so a turnout step always looks like a turnout step. The hat shows small tags for Disabled, Guests and how many parameters it has.

Test run

Test run is a preview: the robot walks through the automation on screen, and nothing moves on the layout -- no commands are sent. It starts at the trigger and steps down the blocks about every half second. Each block it has passed shows a check, a delay fills its segments one at a time, and disabled steps are skipped. At an If block it takes the branch shown on the block's TRUE / FALSE tag (tap the tag to switch), and the other lane fades. A Repeat is walked once. While it runs the button reads Stop; tap it to end the preview early. Changing anything in the automation also ends it. When it finishes, the robot waits at the bottom of the stack until you pick a block.

Help as You Build

The help column follows the block you have open. Select the hat and it explains what can start an automation; select a Wait for… and it explains each Until it choice, Clear for, Give up after and On timeout. Every setting in the open editor is listed with what it means, a choice lists each of its options with the one you have picked marked Now (so the help changes as you change the block), and most blocks end with a practical tip. Close the block, or tap Done, and the column goes back to How it works.

Meet DejaBot

DejaBot is the robot in the studio and beside every automation on the list. He wears an engineer's cap, carries a lantern for an antenna and rolls on two little wheels. His eyes are signal lamps: cyan-white when he is idle, green while the automation runs, amber while it waits, and a red X for about ten seconds after a run ends badly. While a run is going, steam puffs from his smokestack and the needle on his belly gauge sweeps. He falls asleep, with his eyes shut, Zzz and a red marker lamp lit, when the automation is disabled or automations are paused after an E-stop. He waves hello, hops when you press Run, cheers when a run or a Test run finishes well and when you save, and looks worried when Save finds something to fix. If your device is set to reduce motion, he holds still and shows one picture for each mood.

Open Automations at /automations. Everyone on the layout can see the list. The layout owner creates automations with New, which opens a blank studio, and edits one at /automations/:automationId/edit. The studio for a brand-new automation lives at /automations/new.

The Automations page looks like the studio: a dark dotted background with flat, coloured pixel blocks. DejaBot stands beside every automation, and his eyes show what it is doing (see Meet DejaBot above). A disabled automation's DejaBot is asleep. With no automations yet, a big DejaBot waves hello above the templates. Blocks, triggers and steps wear the same icons as the rest of Throttle -- the turnout, signal and sensor icons, the roster's train, the Delay timer. The density buttons at the top trade detail for how many automations fit on screen. In Comfy and Compact, the owner gets Edit (pencil) and Delete (bin) buttons on each automation; Delete asks once, in place -- tap Delete again to confirm, or ✕ (or Esc) to keep it. List has no room for them, so there they are in the ⋮ menu. Comfy, the default, shows each automation as a short block stack with DejaBot in a lane on its left. The top block, in the colour of what starts it, holds the name and when it runs. Up to six steps follow as interlocking blocks, with If and Repeat wrapped around their own steps. A longer automation fades out at the bottom with +N more. DejaBot points at the top block, or at the step a running automation is on. Under the stack sit the status, a Run button, Edit and Delete. Compact shows a bigger DejaBot for each automation. He says the automation's name in a speech bubble, and its steps show as icons on the screen on his belly, up to eight. An automation made before the studio says Needs update on its screen. Run, Edit and Delete sit under it (on a narrow screen, Edit and Delete drop to a second row). List puts each automation on one line: a coloured strip for what starts it, a small DejaBot, the name, a small coloured tile for each step, the status while there is one, ▶ or ■, and ⋮. Comfy and List are one column on a phone and two on a wide screen. Compact fits two robots across a phone and up to six on a wide screen. The app remembers your choice on this device.

💡 Bookmarks to the old /sensors/automations pages still work -- they redirect here.

Start From a Scaffold

With no automations yet, the owner's Automations page offers Start from -- four ready-made scaffolds -- and Blank automation:

A scaffold is not a form. It opens the studio with the blocks already in place and every sensor, turnout, signal and loco left blank. The first block that still needs something is open, ready for you to pick it. Fill in the blanks, adjust anything you like, and Save.

The same four scaffolds are in the studio itself, under Start from a template. On a new automation with no steps yet, tapping one lays out its trigger and steps straight away. If the automation already has steps, the studio asks Replace the current steps? first -- tap Replace to swap in the template's trigger and steps, or Cancel to keep what you have. A name you have typed is kept; a blank one takes the template's.

Triggers

Select the hat: its Starts section holds the trigger. Pick the kind and what it watches:

Train has passed fires when the sensor activates and then stays clear for a short settle time (half a second by default). The settle time stops the gaps between cars from ending the detection early.

An automation converted from before the studio may have two triggers (a sensor's activate and clear). The hat then shows a pill for each one: pick a pill to edit that trigger, or Remove this trigger.

The hat's Advanced row has a cooldown (the minimum gap between firings) and an If triggered while running choice: ignore the new trigger, or start over.

Only If: Conditions

Conditions are checked the moment the trigger fires, and all of them must hold -- otherwise the automation does nothing (no run starts). You can test:

• Whether a sensor is active or clear
• Whether a turnout is straight or divergent
• Which aspect a signal is showing
• Whether a block is occupied or free
• Whether an effect is on or off
• Whether a loco is stopped or moving
• Whether another automation is running or idle

The Only if section of the hat reads Always until you add one. Tap Add condition and pick a coloured block for what to test. Each condition is a small block of its own: tap it to change it or Remove condition, and tap Done to keep it.

Steps

The steps hang below the hat. To add one, tap an Add step slot -- there is one at the bottom of the stack and one at the end of every lane. A menu opens (a sheet from the bottom of the screen on a phone): Do something -- the eight actions -- then Wait, decide, repeat. Tap a step and it lands at the end of that slot's list, already selected with its editor open. Steps for a part of the app wear that part's colour -- a turnout step is the Turnouts page's amber -- and when a step's editor lists your turnouts, effects, routes or locos, each one shows in the colour you gave it (or the section's colour if it has none). Hover over a step (on a tablet, the tools are always there; on a phone, select the step) to use its tools: the arrows reorder it, the eye disables it, and the bin deletes it. A disabled step is faded and skipped.

If blocks wrap around two lanes side by side -- Then and Else (one above the other on a phone) -- and Repeat blocks around one. Each lane ends in its own Add step slot. An If or Repeat placed inside another one wraps around its own steps too, with Then above Else, and its lanes have their own Add step slots. You can nest them three levels deep; at the third level the Add step menu greys out If and Repeat.

The actions available under Do something:

• Throttle -- set a loco's speed and direction, or stop it
• Turnout -- set it Straight or Divergent
• Signal -- set an aspect
• Effect -- switch on or off
• Route -- run a route
• Loco function -- on, off, or pulse (handy for a horn)
• Sound -- play a sound from your library
• Emergency stop

How Waiting Works

Waiting is where most automations succeed or fail, so the rules are simple and exact:

Every wait has a timeout, five minutes by default. You choose what happens when it runs out: stop the run (it shows as Timed out) or carry on with the next step. You can also set a wait to wait forever, but the studio shows a warning when you do.

Repeat Rules

• A repeat must contain a wait, or a delay of at least a quarter second (250 ms), somewhere inside it, so it cannot spin flat out.
• You can nest If and Repeat steps up to three levels deep.
• Changes you save while an automation is running apply from the next run.

Parameters: Run With a Different Loco

A button automation can ask for its inputs each time it runs -- the same arrival sequence with this loco today and that one tomorrow.

1. Open the hat and, under Parameters, tap Add parameter. Pick what it stands for: a Loco, Turnout, Signal, Effect, Sensor, Block or Route.
2. Give it a name -- that is what the Run prompt asks for, so Loco or Yard turnout reads well. The small key under the name is set once and never changes, so renaming is always safe.
3. Optionally pick a Default: a roster loco or any DCC address, or one of your layout's items. Ask each time means no default.
4. In a step (or a condition) that picks a loco or an item, tap the parameter under Use parameter instead of a fixed one. The step then reads «Loco» → 40 fwd. Picking a fixed one below switches it back.

Tap Run with… on the card and a prompt asks for each parameter, with the defaults filled in. Run stays grey until every one has a value. Run in the quick menu (⌘K) runs straight away when every parameter has a default; otherwise it opens the same prompt.

⚠️ An automation that a sensor, turnout, signal or the server can start has nobody to ask, so every parameter needs a default. The studio will not save it until each one has one.

Triggers never use parameters -- what starts an automation is always a real sensor, turnout or signal.

Running Automations

• Run / Stop -- every card has a button. Any member of the layout can run and stop automations. Stopping a run brings the locos it was driving to a stop. An automation with parameters shows Run with… and asks first (see above).
• Quick menu -- press ⌘K and type Run plus the automation's name, or choose Stop all automations & pause.
• Stop all & pause -- members also get a Stop all & pause button in the Automations page header, next to New. Like the quick-menu command, it stops every running automation, brings the locos those automations were driving to a stop, and pauses automations until someone taps Resume (see below).
• Live status -- while a run is going, its card shows what it is doing right now: Running (with how long it has been going, and the lap when it repeats) or Waiting... (naming the sensor or target it waits for).
• When a run ends badly -- a run that Timed out, Failed, was Taken over or was Interrupted shows that on its card for about ten seconds, with the reason (tap or hover the status for the full text), and then the card goes quiet. A run that could not start because a parameter had no value fails straight away with missing parameter «Loco».
• No run history -- a run that finishes or is stopped simply clears. Automations keep no history and no run counts; a card with nothing running shows no status at all.

Watching a Run

When you press Run (or Run in the Run with… prompt), a window opens where DejaBot walks through the automation's own blocks as the server runs them. He goes to each step as it starts, and passed steps get a check mark. The branch an If took stays bright while the other one fades, and a Repeat shows which lap it is on. While a step waits, DejaBot's eyes turn amber and a speech bubble says what he is waiting for and for how long. At the end he cheers for Run complete, shows the reason if the run timed out or failed, looks worried if you took the loco, or falls asleep if the run was stopped. The last state stays on screen until you close the window. Hide, ✕, Esc or a tap outside only close the window, and the run keeps going. Stop stops the run. It is there until the window sees the run end -- even while it says No run seen yet -- and reads Stopping… once you tap it. No run seen yet means the server has not reported the run within a few seconds: it may have finished instantly, or no DEJA server is running for this layout. To watch a run you did not start here, tap its status or its DejaBot on the Automations page. Untick Show the run viewer when I press Run if you would rather it stay closed; the app remembers the choice on this device. Run from the quick menu (⌘K) opens it too when that box is ticked. A Test run in the studio is only a preview and keeps its own robot lane.

Older Automations

Automations made before the studio show a Needs update chip on their card. They do not run until you open them in the studio and save. Opening one converts it to the new format automatically.

Human Wins

If a person touches a loco that an automation is driving -- moving its throttle in the app -- the automation lets go. That run ends as Taken over, so it never fights you for control.

If a loco is held by a WiThrottle app or handheld throttle (Engine Driver, ProtoThrottle and similar), the automation step that would command it is skipped, rather than fighting the throttle. The server log notes each skipped step and why.

E-Stop and Resume

The emergency stop button stops every train on the layout. It also stops every automation, running or waiting, and then pauses them. Stop all & pause on the Automations page and Stop all automations & pause in the quick menu do the same for automations: they stop every run, bring the locos those runs were driving to a stop, and pause automations. Locos you are driving yourself are left alone.

While paused, no trigger fires. A banner on the Automations page says so. Any member can tap Resume to let automations work again. Restarting the server also clears the pause, and any automation that starts on Server start then runs.

A few related safety behaviors:

• When a run is stopped, times out, or fails, the locos it was driving are brought to a stop. Stopping the server (deja stop or Ctrl-C) does the same for every run.
• If the server goes into standby, runs are stopped too, and so are their locos.
• If the server restarts in the middle of a run, that run shows Interrupted, and the locos it was driving are stopped.
• A run that finishes leaves its locos as its last steps left them. A run that is Taken over leaves the loco you took to you, and stops any other locos the automation was driving.

Build a Shuttle (Worked Example)

The classic first automation: a train runs back and forth between two sensors, pausing at each end. It takes about two minutes in the studio and uses most of the building blocks above.

You need: a loco on the roster, and two sensors, one near each end of the run. Call them End A and End B. Park the train at End A.

The quick way: on an empty Automations page, tap Start from → Shuttle between two sensors (or, in a new automation, tap it under Start from a template). The loop below is already laid out, with the first throttle block open. Fill the blanks -- your loco in each throttle block, End B in the first wait, End A in the second -- rename it in the hat, and Save.

Step by step, from a blank studio:

1. Go to Automations and tap New. The studio opens with the hat selected. Type Shuttle #3 as the title (use your loco's number). Leave Starts on Button in the app (so you start it with Run) and Only if reading Always. Tap Done.
2. Tap the Add step slot at the bottom of the stack and pick Repeat. It opens set to until stopped; tap Done. Everything below goes inside this loop: for each block, tap the Add step slot inside the Repeat block and pick the step from its menu.
3. The outbound leg, five blocks. Each one opens as soon as you pick it; fill it in and tap Done:
   1. Throttle: your loco, speed 40, Forward.
   2. Wait for… -- Sensor, End B, until it activates (next time). Keep the default five-minute timeout.
   3. Throttle: your loco, speed 0.
   4. Delay: 10 seconds. This is the dwell at the end of the line.
   5. Optional Loco function: your loco, F2, mode Pulse. A horn before departure.
4. The return leg: the same five blocks, with the throttle in Reverse and the wait on End A.
5. Save, then tap Run on its card.

💡 Want one shuttle for any loco? Add a Loco parameter in the hat and pick it under Use parameter in each throttle block. Run with… then asks which loco to send.

The train runs until you press Stop, which brings it to a stop. If the train never reaches the next sensor within the timeout, the run ends as Timed out and the loco is stopped, so a stalled train is never driven forever.

💡 Parked at End B instead? Put the return leg first. The first leg must drive away from where the train sits.

Who Can Do What

Each automation also has a Guest access switch in its hat. It has no effect yet. It is a setting for a future guest experience, so you will not need to set it up again later.

Tips

• Stopping a train at a sensor -- leave debounce empty on a sensor that stops a train, or a fast train can arrive inside the debounce window and be missed.
• Repeats must yield -- a repeat needs a wait, or a delay of at least 250 ms, inside it. The studio will tell you if it is missing one.
• Two automations, one loco -- if two enabled automations drive the same loco, the studio warns you. The last command wins.
• Find what uses a sensor -- the sensor form's Used by row links back to every automation that starts from it.
• A sensor can be both trigger and wait -- an automation may wait on the same sensor that starts it. A shuttle started by End A, for example, also waits on End A at the end of its return leg.

Related Pages

• Sensors -- The hardware inputs that start and pace automations.
• Turnouts -- Turnouts an automation can set or wait on.
• Signals -- Signals an automation can set or react to.
• Effects -- Effects and sounds an automation can play.
• Routes -- Routes an automation can run.
• Command Menu -- Run automations from anywhere with ⌘K.