FAST Framework

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

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, enable, and disable via DL: modes and TL: triggers.
• 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.

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

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.

The show compiler translates Show definitions into EXP script strings with the following commands:

Scripts are limited to 128 characters. Shows that exceed firmware constraints (multiple LED groups, script too long) return errors and fall back gracefully to software-driven tick loops on the host.

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. Discovery stops after three consecutive empty nodes.

Each discovered board reports information in the following format:

NN:<node_id>,<name>,<fw_version>,<driver_count>,<switch_count>,...

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.

Command responses are matched to the sending command with a two-second timeout. Unsolicited switch notifications (-L: / /L:) and board boot status messages (!B:) arrive on separate channels, so a busy switch matrix cannot starve boot-status handling.

On connection open, the driver drains any stale data left in the serial buffer from a previous session so leftover responses cannot be misinterpreted.

Fire-and-forget commands (watchdog refresh, LED updates, servo positioning) do not block waiting for acknowledgment.

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.