RaftSysManager

Raft SysManager

The SysManager module is responsible for managing system modules (RaftSysMod) in a consistent way. It is a singleton object. Each SysMod derives from the RaftSysMod base class. These modules can be dynamically creted, enabled, disabled, or reconfigured by the SysManager.

Features

• SysMod Creation: Classes defining SysMods can define a "create" function which is used by a factory-model to construct SysMods. During the setup process the SysManager uses the information in the SysTypes (JSON) to determine which SysMods to construct. Subsequently the application code can create additional SysMods as required.
• SysMod Configuration: SysMods are configured using JSON via its setup() function. SysMods which are constructed during the SysManager initialization process are provided with the JSON settings that are specified in the SysTypes file. Subsequently created SysMods must be provided with JSON settings information by the application code.
• SysMod Management: Manages all SysMods (which are derived from RaftSysMod).
• Interaction by Name: Modules can be accessed by name for more complex interaction such as getting their status, sending JSON "commands", or accessing named-values provided by the SysMod.
• Looping Mechanism: Each constructed SysMod's loop() function is called iteratively.
• Supervisory Monitoring: Detects and logs performance issues such as long execution times in system modules.
• API: This module provides part of the overall API of the app, see Raft API List

SysManager Settings

When constructed normally (in RaftCoreApp for instance) the SysManager is configured using the contents of the SysTypes key SysManager. The settings available to configure SysManager are described in SysManagerSettings

SysManager API

The API provided by this module includes:

• /reset: Restarts the firmware.
• /v: Retrieves system version information.
• /caps: Lists device capabilities (the names of all registered REST API endpoints) so clients can feature-detect firmware support rather than probing. caps/<name> returns the method and description for one endpoint. See Raft Core API.
• /sysmodinfo: Retrieves information about a SysMod
• /sysmoddebug: Retrieves debug information from a SysMod. sysmoddebug/SysMan gives the main loop timing stats and the slow SysMod totals; sysmoddebug/RestAPI gives the deferred response counters.
• /friendlyname: Gets or sets the system's friendly name.
• /serialno: Gets or sets the system's serial number.
• /hwrevno: Retrieves hardware revision information.
• /datetime: Gets or sets the system UTC time. Accepts UTC (ISO 8601) or epoch (Unix seconds) parameters. The RaftJS library sends this automatically on connect, so devices have correct time even without NTP.

For full a list of Raft APIs with parameters and examples, see Raft API List

Keeping the main loop short

SysManager::loop() runs on the main task and calls every SysMod's loop() in turn, so one slow loop() (or REST API handler, which also runs on the main task) holds up everything else - device polling, publishing, the comms links. Aim to keep each pass of the main loop short (around 10 ms), and put slow work elsewhere:

• do it a step at a time from loop(), or in a task of your own;
• do file system work on the shared file system worker - file uploads and downloads, FileManager's file operations and the web server's static files already use it;
• for a REST request that can't be answered at once, defer the response.

Slow SysMod reporting

When reportSlowSysMod is on (the default, needs supervisorEnable), SysManager times each SysMod's loop() and reports one that takes longer than slowSysModMs (default 50 ms):

• The first slow loop of a SysMod is logged at once, as a warning: loop sysMod <name> SLOW took <N>ms, with (slow file system write) added if a file system write took over 10 ms during that loop (a flash erase or write stalls all code running from flash, so a SysMod can be slow because of a write somewhere else).
• Further slow loops of that SysMod are counted and summarised after 10 seconds: loop sysMod <name> SLOW <count> more times in <s>s max <N>ms, with the number of slow file system writes in that time.
• Totals since startup are returned by sysmoddebug/SysMan, after the loop timing stats, as "slow":{"n":...,"maxMs":...,"maxMod":"...","fsSlowWrites":...,"fsSlowWriteMs":...} - the number of slow loops, the longest and the SysMod it was in, and the number and total duration of slow file system writes.

See SysManager Settings for the settings.

Constructor

The constructor initializes the SysManager with essential parameters such as module names, system configuration, and serial information.

SysManager::SysManager(const char* pModuleName,
                RaftJsonIF& systemConfig,
                const String sysManagerNVSNamespace,
                SysTypeManager& sysTypeManager,
                const char* pSystemName,
                const char* pDefaultFriendlyName,
                uint32_t serialLengthBytes, 
                const char* pSerialMagicStr);

Parameters

• pModuleName: The name of the system manager (this must match the name used in the SysTypes JSON configuration for the SysManager object)
• systemConfig: Configuration information (JSON) - this is generally the entire SysTypes JSON.
• sysManagerNVSNamespace: Namespace for NVS storage area to be used the system manager.
• sysTypeManager: The manager SysTypes (which allows overriding SysType settings using an API).
• pSystemName: Name of the system (used as a default if not specified in the SysType).
• pDefaultFriendlyName: A friendly name for the system (used as a default, can be overriden by the user using the API).
• serialLengthBytes: Length of the system's serial number.
• pSerialMagicStr: A magic string for validating serial numbers.

Key Functions

void preSetup()

This function is called before the main setup. It configures the system name, version, friendly name, and settings like reboot intervals.

void postSetup()

This function is responsible for the final setup of the SysManager and SysMods. It creates modules, initializes REST API endpoints, and registers system diagnostics.

void loop()

The main loop of the SysManager where all registered modules are iterated over and their respective loop() functions are called. It also manages timing, monitors system performance, and handles system restarts if necessary.

void addManagedSysMod(RaftSysMod* pSysMod)

Adds a new system module to the manager.

void setStatusChangeCB(const char* sysModName, SysMod_statusChangeCB statusChangeCB)

Registers a callback for status changes in a system module.

String getStatusJSON(const char* sysModName) const

Retrieves the status of a system module in JSON format.

double getNamedValue(const char* sysModName, const char* valueName, bool& isValid)

Get a "named value" (double) from the specified SysMod along with a validity indicator.

void setModuleLogLevel(const char* pModuleName, const String& logLevel)

Set the logging level for a SysMod. Valid logLevel strings:

logLevel	Meaning
N	No logging
E	Error
W	Warning
I	Info
D	Debug
V	Verbose