WCLSG: Software Architecture

(This project listing describes the Software Engineering & Development process, considerations, and lessons learned from the Wirelessly-Connected Laser Shooting Gallery Project)

As discussed in the Electrical Engineering and System Architecture pages of this project, this system was designed to have two very similar hardware platforms with the same microcontroller, similar pinouts, and similar peripheral components in order to minimize the amount of code we'd have to write. This let us develop a "core" software package and architecture, which we then extended to implement the functionality required for each platform. This saved us a ton of time, as we didn't have to re-write any code.

Core Architecture

The biggest factor in the design of our system architecture was a specific library we were using, painlessMesh. While it took care of all of our networking requirements, it also imposed a requirement on us, TaskScheduler. TaskScheduler is a real-time multitasking scheduler for embedded devices, running user-defined tasks at fixed intervals, adjusted on-demand as the system needed. While an unexpected aspect of development, it turned out to be incredibly useful once we wrapped our brains around how we would have to develop in this system.

Our core architecture is divided in two functional categories: Managers and Modules.

Managers

"Managers" are a class of classes that are responsible for directly managing hardware or low-level system elements. They serve to expose more abstract control for these hardware systems to the whole software package, including other hardware managers. They're given an initialization opportunity, during which they configure the hardware as they require, and may register a task to the global scheduler if they require fixed updates during their operation. These managers tend to follow a singleton or static pattern, as they're used throughout the lifespan of the device's operation and tend to require monopolistic control over the hardware assets that they are responsible for.

A good example of this is our Audio Manager, which is responsible for loading, queuing, and feeding the buffer for our DAC/amplifier chip on both hardware platforms. During initialization, it prepares the audio playback, generator, and output helper classes, configures the audio chip, and initializes a task that is responsible for dumping audio data into the DAC as fast as possible whenever required. It also exposes public functions for the control of volume, cueing of audio files, and pausing playback.

As an aside, the Audio Manager is one of the most underdeveloped managers in the system. We never integrated it with the network system, so targets can't be triggered to play audio over the network. That's okay, however, as we never got the hardware amplifiers to work on the targets, so we wouldn't be able to play audio, anyway.

Modules

Logic Modules are dedicated, exclusive "Modules" that define the system's primary behavior. Think of these as states in a finite-state machine (FSM) - only one runs at a time, and they contain the logic that controls the system for that particular state. Logic modules can also flag the system to change the state, so that another logic module can take over.

Logic Modules all have a primary task that is used to enact the state management functionality. By binding functions to TaskScheduler's onEnable, onSleep, and Update callbacks, we can make ourselves a "onWake" function that runs whenever the system shifts into this mode, "onSleep" function that runs whenever the system is leaving this mode, and "update" on whatever fixed interval we see fit.

Logic Modules use this, alongside various callbacks they register in the hardware managers, to create our interfaces, gameplay logic, and more.

With a solid understanding of our general system, I'll go into more detail into the more interesting managers modules below, before I go into interesting platform-specific logic modules.

Interesting Hardware Managers

There are a lot of hardware managers, so I'll be covering the most interesting ones from the system. Some, like the "Power" and "Laser" managers may sound interesting, but were cut in scope (or are truly simple) to be not worth describing in dedicated sections. You can view their source code online (or email me directly) if you have questions, but in short - the "Power" manager turned on the 3V3 PWM lines required for the old switching regulator circuitry, and the laser manager turns on the laser when the trigger is pressed, with some safety control.

Config Manager

The Config Manager is responsible for storing long-lived data in the system, such as user settings and target pairing data. Internally, our configuration data is handled as a text-encoded JSON file stored in the MCU's non-volatile flash using the SPIFFS file system. A class called "ConfigurationData," which holds the long-lived data for the system during runtime, is responsible for serializing/deserializing itself into an ArduinoJson document which is then saved by the ConfigManager when requested. The ConfigurationData object is deserialized upon startup, but sets itself to default values of the deserialization process fails. 

Use of the ConfigManager by other parts of the system is typically done by adjusting the values of the ConfigurationManager's public ConfigurationData member, then by issuing a call to the "saveData" method of the ConfigurationManager. This allows external actors to adjust multiple pieces of data before serializing their changes, in case many things need to be adjusted at once.

Display Manager

The Display Manager, present only on the Controller, is responsible for driving the OLED display. While low-level control is performed by the display's provided Adafruit library, methods for drawing specific screens or patterns to the display are encapsulated in this class. Nothing outside of this class should ever have to do manual positioning of text on the screen, or configuring font sizes, or anything like that. 

Our primary screen, the "4-item menu," is just a public method of the Display Manager. Call it, pass in the title, four options, and left/right menu labels, and it'll draw it all. Similar methods were created for other stylings, as well as some internal helpers for drawing text with underlines (or centered horizontally).

Input Manager

The InputManager is present on both devices and manages anything that counts as input for each device platform. For the controllers, this is stuff like the menu buttons and trigger, while the target has the phototransistor array and pairing button. Inputs are polled every eight milliseconds, and their state is recorded in an internal array. Callbacks are issued every time the internal state has changed.

The input manager maintains a list of callbacks for each input source. When an input state change occurs, each of these callbacks for that input source are called. The Input Manager has public methods for registering and de-registering input callbacks. InputCallbacks are given the input source and the new state.

The InputManager also provides a public method for polling the input state of an input source.

Initially, the InputManager ran using Interrupts for each input source. A trigger pull or a button press would throw an interrupt, which would then enable a task on the InputManager to call the various callbacks whenever next available. Unfortunately, this setup caused issues with our Audio Manager - the interrupt would take too long, or happen in the middle of the audio manager sending audio data to the audio amp. This cause the audio manager to read an invalid location in memory, crashing the entire device. Changing to polling was an easy solution that ended up being more than reliable enough.

Lighting Manager

As the goal of the system was to ensure that the Targets would be driven entirely by Controller commands, the Lighting Manager needed to be able to display any lighting on the fly, through some encoded command. To achieve this goal, the lighting manager follows a set of variables to define an active "command," including settings like the primary/secondary color of LEDs, the 'pattern' to be displayed, timing information, and looping settings. The 'patterns' are, unfortunately, hard-coded in the system, small functions that directly drive the LED array on a fixed loop. These include the "static color," "blinking all," and "marching" patterns, which drive the entire array in a single solid color, blinking between both colors, or stepping through the LEDs one at a time (per segment) between the two colors selected.

In order to facilitate effects that "interrupt" the primary effect, like a bright flash when shot, the system keeps track of both an active and "on shot" lighting command, which can be set through the lighting manager's public methods. Either can be activated as required.

Lighting Commands are encoded as strings to be sent as part of network message with the following format

The Lighting Manager's commands ended up being the most complicated part of the system to program, and also the most un-used and unreliable. During gameplay, targets can get stuck in a "blink" state, where the lights stay blank white until another command turns them on/off/onto a different color. This can be confusing for players.

In addition, outside of blinking when players hit them and changing to static colors, the lighting manager was pretty unused. My goals of synchronizing lighting between targets, adding new patterns, and making the targets much more interesting visually fell by the wayside as our project's deadline drew nearer. Maybe someday I'll revisit it to play with the system I built, but not for now.

Network Manager

The Network Manager serves mostly to expose interfaces to the painlessMesh library, with the addition of a similar callback system to our input manager. Modules can ask to be informed when a new message comes in, and the Network Manager will issue those callbacks when new messages are received.

painlessMesh works by sending string packets across the network, either as broadcast messages or targeted messages. With the 32-bit unsigned integer ID of a chip, you can send a message directly to another device on the network, which is what we used to trigger specific targets, or for a target to let a controller know that it's been hit.

We built our own little format around this string packet - all messages start with the network time the messages was sent, a ";" separator, a string "tag" that defines the category of message (e.g., LASER_HIT, TARGET_IGNITE, TARGET_EXTINGUISH, another "|" separator, then the rest of the string can be arbitrary data related to that tag. The lighting manager slips its lighting command data into this part.

State Manager

The State Manager is the most important hardware manager of the system, but it's also simple. It maintains a map of states and their related tasks. When a state switch is initiated, it disables the active task then enables the new one. That's it. This ensures that we have only one "Logic Module" operating at any given time, which enables them to act with ultimate authority over the system.

Interesting Logic Modules

Our block diagram only shows four logic modules - Ready, Pairing, Play, and Results. This is really an abstraction of our logic modules - more the "categories" of functionality.

It's close to reality on the Target device; there's only three modules there (ready/play/pairing), and they perform simple tasks. Ready waits for gameplay start events, play responds to gameplay events, and pairing broadcasts pairing requests when hit.

The Controller, of course, is more complicated. It has, in total, 10 modules (about, pairing, ready, results, test_standby, test_target_timing, game_horde, game_one_shot, game_time_trial, game_whack_a_mole), though only eight are used by regular players (test_* is for testing purposes only).