FAST Serial Protocol Command 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, 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 the necessary components of a pinball machine. A host computer only needs two things to communicate with the FAST platform: a serial port connection to the FAST hardware, and the ability to send and receive the commands outlined in this documentation. This means almost any computer or microcontroller can be a host for the FAST platform. We don't have any hard core requirements, so you can use whatever type of system and language that makes sense to you.
Once the FAST platform is configured most actions such as flipper control, pop bumpers, sling shots, even diverters 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
0xA5would 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
For the few commands that require binary format, that's sent one character per byte. This format is not used often in the command set, and is not very friendly to a terminal screen. It is usually only used in commands where speed is a benefit. Most commands that use binary format have an equivalent command that uses ASCII nibble format instead. This helps with debugging and when testing the system using a terminal program. (Yeah, imagine that! If you're working on a machine having a problem and you can't figure out what's happen, you can connect a terminal directly to the FAST hardware to read states and configuration and trigger things!)
Some Common Types of Data:
<CR>represents a carriage return (ASCII decimal 13, hex
0x0D). If you're using a serial terminal software and sending commands manually, this will be configured for what's sent when you press the Return or Enter key.
<Driver_ID>Each driver is represented by a hexadecimal number in ASCII nibble format. (These are "0 referenced", which means the first driver is 0, the second is 1, etc.)
<Switch_ID>Each switch is represented by a hexadecimal number in ASCII nibble format. (Also 0 referenced)
<Time>Normally in milliseconds (ms) but some commands have multipliers where the time specified is in x10 or x100 ms.
The FAST Serial Protocol runs at different speeds, depending on which board and port you're connecting to. Refer to the product docs for the product you're connecting to for details about what baud rate you should use. (Many products support multiple baudrates for different scenarios.)
Most commands start with two ASCII characters followed by a colon
:character. Example command:
Most commands can take additional data after the colon but before the
<CR>. Example command:
Most commands end with a
Some commands can accept variable-length data fields. In those cases, if a
<CR>is sent before with less than all the data fields, only those fields sent will be modified.
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.
Not all commands have responses.
All responses from a FAST processor sent back to the host computer end with a
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
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. Most likely this was a typo, or you tried to send a value that was outside of the acceptable range.
XX:F<CR>The last command was not valid. If you just hit Return in your terminal emulator, you will get the
XX:Fback 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.
WD:1F4<CR> WD:P<CR> #(1) WD:PP<CR> WD:F<CR> #(2) WZ:<CR> WX:F<CR> # (3)
- Watchdog command was used to set timeout to 500ms (1F4 in hex), which passed
- Watchdog command failed, as "PP" is not valid data to send to a WD: command.
- Second character of the command (in this example, the “Z”) is invalid.
Documentation Feedback? Requests? Confused?
Hi! I'm Brian, and I'm responsible for the documentation at FAST Pinball. If you have any feedback, requests, corrections, ideas, or any other thoughts about this documentation, please let me know! You can email me at firstname.lastname@example.org. Thanks!
N or > jump the next page, P or < for previous, search with S or ?