Repository navigation
DeviceManager
The DeviceManager SysMod is responsible for managing devices and buses. It sets up and monitors the status of devices, handles bus communication, and provides an interface for interacting with devices via REST API endpoints. The DeviceManager interacts with the system manager (SysManager) to register devices and manage data sources. Two distinct kinds of devices are managed:
- Dynamic Devices these are generally attached to a physical, (perhaps wireless, or even notional) bus and detected through some mechanism such that they can dynamically appear and may go offline again.
- Static Devices are generally hardware attached in other ways (SPI, GPIO, etc) and are not detected automatically but require the device code itself to instantiate and support them
- Device Setup and Management: Initializes and manages devices based on configuration.
- Bus Management: Monitors and handles bus operations and element statuses.
- REST API Interface: Provides REST endpoints for interacting with devices.
- Device Data Change Callbacks: Supports registering callbacks for device data changes.
- Status Monitoring: Continuously monitors the status of devices and buses.
-
setup(): Initializes buses from the
Busesconfiguration section and instantiates configured devices from theDeviceslist. -
postSetup(): Loads the device type file and the saved device settings, registers data sources for publishing (
devjson,devbin), callspostSetup()on each device, and registers device data/status callbacks. Buses start scanning straight away, but no device is identified until the type file has been loaded (ortypeFileTimeoutMshas passed), so the file's records and disabled types apply from the first identification. -
loop(): Services the bus system and then calls
loop()on each online device.
DeviceManager supports two paths for device creation:
-
Statically configured devices: Devices listed under
Devicesare created using the DeviceFactory, assigned a direct-connection device ID, thensetup()andpostSetup()are called. If a device provides a device type record, it is added to the device type records and assigned a type index. -
Dynamically detected bus devices: As buses report element status changes, newly identified devices are created as
RaftBusDeviceinstances, assigned their bus ID, and brought online. The manager updates online/offline state and registers for device data notifications when a device is first identified.
DeviceManager relies on the DeviceFactory to create devices from the class field in each device configuration entry. Device classes register themselves with the factory at startup. When a configuration entry is processed, DeviceManager looks up the class name in the factory and invokes the registered create function.
If a device provides a type record, DeviceManager registers it with the device type records and assigns a type index. The type information is used by the REST API (/devman/typeinfo) and by published device data. Two static devices with the same type share one record if their records are identical; if they differ, the second device's record is rejected (an error is logged) and that device has no type index. The number and size of these records are limited by the typeTable settings.
DeviceManager maintains two per-device maps that are independent of the device type record:
-
Name map — associates a friendly name (e.g.
IMU1,FuelGauge) with aRaftDeviceID. Names can be configured via thenamefield on aDevicesentry, via a top-levelDeviceNamesmap, or assigned at runtime through/devman/setname. -
Role map — associates a role string (default
normal, or e.g.system) with aRaftDeviceID. Roles allow callers to distinguish system-infrastructure devices (fuel gauges, RTCs, chargers) from standard published measurement devices. Roles can be configured via therolefield on aDevicesentry or assigned at runtime through/devman/setrole. The current role is reported by per-device/devman/typeinforequests and by/devman/listdevs.
Names, roles, devconfig settings and stopped polling set over the REST API last until the next restart, or are kept over restarts with save=1 (see saved device settings). Saved settings are keyed by device ID.
The display name is what to show for a device: its device name if it has one, otherwise its type display name (devInfoJson.name, or the device type key) and its device ID, e.g. Accelerometer & Gyroscope 1_68. getDeviceDisplayName(deviceID) returns it, and devman/listdevs and per-device devman/typeinfo report it as displayName. Consumers (clients, RaftROS, the data logger) should use it rather than forming their own.
A Devices entry that omits the class field is treated as a bus-tagging entry — it does not instantiate a device but instead assigns a name and/or role to a bus-discovered device identified by its bus+addr. See DeviceManager Settings for the full schema.
-
Named values:
getNamedValue()andgetNamedString()use the formDeviceName.paramNameto query values on a specific device;setNamedValue()andsetNamedString()route writes the same way. For a bus device the value comes from the newest record of its latest poll (a FIFO poll can hold several), and an array attribute's element is named with an index, e.g.Strip.diff[3](RaftCore 1.68.0 and later). -
JSON command routing:
receiveCmdJSON()expects a JSON body with adevicefield and forwards the command to that device. -
Device events: Device status/event callbacks are registered and forwarded to SysManager as
syseventmessages. -
Device status changes:
registerForDeviceStatusChange()listeners get aBusAddrStatusfor each bus device that comes online, goes offline or changes identity - see identity changes (identEvent:Identified,TypeChanged,Lost). Subscriptions made withregisterForDeviceData()by device ID last through re-identification and absences, so a consumer should subscribe through DeviceManager rather than on the bus.
A SysMod can subscribe to a device's decoded data directly (in addition to, or instead of, the published devjson/devbin topics) using DeviceManager::registerForDeviceData(). The callback fires whenever fresh data arrives for the target device, with the device type index (for decoding), the raw poll bytes, and any registered callback info:
using RaftDeviceDataChangeCB = std::function<void(uint32_t deviceTypeIdx,
std::vector<uint8_t> data,
const void* pCallbackInfo)>;The target device can be identified three ways:
-
By device ID / address —
RaftDeviceID, or a device-id string such as"I2CA_0x6a@3"/"1_6a"(bus name or number, hex address, optional@slotfor a multiplexer slot). -
By device name — e.g.
"IMU1"(a name set in the configuration or withsetDeviceName()). -
By device type index —
DeviceTypeIndexType. -
By device type key — e.g.
"LSM6DS3".
Registration works at any time: during setup() before the device has been identified (it takes effect when a matching device comes online), or later while the device is online (it takes effect at once).
Any number of subscribers can share a device. DeviceManager owns each bus device's single data callback and delivers each sample to every matching subscription (each with its own minTimeBetweenReportsMs). Always subscribe through DeviceManager: registering a callback directly on the bus (RaftBusDevicesIF::registerForDeviceData) replaces DeviceManager's, so every other subscriber loses the device's data (RaftCore logs data callback ... replaced by another subscriber).
Pass a pCallbackInfo that identifies the subscriber (e.g. this) and unsubscribe with the same target, the same pCallbackInfo and unregister = true; that removes only that subscriber's subscriptions. It returns only once no call to the subscriber is in progress on another task. Each registration adds a subscription (there is no de-duplication), so register once. The const char* overload accepts either a device-id string or a device type key (it first tries to resolve the string as a bus_addr identifier, then as a device name, then as a device type key), so callers targeting a specific bus address and callers targeting a type both work.
// e.g. from a SysMod setup(), register for the accelerometer at I2CA 0x15
getSysManager()->getDeviceManager()->registerForDeviceData("I2CA_0x15@0",
[this](uint32_t devTypeIdx, std::vector<uint8_t> data, const void* /*cbInfo*/) {
// decode `data` using devTypeIdx and use the values (see below)
},
50 /* min ms between reports */);data is one poll result at its actual length: a timestamp followed by the bytes read. A poll with a variable read length (a FIFO read, r{...} in the record's poll info) is shorter than the record's full size, resp.b plus the timestamp. The decoders read whole records of that size, so passed straight to the record's pollResultDecodeFn such a poll decodes to nothing. One poll can also hold several records (an IMU's FIFO read gives several samples).
Decode through DeviceTypeRecords instead, which pads a short poll with zeros (as the bus's own poll store does), and read values with the field descriptions' getValue() (RaftCore 1.68.0 and later). DeviceManager's named values, RaftI2C, RaftMicroPy and RaftROS all use these, so every consumer gets the same values:
// Every record the poll holds (structBuf holds up to maxRecs records of the record type's pollStructSize)
uint32_t n = deviceTypeRecords.decodePollData(devTypeIdx, data.data(), data.size(), structBuf, structBufSize,
maxRecs, decodeState);
// Or only the newest record, with the number of records the poll held
uint32_t n = deviceTypeRecords.decodeNewestPollRecord(devTypeIdx, data.data(), data.size(), record, recordSize,
decodeState);
// A field's value (element e of an array attribute), with what is still to be scaled applied
const DeviceTypeRecord* pRec = deviceTypeRecords.getRecord(devTypeIdx);
double value = 0;
pRec->pollFieldDescs[f].getValue(record, pRec->pollStructSize, e, value);-
Decode state: keep a
RaftBusDeviceDecodeStateper device between calls; it tracks timestamp wrap-around. -
On the bus task: a subscriber's callback runs on the bus task, whose stack is small.
decodeNewestPollRecordallocates working space for the records unless it is given some: the static overload takes the decode function, sizes and a buffer kept by the subscriber (as RaftROS's AutoPub does). -
Field descriptions:
elemCount()is the number of elements (1 for a scalar), andisIntegral()says whether the value is a whole number (an integer field with nothing to scale).
Every DeviceManager REST endpoint has a C++ equivalent, for SysMods that manage devices themselves:
| C++ | REST | Notes |
|---|---|---|
requestReIdentify(BusReIdentRequest, busNum) |
devman/reident |
Scopes: all, unidentified, one address, devices of a type, devices a type now outranks. An identified device keeps its type (and is polled) until a different result is known |
setTypePolicy(deviceTypeKey, policy) |
devman/typepolicy |
Enable or disable a type at runtime and identify the affected devices again. Not saved - the type file is |
markTypeFileChanged() |
devman/typefile restartRequired
|
Call after changing the device type file, so clients know a restart (devman/typefile/apply) is needed |
setDeviceName(), setDeviceRole(), getDeviceDisplayName()
|
devman/setname, setrole, listdevs
|
|
bus getBusDevicesIF()->requestReInit(address, doneFn)
|
devman/reinit |
Runs the init steps again on the bus task; devconfig settings are then applied again |
bus getBusDevicesIF()->setDevicePollingEnabled(address, enabled)
|
devman/devenable |
The REST endpoint also keeps the setting while the device is offline |
bus getBusDevicesIF()->getIdentInfoJson(address)
|
devman/identinfo |
|
bus getBusDevicesIF()->getIdentState(address, state, attempts)
|
- | The state (BusIdentState) and the consecutive attempts with that outcome, without building JSON: cheap enough to call for every device several times a second (e.g. status LEDs). False if the bus doesn't support it (RaftCore 1.62.0, RaftI2C 1.24.0) |
sendDeviceAction(deviceIdOrName, actionName, values, barMs, pErrorMsg, pNumWrites) sends an action from the device's type record by name - the C++ equivalent of devman/action, with the same encoding as raftjs, so a SysMod, an on-device script (RaftMicroPy device.action()) and a remote client drive a device alike:
String err;
if (pDevMan->sendDeviceAction("synth", "noteOn", {"60"}, 0, &err) != RAFT_OK)
LOG_W(MODULE_PREFIX, "noteOn failed: %s", err.c_str());-
deviceIdOrName: a device ID ("1_37","0_0"), a static device name or a name from the device name map. -
values: numbers as text, or the key of a map action. - A bus device gets the action's writes as one batch, and is barred for
barMsafter the last one; a directly-connected (static) device gets each write throughsendCmdBinary(). - Call it on the main task (e.g. from a SysMod
loop()); queue requests from other tasks. Errors are named as fordevman/action(failNoSuchAction,failBadValue, ...). (RaftCore versions after 1.67.0)
A change to the device type records themselves (added, replaced or removed records) is applied by a restart: edit the type file, call markTypeFileChanged(), and restart when convenient. A type's policy can be changed at once.
DeviceManager automatically publishes device data through the StatePublisher system using two topics:
- devjson: Human-readable JSON format for device data
- devbin: Compact binary format for efficient transmission
For detailed information about the message formats, subscription methods, and integration details, see Device Data Publishing.
Device data publishing uses a state-hash mechanism that combines bus timestamps and per-device state hashes, so publish updates only occur when device data changes.
DeviceManager supports various device types. Some devices have dedicated documentation:
- MotorControl Device - Multi-axis motor control with REST API and JSON commands
DeviceManager is part of every RaftCoreApp build unless the project sets set(RAFT_DEVICE_MANAGER OFF) in its features.cmake (see SysTypes). Without it SysManager::getDeviceManager() returns nullptr, so code that uses DeviceManager must check for that (RaftCore, RaftSysMods, RaftROS and the Robotical libraries already do - RaftROS then logs that auto-publishing is disabled).
When constructed normally (in RaftCoreApp for instance) the DeviceManager is configured using the contents of the SysTypes key DevMan. The settings available to configure DeviceManager are described in Device Manager Settings
RaftI2C scans I2C buses to detect devices, including those connected through bus multiplexers. For configuration of the I2C bus itself (pins, frequency, multiplexers, task parameters, etc.) see I2C Bus.
Scanning uses priority-based address ordering for efficient detection and supports device hot-swapping. For detailed information about the scanning process, priority lists, multiplexer handling, and bus stuck recovery, see I2C Device Scanning.
After devices are detected through scanning, DeviceManager identifies device types, initializes devices, and polls them for data at configured intervals. Device type records define how to identify, initialize, and poll each supported device type.
For detailed information about device type detection, initialization sequences, polling configuration, and data collection, see I2C Device Identification and Polling.
See Device Manager REST API for full endpoint details and examples.
Common Tasks
Getting Started
- Quick Start
- Architecture at a Glance
- Writing Your First SysMod
- Adding a Comms Channel
- Adding an I2C Device Type
Scaffolding & Building
- Raft CLI
- Web Apps (Device Types, Flasher)
- SysTypes
- Top-Level SysType
- Build Process
- WebUI Build Pipeline
- File System
- Partitions & Flash
- Local Dev Libraries
- Library Developer Guide
Architecture
Built-in SysMods
- NetworkManager
- WiFi Troubleshooting
- BLEManager
- WebServer
- MQTTManager
- SerialConsole
- CommandSerial
- CommandSocket
- CommandFile
- FileManager
- LogManager
- ESPOTAUpdate
- StatePublisher
- Remote Logging
- Data Source Registration
Comms & Protocols
- Stack Overview
- Comms Channels
- ProtocolExchange
- RICREST Protocol
- Real-Time Streams
- Adding REST Endpoints
- Built-in REST Endpoints
- File Download (OKTO)
- OTA Update Flow
Devices & Buses
- DeviceManager
- Device Manager REST API
- Device Factory & Classes
- Device Type Records
- Selecting Device Types
- Adding an I2C Device Type
- Device Data Publishing
- Data Logger
- I2C Bus
- I2C Device Scanning
- I2C ID & Polling
- MotorControl Overview
- MotorControl Config
- MotorControl Commands
- Camera
ROS 2
Helpers
Reference