Skip to content

DeviceManagerRESTAPI

Jump to bottom
Rob Dobson edited this page May 19, 2026 · 5 revisions

DeviceManager REST API

The API for DeviceManager is included in the Raft API List

1. /devman/typeinfo

Description:

This endpoint operates in two modes:

  1. Type lookup — supply a type parameter (device type name or device type index) to retrieve the static device type record from the firmware's device type database.
  2. Per-device lookup — supply a deviceid (or bus+addr) to retrieve the type record for the device actually instantiated/detected at that address, along with optional sidecar fields (name, role) that have been assigned to that specific instance.

Per-device lookup is preferred when the caller wants instance-specific metadata (e.g. the friendly name or role tag) in addition to the type description.

GET Parameter Type Required Description
type string Type-lookup mode The type name (e.g. LSM6DS) or numeric device type index.
deviceid string Per-device mode Canonical device identifier <busNum>_<hexAddr> (e.g. 1_6a). For a static device the bus number is 0.
bus string Per-device mode Bus name (e.g. I2CA) or bus number — used together with addr.
addr string Per-device mode Device address as plain hex without 0x prefix (e.g. 6a).

Note: A request with only bus (no addr) is treated as legacy type-name lookup mode (e.g. ?bus=I2CA&type=LSM6DS) for backward compatibility.

Example Requests:

# Type lookup by name
/devman/typeinfo?type=LSM6DS

# Type lookup by type index
/devman/typeinfo?type=5

# Per-device lookup (canonical id)
/devman/typeinfo?deviceid=1_6a

# Per-device lookup (bus + addr)
/devman/typeinfo?bus=I2CA&addr=6a

Example Success Response (type-lookup mode):

{
    "req": "/devman/typeinfo?type=LSM6DS",
    "devinfo": {
        "name": "LSM6DS",
        "desc": "6-Axis IMU",
        "manu": "ST",
        "type": "LSM6DS",
        "resp": {
            "b": 12,
            "a": [
                {
                    "n": "gx",
                    "t": "<h",
                    "u": "dps",
                    "r": [
                        -2000,
                        2000
                    ],
                    "d": 16.384,
                    "f": ".2f",
                    "o": "float"
                },
                {
                    "n": "gy",
                    "t": "<h",
                    "u": "dps",
                    "r": [
                        -2000,
                        2000
                    ],
                    "d": 16.384,
                    "f": ".2f",
                    "o": "float"
                },
                {
                    "n": "gz",
                    "t": "<h",
                    "u": "dps",
                    "r": [
                        -2000,
                        2000
                    ],
                    "d": 16.384,
                    "f": ".2f",
                    "o": "float"
                },
                {
                    "n": "ax",
                    "t": "<h",
                    "u": "g",
                    "r": [
                        -4,
                        4
                    ],
                    "d": 8192,
                    "f": ".2f",
                    "o": "float"
                },
                {
                    "n": "ay",
                    "t": "<h",
                    "u": "g",
                    "r": [
                        -4,
                        4
                    ],
                    "d": 8192,
                    "f": ".2f",
                    "o": "float"
                },
                {
                    "n": "az",
                    "t": "<h",
                    "u": "g",
                    "r": [
                        -4,
                        4
                    ],
                    "d": 8192,
                    "f": ".2f",
                    "o": "float"
                }
            ]
        }
    },
    "rslt": "ok"
}

Example Failure Response

{
  "req": "/devman/typeinfo?type=UnknownDevice",
  "rslt": "error",
  "error": "failTypeNotFound"
}

Other failure reasons:

  • failTypeMissing: Missing type parameter (in type-lookup mode).
  • failTypeNotFound: The specified type was not found.
  • failInvalidDeviceId: deviceid was supplied but is malformed.
  • failBusNotFound: The supplied bus name/number could not be resolved.
  • failDeviceNotFound: Per-device lookup could not find an installed/detected device at the supplied address.

Per-device lookup response

When deviceid (or bus+addr) is supplied, the response also contains the canonical fields below. The name field is omitted entirely when no friendly name is mapped, and role is omitted when the role is the default (normal).

{
    "req": "/devman/typeinfo?deviceid=1_6a",
    "rslt": "ok",
    "devinfo": { "name": "LSM6DS", "desc": "6-Axis IMU", ... },
    "dtIdx": 5,
    "name": "IMU1",
    "role": "system"
}

If the device has no type record (e.g. some statically-instantiated devices), devinfo is omitted but dtIdx, name, and role are still returned.

2. /devman/cmdraw

Description:
Sends a raw command to a device on a specified bus. Can write bytes and/or read bytes back. The device can be identified either by a canonical deviceid string or by separate bus and addr parameters — both options are supported.

Method: GET

URL Parameters:

Parameter Type Required Description
deviceid string One of deviceid or bus+addr Canonical device identifier in the form <busNumber>_<hexAddr> (e.g., 1_6a). Takes precedence if present.
bus string One of deviceid or bus+addr Bus name (e.g., I2CA) or bus number.
addr string One of deviceid or bus+addr Device address as plain hex without 0x prefix (e.g., 6a for I2C address 0x6A).
hexWr string No Hex-encoded bytes to write to the device.
numToRd int No Number of bytes to read back from the device.
msgKey string No Optional key for response correlation.

Example Requests:

# Option 1: canonical deviceid
/devman/cmdraw?deviceid=1_6a&hexWr=0F&numToRd=1

# Option 2: bus name and address
/devman/cmdraw?bus=I2CA&addr=6a&hexWr=0F&numToRd=1

Example Response:

{
    "req": "/devman/cmdraw?bus=I2CA&addr=6a&hexWr=0F&numToRd=1",
    "rslt": "ok"
}

Error Responses:

  • failBusMissing: Neither deviceid nor bus parameter provided.
  • failMissingAddr: Neither deviceid nor addr parameter provided.
  • failBusNotFound: The specified bus was not found.

3. /devman/cmdjson

Description:
Routes a JSON command to a specific device. The JSON body must include a device field that matches the configured device name or device ID string. The response only indicates whether the command was successfully dispatched; any result from command execution should be obtained via device data updates or separate API calls.

Method: GET

URL Parameters:

Parameter Type Required Description
body string Yes JSON command string; must include a device field.

Example Request:

/devman/cmdjson?body={"device":"I2CA_20","cmd":"reset"}

Error Responses:

  • failMissingBody: Missing body parameter.
  • failDeviceNotFound: The specified device was not found.
  • failNoDeviceSpecified: The JSON body did not include a device field.
  • failCmdFailed: The command failed in the device handler.

4. /devman/busname

Description:
This endpoint retrieves the bus name from a bus number. Bus numbers start from 1 and match the numbering used in device data JSON/binary messages. Only buses with valid device interfaces are numbered.

Method: GET

URL Parameters:

Parameter Type Required Description
busnum int Yes The bus number to retrieve the name for.

Example Request:

/devman/busname?busnum=1

Example Success Response:

{
    "req": "devman/busname?busnum=1",
    "rslt": "ok",
    "busName": "I2CA"
}

Error Responses:

  • failInvalidBusNum: Missing or invalid busnum parameter.
  • failBusNotFound: The specified bus number was not found.

5. /devman/devconfig

Description:
Configure polling parameters for a bus device at runtime. Supports setting the polling interval, the number of buffered samples, and the I2C bus speed override for polls. The device can be identified either by a canonical deviceid string or by separate bus and addr parameters — both options are supported. The response always includes the current values of pollIntervalUs, numSamples, busHz, and busHzSlots for the device, regardless of which parameters were changed.

Method: GET

URL Parameters:

Parameter Type Required Description
deviceid string One of deviceid or bus+addr Canonical device identifier in the form <busNumber>_<hexAddr> (e.g., 1_25). Takes precedence if present.
bus string or int One of deviceid or bus+addr Bus name (e.g., I2CA) or bus number.
addr string One of deviceid or bus+addr Device address as plain hex without 0x prefix (e.g., 25 for I2C address 0x25).
intervalUs int No Polling interval in microseconds. Must be > 0.
numSamples int No Number of poll result samples the device buffers. Must be > 0. Changing this clears any previously buffered samples.
busHz int No I2C bus speed in Hz for this device's polls. Set to 0 to revert to the default bus speed. Common values: 100000 (100 kHz), 400000 (400 kHz).
busHzSlots string No Comma-separated list of slot numbers (0–63) to which busHz applies. Omit to keep the current slot mask. Set to empty or 0 to apply to all slots. Example: 4,5,6.

At least one configuration parameter (intervalUs, numSamples, busHz, or busHzSlots) should be provided, though the endpoint can also be used to read current values without changing them.

Example Requests:

Set polling interval only:

/devman/devconfig?deviceid=1_25&intervalUs=50000

Set number of buffered samples only:

/devman/devconfig?deviceid=1_25&numSamples=10

Set both at once:

/devman/devconfig?bus=I2CA&addr=25&intervalUs=50000&numSamples=5

Set bus speed override for all slots:

/devman/devconfig?deviceid=1_6a&busHz=400000

Set bus speed override for specific slots only:

/devman/devconfig?deviceid=1_6a&busHz=400000&busHzSlots=4,5,6

Revert to default bus speed:

/devman/devconfig?deviceid=1_6a&busHz=0

Read current configuration:

/devman/devconfig?bus=I2CA&addr=25

Example Success Response:

{
    "req": "devman/devconfig?bus=I2CA&addr=25&intervalUs=50000&numSamples=5",
    "rslt": "ok",
    "deviceID": "1_25",
    "pollIntervalUs": 50000,
    "numSamples": 5,
    "busHz": 400000,
    "busHzSlots": [4, 5, 6]
}

Notes on busHz and busHzSlots in the response:

  • busHz is 0 when no bus speed override is set (default bus speed is used)
  • busHzSlots is an empty array [] when the override applies to all slots

Error Responses:

Error Cause
failAddrMissing No deviceid or addr parameter provided
failBusMissing Using addr style but no bus parameter provided
failBusNotFound Bus name or number does not exist
failInvalidDeviceID Device ID could not be parsed
failInvalidInterval intervalUs is 0
failInvalidNumSamples numSamples is 0
failUnsupportedBus The bus does not support the requested operation, or the device was not found on the bus

Notes:

  • numSamples corresponds to the "s" field in the device's pollInfo configuration. Changing it at runtime overrides the value from the DeviceTypeRecord.
  • Changing numSamples clears all previously buffered poll data for the device.
  • busHz corresponds to the "h" field in the device's pollInfo configuration. When set, the I2C bus speed is changed to this value before each poll of the device and restored to the default afterwards.
  • busHzSlots corresponds to the "hSlots" field. It limits which multiplexer slots the bus speed override applies to. This is useful when different slots have different electrical characteristics (e.g. cable length, capacitance).
  • All parameters are backward-compatible additions; existing clients that omit them are unaffected.

6. /slotcontrol/setrate

Description:
Sets the sample rate for a specific slot. An optional addr filter restricts the update to a device with the given address on that slot.

Method: GET

URL Path Format:

/slotcontrol/setrate/<slotNumber>/<rateHz>
Path Segment Type Description
slotNumber int The slot index to configure.
rateHz int The desired sample rate in Hz.

URL Parameters:

Parameter Type Required Description
addr string No Filter to a specific device address. Plain hex without 0x prefix (e.g., 25 for address 0x25). A 0x prefix is also tolerated.

Example Requests:

# Set rate for all devices in slot 2
/slotcontrol/setrate/2/10

# Set rate for the device at address 0x25 only
/slotcontrol/setrate/2/10?addr=25

7. /devman/demo

Description:
Starts a demo device instance (if enabled) with a configurable sample rate, duration, and offline behavior. Useful for testing pipelines without real hardware.

Method: GET

URL Parameters:

Parameter Type Required Description
type string No Device type name; default ACCDEMO.
rate int No Sample rate in ms (min 10, max 60000).
duration int No Duration in ms (0 for continuous).
offlineIntvS int No Offline interval seconds.
offlineDurS int No Offline duration seconds (min 1).

Example Request:

/devman/demo?type=ACCDEMO&rate=100&duration=10000

Error Responses:

  • failDemoDeviceExists: The demo device already exists.

8. /devman/setname

Description: Assign a friendly name to a device. The mapping is held in DeviceManager's in-memory name map and applies to both statically-instantiated devices and bus-detected devices. Names assigned via this endpoint are not persisted across restarts — to persist them, add a name field on the corresponding Devices entry (or a top-level DeviceNames map) in the SysType configuration.

Method: GET

URL Parameters:

Parameter Type Required Description
deviceid string Yes Canonical device identifier <busNum>_<hexAddr> (use 0_<hexAddr> for statically-instantiated devices).
name string Yes Friendly name to assign. Must be non-empty.

Example Requests:

/devman/setname?deviceid=1_6a&name=IMU1
/devman/setname?deviceid=0_0&name=MotorControl

Error Responses:

  • failDeviceIdMissing: No deviceid parameter supplied.
  • failNameMissing: No name parameter supplied (or empty).
  • failInvalidDeviceId: The supplied deviceid could not be parsed.

9. /devman/setrole

Description: Assign a role string to a device. Roles allow callers to distinguish between standard published measurement devices (default role normal) and devices that should be treated as system infrastructure (role system, e.g. a fuel gauge, charger, or RTC). The role is reflected in the per-device /devman/typeinfo response and can be used as a filter for /devman/listdevs.

The mapping is held in-memory; pass role=normal or an empty role to clear it. To assign a role persistently, set the role field on the corresponding entry in the SysType Devices array (see DeviceManager Settings).

Method: GET

URL Parameters:

Parameter Type Required Description
deviceid string Yes Canonical device identifier <busNum>_<hexAddr>.
role string Yes (may be empty) Role string; common values are normal (default) and system. Empty or normal clears the mapping.

Example Requests:

/devman/setrole?deviceid=1_36&role=system
/devman/setrole?deviceid=1_36&role=normal    # clears the role

Error Responses:

  • failDeviceIdMissing: No deviceid parameter supplied.
  • failInvalidDeviceId: The supplied deviceid could not be parsed.

10. /devman/listdevs

Description: Enumerate currently-known devices. The list contains:

  • All statically-instantiated devices (those configured via the Devices array with a class field).
  • All bus-detected devices that the bus has successfully identified.

Undetected bus addresses are intentionally not reported. An optional role filter restricts the result to devices with the supplied role string.

Each entry contains the canonical deviceid and, when set/non-default, optional name and role sidecar fields plus the dtIdx (device type index) when known.

Method: GET

URL Parameters:

Parameter Type Required Description
role string No Filter the result to devices whose role exactly matches (case-insensitive). E.g. role=system returns only system-tagged devices.

Example Requests:

/devman/listdevs
/devman/listdevs?role=system
/devman/listdevs?role=normal

Example Success Response:

{
    "req": "devman/listdevs",
    "rslt": "ok",
    "devices": [
        { "deviceid": "0_0",  "name": "MotorControl",        "dtIdx": 12 },
        { "deviceid": "1_36", "role": "system",              "dtIdx": 7  },
        { "deviceid": "1_6a", "name": "IMU1",                "dtIdx": 5  }
    ]
}

Notes:

  • name is only present in entries that have a friendly name mapped.
  • role is omitted when the role is the default (normal).
  • dtIdx is omitted when the device type has not been identified.

Home

Getting Started

Scaffolding & Building

Architecture

Built-in SysMods

Comms & Protocols

Devices & Buses

Helpers

Reference

Clone this wiki locally