SysMods

SysMods

SysMods are modules used to build a Raft application

SysMods are the basic building-blocks for both application-specific functionality and general system operation, they provide:

• setup() function for configuration using JSON
• loop() function for regular service
• Publishing of state information

Raft Library SysMods

The Raft libraries (RaftCore, RaftSysMods, RaftI2C, etc) provide SysMods handling:

• Networking (WiFi, Web serving, WebSockets, ethernet, BLE, MQTT)
• File and log management
• Publish/subscribe and other communications management
• Web server functionality
• I2C bus management

SysMod Anatomy

Each SysMod is defined by a C++ class which is derived from the base-class RaftSysMod. The SysMod class should define its own setup() and loop() functions and these are analogous to the setup() and loop() in an Arduino appliation. Initialisation of the resources to be used by the SysMod (such as GPIO pin configuration, use of any system resources like SPI or I2S, etc) should also be done in the setup() function.

The other important functions in a SysMod are the constructor and destructor. The constructor of a SysMod receives configuration information which is generally passed down to the base-class - in addition the constructor can perform operations that will endure for the lifetime of the SysMod. The destructor can be used to clean-up any resources that the SysMod has used but, in many cases, will never be called as most embedded applications will leave SysMods in place for the lifetime of the application.

The Raft run-time performs construction and configuration of all SysMods. It also maintains a list of active SysMods and allows asynchronous operation of each SysMod by frequently calling its loop() function.

Publishing State

SysMods can publish their state. To do this they need to register with the SysManager as a data source:

Registering as a Data Source

Writing SysMods

SysMods should be written so that they accomplish whatever activity they need to perform inside the loop() function and they should return from this function as quickly as possible. This is to allow other SysMods to run frequently too as all of the SysMods are effectively working co-operatively to give the semblance of multi-tasking. Ideally a SysMod's loop() function should return within a few milliseconds and staying in a loop() function for more than 50ms will negatively impact the performance of the application in many cases.

For many applications it won't be difficult to get loop() functions to return quickly. But in some cases it can be more difficult to achieve - e.g. when waiting for communication from a slow peripheral or doing some long computation. In these cases there are a number of ways to write the loop() function so that it returns quickly:

• A finite-state-machine (FSM) can be used to deal with the problem of "waiting-around for something to happen" by remembering that we are in a waiting state and then checking each time loop() is called to see if the program can progress to a different state. A couple of resources on this are Implementing Finite State Machines in Embedded Systems and Finite State Machines in Embedded Applications. This is generally a good approach if you are handling communication with a peripheral.

• A separate task can be started (generally this would be done in the setup() function) and this task can be given the job of handling the asynchronous activity. If, for instance, you need to collect data from a data collection device like the Analog-to-Digital converter in the ESP32, then you might find this a better approach as the time between samples will probably be more consistent than the FSM approach.

SysMod configuration

When a SysMod's setup() function is called it has access to a config object (simply called config) which permits access to the SysType JSON information. See the Configuration section for more details on how this works.

Comparison with Arduino setup() and loop() functions

Each Raft SysMod has the following methods (functions):

• setup() - this performs the same purpose as the setup() function of an Arduino program. It provides the SysMod with the opportunity to configure hardware and other functionality on system start-up
• loop() - this performs the same purpose as the loop() function of an Arduino program. It is called as frequently as is possible based on the performance of the microcontroller and the time taken to call the loop() functions of all of the other SysMods. Care should be taken to ensure that the loop() function of each SysMod returns as quickly as possible.