Skip to content

FAST Serial Protocol command & message structure (with examples)

FAST Serial Protocol: Overview & First Steps

This documentation section is about the FAST Serial Protocol (FSP) commands, which are the low-level commands a host computer sends to a FAST board. Most FAST Pinball makers do not need to know about these details, since the pinball game framework (such as the Mission Pinball Framework) handles this communication for you.

If you're writing your own game framework, we have a series of programming guides. Also, be sure to read the overview of how FSP works and how to connect first.

The FAST Serial Protocol command set is used to configure and control all aspect of the FAST Pinball hardware. These commands and messages are transmitted via virtual serial ports (usually over a USB connection) between your host controller and the FAST Pinball hardware

What type of host computer / machine controller can be used?

The FAST Pinball hardware has USB ports. Your game software runs on some type of computing device which connects to the FAST Pinball hardware via USB. There are a few fundamental requirements for what type of device can be used as this host computer:

  • It must be able to establish high-speed (921,600 baud), 8-N-1 serial connections.
  • It must be able to transmit and receive ASCII (UTF-8) encoded/decoded characters.
  • It should be able to connect to multiple serial ports simultaneously.
  • Note that USB is not a strict requirement, but it's what most people used. (Details below)

While we refer to the controlling device as a "host computer", it doesn't have to be a computer per se. Anything can can make the high-speed serial connections should be fine.

USB is technically optional

While the vast majority of FAST Pinball makers connect their host computer to the FAST Pinball hardware via USB, you can actually make a direct serial connection. For example, the FAST Neuron Controller has headers for a Raspberry Pi to plug directly into the board. In that case you run your game software on the Pi itself, but the Pi uses direct serial ports via its plug-in header and not USB. You could repurpose this for many different types of non-USB serial connections

Because the core requirements for communicating with FAST Pinball hardware are fairly low, really any type of computer, running any OS, running software written in any language should be fine.

Once the host computer establishes a serial connection with the FAST Pinball hardware, it sends various configuration commands which set up how the drivers should fire, how the switches should be read, and sets up automatic high-speed "hardware-controlled" actions for things like flipper control, pop bumpers, sling shots, diverters, etc. which will work with no additional support or CPU cycles required by the host computer. This allows the host computer to spend its cycles on more CPU cycle intensive functions like graphic content and sound generation.

Debug and monitoring are also simplified because most all commands are ASCII friendly so any TTY serial analyzer or logic analyzer with a serial communication engine can view the commands going back and forth. You can even fire your first coil (the pinball equivalent of "hello world") with nothing more than a terminal program!

Symbols used in this command reference

  • <> Anything in brackets represents a byte or bytes. There will be a name between the brackets representing the type of data for that field.

  • Most data sent to or received from the FAST Platform is in two ASCII nibble format, though a few commands use a binary format.

  • ASCII nibble format requires two characters per byte. The hex value 0xA5 would be sent as two individual characters: "A" followed by the character "5". A 16-bit value requires four ASCII characters to be sent, and a 32-bit value requires eight ASCII characters to be sent.

  • ASCII characters representing hex values are not case-sensitive and do not need to be zero-padded. (e.g. 0F and F and 0f and f are all the same.)

  • Some commands require binary-encoded data. (This is not common, and most binary commands have ASCII equivalents, but binary commands are useful for high-frequency commands with lots of data, like for DMDs, segment displays, RGB LEDs, etc.) Binary commands are sent one character per byte.

ASCII serial terminal commands are awesome!

One fun aspect of using FAST Pinball hardware is if you're working on a machine which having a problem, and you can't figure out what's happen, you can connect a terminal directly to the FAST hardware to interact with it directly, reading states and configuration and trigger things interactively!

Command syntax

  • Most commands start with two ASCII characters followed by a colon : character. Examples: ID:, SA: DL:.

  • Most commands can take additional data after the colon but before the closing <CR>. For example: DL:01,09,04,10,1F,2D,14<CR>

  • Most commands end with a <CR>.

  • Some commands can accept variable-length data fields. In those cases, if a <CR> is sent before all the data fields, only those fields sent will be modified. Example: DL:01,81<CR>

  • Some commands will respond with the current field values if a <CR> is received before any fields are sent. This is used to read the current values instead of writing new values. Example: DL:01<CR>

Command responses

Some commands send back a response, and some do not. Sometimes those responses are simple, just letting you know that a particular command succeeded or failed, and sometimes they are more complex, like a response to a query which sends lots of configuration or current state information.

  • All responses from a FAST processor sent back to the host computer end with a <CR>.

  • The first characters of response will be the name of the command plus the colon. So if you send a command like DL:01,09,04<CR>, any response to that will start with DL:.

  • Some common responses (just using the WD: as an example, but most of the commands are the same this way):

    • WD:P<CR> The command was successful. (P = Passed)

    • WD:F<CR> The command failed. (F = Failed) This is typically a typo, or you tried to send a value that was outside of the acceptable range.

    • XX:F<CR> Indicates the last command received was not valid. If you just hit Return in your terminal emulator, you will get the XX:F back because sending <CR> by itself is not a valid command.

    • WX:F<CR> The second character of command invalid, or garbage received after first character.

Some examples:

WD:1F4<CR>
WD:P<CR> #(1)

WD:PP<CR>
WD:F<CR> #(2)

WZ:<CR>
WX:F<CR> # (3)
  1. Watchdog command was used to set timeout to 500ms (1F4 in hex), which passed
  2. Watchdog command failed, as "PP" is not valid data to send to a WD: command.
  3. Second character of the command (in this example, the “Z”) is invalid.

N or > jump the next page, P or < for previous, search with S or ?