FAST Framework Driver

The FAST driver communicates with FAST Pinball controllers over USB serial using the FAST serial protocol. It targets FAST Neuron (platform code 2000) controllers at 921600 baud.

Protocol Overview

The FAST serial protocol uses CR-terminated ASCII messages with hex-encoded numeric values. Messages follow the framing pattern CMD:data\r:

• A two-character command prefix, followed by a colon, comma-separated hex data fields, and a carriage return terminator.
• Responses indicate success with XX:P (pass), failure with XX:F (fail), or invalidity with XX:X.
• Asynchronous messages arrive unsolicited: -L:<hex> for switch closed, /L:<hex> for switch opened, and !B:<code> for board boot status.

Command Reference

The ES, TS, and EW commands travel over the EXP port, so hardware-resident light shows require exp_port to be configured.

Configuration

The FAST driver is configured in a platform block within your Cade configuration file.

platform "fast" "main" {
  net_port    = "/dev/ttyUSB0"
  exp_port    = "/dev/ttyUSB1"
  baud        = 921600
  platform    = "2000"
  watchdog_ms = 1000
}

Properties

Supported Capabilities

The FAST driver supports the full set of hardware capabilities:

• Switch inputs — monitored over SL: / SA: configuration and -L: / /L: asynchronous events.
• Coils — pulse (DL: mode 01) and hold/enable (DL: mode 02, a latch). Coils are configured for manual triggering (mode 00) by default and switched off with TL:.
• RGB LEDs — individual and batched colour updates via RS:, RA:, and RF: (fade).
• Firmware-assisted flippers — configured through DL: (mode 10) and toggled with TL:.
• Firmware-assisted autofire rules — bumpers, slingshots, and other rule-driven coils via DL: (mode 11) and TL:.
• Servo motors — enabled with EM: and positioned with MP:.
• Firmware-assisted light shows — compiled to EXP scripts and executed directly on the controller. Requires exp_port.

Firmware-assisted flippers and autofire rules execute on the FAST controller, delivering sub-millisecond response times independent of the host.

Platform Capabilities

Switch, coil, and light maxima are not fixed — Cade reports them after board discovery finishes, so they reflect the boards actually attached to your machine. The firmware version and hardware revision reported alongside them come from the controller’s own identification response.

Show Script Support

When a light show can be compiled into a FAST EXP script, the controller runs it directly on the hardware — eliminating tick-loop overhead and ensuring precise timing.

Light shows are translated into EXP script strings built from these elements:

One FAST tick is 32ms, and tick counts are clamped to the range 1–255, so a single fade or wait step tops out at roughly eight seconds.

Scripts are limited to 128 characters. Shows that exceed firmware constraints (multiple LED groups, script too long) are not offloaded — Cade logs the reason and runs the show from the host instead. This fallback is silent from a gameplay perspective: the show still plays, just driven by the host rather than the controller.

Board Discovery

On startup, the driver discovers attached I/O boards by querying node addresses sequentially (NN:00, NN:01, …). Each response returns the board name, firmware version, driver (coil output) count, and switch input count. An address with no board answers with the name !Node Not Found!; discovery stops after three consecutive misses.

Each discovered board reports eleven comma-separated fields, the first five of which are the ones you will care about:

NN:<node_id>,<name>,<fw_version>,<driver_count>,<switch_count>,<6 further fields>

For example: NN:00,FP-I/O-3208-2,01.05,08,20,...

The total switch and driver counts across all discovered boards determine the platform capabilities reported to the rest of the system.

Connection Management

The driver manages one or two serial connections:

• NET connection (required) — the primary link to the NET processor. Carries all command/response traffic, switch events, and boot messages.
• EXP connection (optional) — a secondary link to the EXP processor for expanded I/O, configured via exp_port.

Commands that expect a reply wait up to two seconds for it; a slower response is reported as a timeout in the logs. Unsolicited switch notifications (-L: / /L:) and board boot status messages (!B:) are handled independently of that exchange, so heavy switch traffic does not delay reboot detection.

On connection open, the driver discards any stale data left in the serial buffer from a previous session, so leftover responses cannot be misread as answers to new commands.

High-rate commands — watchdog refreshes, LED updates, and servo positioning — are sent without waiting for acknowledgment, which is why a failed LED write does not surface as an error the way a failed configuration command does.

Initialization Sequence

The startup handshake follows a fixed sequence:

1. ID: — identify the board model and firmware version.
2. CH:2000,01 — configure for Neuron platform with verbose switch reporting.
3. WD:0001 — expire the watchdog (clean slate).
4. NN:00, NN:01, … — discover all attached I/O boards.

Once discovery completes, the driver reports the aggregate board capabilities and begins monitoring the watchdog, boot messages, and switch event stream.

Automatic Recovery

The driver handles board reboots automatically. A background boot message listener monitors for !B: messages:

When the board signals ready after a reboot, the driver re-runs the initialization sequence and resumes normal operation without requiring a restart of the host application.

Watchdog

When watchdog_ms is greater than zero, the driver runs a periodic watchdog refresh to keep the FAST controller active. If the host stops sending watchdog pings (e.g., due to a crash), the controller automatically disables all outputs to protect the hardware.

Troubleshooting