State Machine
The system always exists in one of the predefined states, also known as modes.
You can read the current mode in the /app_mode variable at the root level. The mode is also broadcast in both CAN status messages — see CAN Messages. The mode is complemented by the global application flags — see Status Word.
The values are ordered by activity: a higher value means the system is further along toward full generation. This makes range checks meaningful — for example app_mode >= 95 means "the engine is running", app_mode >= 85 means "the starting sequence is engaged or beyond".
Any state falls back to STOPPED when the start request is released, to ERROR on a controller fault, and to OVERVOLTAGE if the engine overspeeds while running. OVERVOLTAGE and MAX_TRIALS are latched — the latch survives even a transient controller error, and only releasing the start request resets it. The overvoltage latch additionally propagates to both controllers of a pair: a hazard of the shared shaft and DC bus stops the whole system.
In a multi-master system the following controller mirrors the mode of the leader during the starting sequence, and it does not report MODE_OVR while the leader drives its motor — that is the normal operating condition.
| Value | Mode name | Description |
|---|---|---|
| 0 | MODE_ERROR | Controller is in an error state. Either `/driver/error` or `/common/error` is non-zero. Ignition open, engine shut down. Recovers automatically when the error clears. |
| 50 | MODE_STOPPED | No start request. Ignition open, ready to start. |
| 60 | MODE_OVERVOLTAGE | Uncontrolled generation detected: the generated current escaping regulation while pushed back into the DC bus, a driver overvoltage/range protection, or power stage overtemperature (engine overspeed, or a battery unable to accept the charge). The engine is killed through the ignition relay and the motor freewheels. Latched, and propagated to the peer controller — release the start request to reset. |
| 65 | MODE_MAX_TRIALS | Engine did not start within the maximum number of attempts. Latched — release the start request to reset. |
| 70 | MODE_STANDBY | Reserved, not implemented yet: automatic stop after the generation demand stays at zero for a configured time — the engine stops from idle and waits for the demand to return. |
| 80 | MODE_PAUSE | Pause between start attempts — the engine did not catch within the cranking time. |
| 85 | MODE_PULLBACK | Starting: brief reverse rotation before cranking. |
| 90 | MODE_STARTING | Starting: cranking the engine. |
| 95 | MODE_WARMUP | Engine started, warming up. No generation load; the starter assist stays engaged and catches the engine if it chokes. |
| 100 | MODE_IDLE | Engine idles unloaded — the generation demand is zero. The motor freewheels. |
| 110 | MODE_RAMPUP | Generation load is ramping up toward the demand. |
| 115 | MODE_RAMPDOWN | Generation demand dropped to zero — the load is ramping down toward idle. |
| 120 | MODE_GENERATING | Fully loaded generation at the demanded level. |
| 200 | MODE_OVR | Application is overridden via the process API or the `run`/`stop` shell commands. Not reported on a controller whose motor is driven by the multi-master leader. |
When a DC regulation limiter hovers around exactly zero demand (typically the voltage limiter on a nearly full battery), the mode may alternate between MODE_RAMPUP and MODE_RAMPDOWN at the limiter's own pace, with a status broadcast on each change. This is bounded and harmless, and will be smoothed in a future release.