Skip to content

DeviceManagerRESTAPI

Rob Dobson edited this page Apr 2, 2026 · 31 revisions

DeviceManager REST API

The API for DeviceManager is included in the Raft API List

1. /devman/typeinfo

Description:

This endpoint is used to retrieve detailed information about a specific device type on a given bus. It returns information such as the device's capabilities, status, and configuration details.

GET Parameter Type Required Description
type string Yes The type name of the device to retrieve information for.

Example Request:

/devman/typeinfo?type=LSM6DS

Example Success Response:

{
    "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.
  • failTypeNotFound: The specified type was not found.

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.

Clone this wiki locally