Controlling Expansion Boards with the FAST Serial Protocol¶
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.
FAST Expansion boards are controlled via the FAST Serial Protocol connecting to processors over the FAST Expansion Bus. These processors will identify themselves as
FAST Expansion Boards are supported on all current FAST Platform Controllers. (The Neuron and Retro Controllers have EXP Ports on them. The Nano Controller can add an expansion hat to add support.)
Understanding the expansion board communication architecture¶
Communicating with EXP processors over the Expansion Bus is a bit different than other FAST processors and connections. The simple reason is that there can be multiple expansion boards on the same bus, each which could have one or more breakout boards. This means most EXP commands must be addressed to the specific expansion board + breakout board the device you're controlling is attached to.
There are two ways to target expansion board + breakout combination. You can embed an address into the command, or you can set a board to be "active" and then every command you send applies to that board until you set a different board to be active.
Let's look at the addresses themselves first, then we'll look at how to use them.
Expansion Board Addresses¶
The addresses of the various FAST Expansion Boards are pre-configured based on board type. FAST Expansion boards also have two solder jumpers you can use to set a board ID which is needed if you have more than one type of a particular board in a machine.
For example, maybe you have an
FP-EXP-0071 (which we often refer to as the "71" board) under the playfield and also in a topper. The address for a 71 board is
B4, so you could solder the ID jumper 0 on the second board which would give it the address
B5. The following chart shows the addresses of each expansion board for their various IDs. (You only need to worry about the ID setting if you have more of on of the same type of expansion board in a machine. All the boards are ID 0 by default with no jumpers soldered.)
Breakout Board Addresses¶
Some FAST Serial Protocol commands on the EXP bus apply to Expansion Boards themselves. (This includes commands like the
ID: command to identify a board, or the
BR: command to reset a board.) But most of your interaction with Expansion Boards will be controlling the devices attached to a board (LEDs, servos, etc.)
From an architecture standpoint, think of an Expansion Board like a "carrier board" that holds one or more breakout boards, and the breakout boards are what devices like LEDs are technically attached to.
Most FAST Expansion Boards have a Breakout Board 0 built into them which controls the devices connected to the Expansion Board itself. Many Expansion Boards have additional Breakout Board Headers which can be used to connect to additional breakout boards to add more devices to the expansion board.
The diagram of a FAST FP-EXP-0201 Expansion Board below illustrates this concept. This board has four built-in RGB LED ports (which can contain chains of up to 32 LEDs each). Those four LED ports are running on the onboard "Breakout Board 0". If you want to drive more than 128 LEDs from this Expansion Board, you can add an LED breakout board which would connect to one of the Breakout Broad headers.
This modular architecture allows pinball makers the flexibility to configure their FAST hardware for the exact device types and counts they need. It also allows for custom breakout boards to be built for specific scenarios. (For example, maybe you have a few lighting boards with lots of LEDs on them. We can then design a custom LED board that acts as a Breakout Board and connects directly to one of the Breakout headers on an Expansion Board.)
Breakout boards are individually addressable via a single nibble (0-5) added to the end of the Expansion Board address. Some examples are shown below:
- FP-EXP-0201 Expansion Board at ID 0 (Address
88), Onboard Breakout 0 (Address
- FP-EXP-0071 Expansion Board at ID 1 (Address
B5), Onboard Breakout 0 (Address
- FP-EXP-0201 Expansion Board at ID 3 (Address
8B), Remote Breakout 2 (Address
The Neuron Controller has a built-in Expansion Board too!¶
You may have noticed from the table above that there's an entry for the FAST Neuron Controller. That's because the Neuron has an Expansion Board built into it. So those 4-ports of LEDs on the Neuron are controlled via the Expansion Bus, using the Neuron's address
48. The built-in LED ports are Breakout Board 0, and then there are also three additional breakout board headers for additional connections. (The FAST Smart Power Filter Board connects to one of these, for example.)
What do you do with these addresses?¶
Now that we've looked at how Expansion Boards and their Breakout Boards are combined to get the full address for a device, let's look at how you use them. There are two options:
- Embed the address into a FAST Serial Protocol Command
- Set the "active" board, then send normal commands
Let's look at each.
Embedding Expansion+Breakout addresses into a command¶
Most FAST Serial Protocol commands for expansion and breakout boards can take an address parameter embedded into the command itself. Let's look at a simple example, using the
ID: command. (All of these examples are valid only on the EXP bus)
ID:Since this does not have an address embedded, one of the connected Expansion Boards will respond indicating the active connection is to an EXP bus.
ID@88:This is addressed to the FP-EXP-0201 Expansion Board with no solder jumpers. If you have one of these boards plugged in to your EXP Bus, then this board will respond with its ID. (If the address is not valid for a board that's connected, there will be no response.)
ID@881:This is addressed to the remote breakout board connected to Breakout 1 on that same expansion board. If a breakout board is attached, its processor will respond to this
ID:command. If there is no breakout board attached to Breakout 1, then this command will have no response.
Most (but not all) commands can have an address embedded into them. For example:
RA@880:005500 Turn all LEDs medium green, for LEDs attached to the built-in Breakout Board 0 (e.g. the 4 built-in LED ports) on an FP-EXP-0201 with no solder jumpers set.
Note that the address in the above command is
0, singling out the specific breakout board on that Expansion Board. If you tried the command
88 instead of
880, then this command work at the Expansion Board level, meaning that all LEDs attached to all Breakout Boards on that Expansion Board would turn green.)
The product documentation for the Expansion Boards lists the various addressing and breakout options for each board.
Setting an Active Expansion + Breakout Board¶
Instead of embedding the Expansion + Breakout address into every command, you can set a specific Expansion or Breakout Board to be "active", and then all subsequent commands without an address embedded in them are received by the active board.
An active board is set with the
EA: command. The
EA: command does not provide a response.
Here's the same example from above, used to turn all the LEDs from Breakout 0 on an FP-EXP-0201 Expansion Board light green: (Every line ends in a
<CR> which is not shown)
You can also use the two-character Expansion Board addresses like this. To reset all LEDs attached to the four onboard Breakout 0 ports, as well as any devices attached to any of the three remote breakouts, you would use the following sequence: (Every line ends in a
<CR> which is not shown)
Which addressing method should you use?¶
From a pure technical standpoint, it doesn't matter whether you use commands with the board address embedded versus setting the active board address and then using the shorter commands with no addresses in them. It really just depends on which method is more convenient based on the architecture of the game software you're writing.
For example, the Mission Pinball Framework mostly uses the "active board" method. To use the LED updates as an illustration, MPF maintains a list of "dirty" LEDs that need to be updated every frame. (e.g. 30 times a second). When the LED update process wakes up to update the LEDs, it scans through all the LEDs in the code to see which ones need to be updated, then it arranges them all by Breakout Board, then it walks through the breakout boards, setting the active board, updating the LEDs, and repeating until it's done.
For example, let's look at a pinball machine with the following LEDs connected:
- Neuron Controller, onboard LED ports (Breakout 0), address
- Neuron Controller, LED Breakout Board connected to Breakout 2, address
- FP-EXP-0201 Expansion Board, onboard LED ports (Breakout 0), address
- FP-EXP-0201 Expansion Board, LED Breakout Board connected to Breakout 1, address
If you look at the actual serial commands for the EXP bus that MPF would use to update LEDs each frame, it might look like this:
ea:480<cr> rd:02<binary LED update data> ea:482<cr> rd:04<binary LED update data> ea:880<cr> rd:1A<binary LED update data> ea:881<cr> rd:78<binary LED update data>
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 ?