DeviceManagerRESTAPI

DeviceManager REST API

The API for DeviceManager is included in the Raft API List

Naming a device type

Endpoints that take a device type accept:

• deviceTypeKey=<key> - the device type key, e.g. MPU6050 (the key of the record in devTypes). Canonical.
• deviceTypeIndex=<n> - the device type index (dtIdx, devjson _i). Canonical. An index is valid for one boot of one firmware build: look it up again after a restart.
• type=<key or index> - the older form, still accepted: a value starting with a digit is tried as an index, then as a key.

If more than one is given, deviceTypeIndex is used, then deviceTypeKey, then type. Responses give the type as deviceTypeKey and dtIdx.

1. /devman/typeinfo

Description:

This endpoint operates in two modes:

1. Type lookup — supply a type parameter (device type key 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
deviceTypeKey or deviceTypeIndex (or type)	string	Type-lookup mode	The device type (see Naming a device type), e.g. deviceTypeKey=LSM6DS3 or deviceTypeIndex=5.
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).
full	0/1	No	1: also return the whole record as record - {"<key>":{...}} in the device type file format, so it can be copied into a type file and loads as the same record.

Per-device mode also returns displayName (see devman/listdevs).

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

Example Requests:

# Type lookup by device type key
/devman/typeinfo?deviceTypeKey=LSM6DS3

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

# The older form (key or index)
/devman/typeinfo?type=LSM6DS3

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

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

Both modes give decoder: where the record's on-device poll decoder comes from - compiled (built into the firmware), runtime (made from its attributes, firmware with RAFT_RUNTIME_DECODE), runtimePending (made when a device of the type is first identified), runtimeFailed (couldn't be made when it was needed; decoderProblem gives the reason) or none (only clients such as raftjs decode its data). See Device Type Record Format.

Example Success Response (type-lookup mode):

{
    "req": "/devman/typeinfo?type=LSM6DS3",
    "deviceTypeKey": "LSM6DS3",
    "decoder": "compiled",
    "devinfo": {
        "name": "LSM6DS3",
        "desc": "6-Axis IMU",
        "manu": "ST",
        "type": "LSM6DS3",
        "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.

The device type key

Both modes return deviceTypeKey: the device type key of the record (the key of the record in devTypes, e.g. LSM6DS3), which identifies the record. Use it rather than devinfo.type, which is a copy that can differ from the key, and rather than devinfo.name, which is the name shown to users and need not be unique. deviceTypeKey is returned by firmware from October 2026 onwards and is omitted if the device has no type record.

Both modes also return src - where the record comes from: base (compiled in), override (added at runtime with a compiled record's key, replacing it at its index) or extended (added at runtime with its own index) - and policy: enabled, disabled or disabledClaim, whether the record is used for identification (see typePolicy). Both are omitted when deviceTypeKey is.

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": "LSM6DS3", "desc": "6-Axis IMU", ... },
    "dtIdx": 5,
    "deviceTypeKey": "LSM6DS3",
    "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.
hexWrs	string	No	Several writes sent as a batch, comma separated (e.g. a950,7008,7483,a940): one after the other with nothing else on the bus between them - no poll of this or any other device - so an action of several writes can't have a poll in the middle (one that selects a register bank, writes, and selects the normal bank again, say). Up to 32. Used in place of hexWr; a read (numToRd) follows the last write. From RaftCore 1.65.0 and RaftI2C 1.25.0
numToRd	int	No	Number of bytes to read back from the device. When non-zero the response is sent when the read completes and contains the data as rdData.
timeoutMs	int	No	How long to allow for the bus transaction (default 1000 ms, maximum 60000 ms). See the note on deferred responses below.
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",
    "rdData": "6a"
}

rdData (hex) is only present when numToRd is non-zero. A write-only request (numToRd omitted or 0) returns "rslt": "ok" once the write has completed on the bus, or the bus error (e.g. BUS_ACK_ERROR if no device acknowledged).

A batch (hexWrs) replies once, after its last write, with "numWr": the number of writes sent; the first write that failed, if any, gives the error. Firmware without batches ignores hexWrs (writing nothing), and its reply has no numWr - raftjs then sends an action's writes one at a time.

A request to a device whose access is barred for the moment - during a pause in the device's poll, e.g. while it measures - waits until the bar ends (up to 2 s), and the requests queued behind it with it, rather than failing (RaftI2C 1.25.0; earlier firmware fails it with BUS_BARRED).

Error Responses:

• failBusMissing: Neither deviceid nor bus parameter provided.
• failMissingAddr: Neither deviceid nor addr parameter provided.
• failBusNotFound: The specified bus was not found.
• failDeviceNotOnBus: The device is not on a bus (e.g. a directly-connected device).
• failBusQueueFull: The bus request queue is full.
• failBadHexWrs: A hexWrs write is empty or not whole hex bytes, or there are more than 32.
• BUS_ACK_ERROR, BUS_SW_TIME_OUT, ...: The bus transaction failed (e.g. no device acknowledged at the address).
• timeout: The bus transaction did not complete within timeoutMs.
• readTimeout: The read did not complete in time (non-deferred transports only, see below).

Deferred responses

A command does not block the main loop. The response is sent when the bus transaction (write and/or read) completes, so it reports the actual result, or with "error":"timeout" after timeoutMs. It is still a single response to the original request:

• HTTP GET: the HTTP response is sent when the read completes (status 200 in all cases, including timeout).
• WebSocket, BLE and serial (RICSerial frames, e.g. raftjs): the response carries the request's message number so the client matches it as usual. A resent request with the same message number is ignored while the original is pending.
• Serial console and remote-control socket (typed commands): the response line is printed when available.
• Command files (.api): the response is discarded.

Transports which cannot defer a response (e.g. MQTT) fall back to the earlier behaviour: a read waits on the main loop (capped at 20 ms, and can return readTimeout) and a write returns ok once it is queued. The sysmoddebug/RestAPI endpoint returns counters for deferred responses (pend pending, def deferred, cmpl completed, tout timed out, unk late completions).

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. Commands for a device on a bus take hexWr and numToRd fields, as for /devman/cmdraw.

For a bus device, the response is sent when the bus transaction completes and contains the result (with rdData if numToRd is in the body) or the bus error (a deferred response, as for /devman/cmdraw). Otherwise 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.
timeoutMs	int	No	How long to allow for a command to a bus device (default 1000 ms). Can also be given in the body.

Example Request:

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

# Read 1 byte from register 0x75 of the bus device 1_68
/devman/cmdjson?body={"device":"1_68","hexWr":"75","numToRd":1}

The body value should be URL-encoded when sent over HTTP.

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.
• failBusQueueFull, bus errors (e.g. BUS_ACK_ERROR) and timeout: as for /devman/cmdraw (bus devices).

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.
sampleRateHz	number	No	Requested device sample rate. Looked up in the device's _conf.* action map (see DeviceTypeRecordFormat). Applies all three together: writes the mapped w bytes to the device, and sets the poll interval and retained-sample count from that entry's i (microseconds) and s. An entry without w only sets the polling (a device whose rate is how often it's read, e.g. the SCD30). An explicit intervalUs or numSamples in the same request overrides the mapped value. A rate that isn't in the map fails with failInvalidSampleRate.
save	0/1	No	1: save the device's settings (those set by this and earlier devconfig requests for its type) in the device settings file, so they are applied again after a restart. The response then has saved. Without it they are applied again when the device is identified again as the same type, until the restart.

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

Prefer sampleRateHz over setting intervalUs yourself for any device that declares a _conf.rate action. The device rate and the master's poll interval must move together: writing the device rate alone leaves the master polling at its old interval, and if the device then produces more samples per poll than one read can carry, the excess is silently dropped. That coupling is the reason such actions are named _conf.* rather than plain actions.

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 a device sample rate (moves the poll interval with it):

/devman/devconfig?deviceid=1_25&sampleRateHz=100

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
deviceTypeKey (or type)	string	No	Device type key; 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?deviceTypeKey=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. With save=1 the name is also saved in the device settings file and applied again after a restart; without it the name lasts until the restart. A name can also be set in the SysType configuration (a name field on the Devices entry, or a top-level DeviceNames map).

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.
save	0/1	No	1: save it (kept over a restart).

Example Requests:

/devman/setname?deviceid=1_6a&name=IMU1
/devman/setname?deviceid=0_0&name=MotorControl
/devman/setname?deviceid=1_6a&name=Arm%20IMU&save=1

Error Responses:

• failDeviceIdMissing: No deviceid parameter supplied.
• failNameMissing: No name parameter supplied (or empty).
• failInvalidDeviceId: The supplied deviceid could not be parsed.
• failSave: The name was set but the device settings file couldn't be written.

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.

Pass role=normal or an empty role to clear it. With save=1 the role is also saved in the device settings file; a role can also be set with the role field of the device's 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.
save	0/1	No	1: save it (kept over a restart).

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, its displayName 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", "displayName": "MotorControl", "dtIdx": 12 },
        { "deviceid": "1_36", "displayName": "Fuel Gauge 1_36", "role": "system", "dtIdx": 7 },
        { "deviceid": "1_6a", "name": "IMU1", "displayName": "IMU1", "dtIdx": 5 }
    ]
}

Notes:

• name is only present in entries that have a friendly name mapped.
• displayName is the name to show for the device: its name if it has one, otherwise its type's display name (devInfoJson.name, or the device type key) and its device ID. Clients should show this rather than forming their own.
• role is omitted when the role is the default (normal).
• dtIdx is omitted when the device type has not been identified.

---

11. /devman/typefile

Description:

Reports what was done with the device type file at startup, checks a file without applying it, and applies a file (by restarting - the reply is sent first).

Request	Does
devman/typefile	Status. entries=1 adds entries: what happened to each entry of the file at startup
devman/typefile/check?file=<path>	What the file would do at the next startup, entry by entry, without changing anything (default file: the device type file). The file is applied to a scratch table holding what the device's table holds before its type file is loaded - the compiled records, records registered by code, protected types and the same limits - so the result is what a restart would give
devman/typefile/apply	Restart to apply the device type file
devman/typefile/apply?file=<path>	Check the file first; if nothing in it is rejected, it becomes the device type file (it is moved to the device type file's path) and the device restarts. Otherwise nothing changes, and the response is rslt fail, error failCheck, with the check's fields

Timing: a check (and the check an apply?file= makes) runs in a background task using only spare processor time, so it takes a few seconds (about 4 s for a file of 45 records on an Axiom), longer for records with custom code. Where the connection supports deferred responses (HTTP, serial console, BLE and WebSocket via RICREST) it doesn't hold up the device: the file is read a chunk at a time, the check runs in the background, and the reply comes when it is done (allow up to 60 s). Otherwise the check is done before replying. Only one check or apply runs at a time; a second gets failBusy.

Uploading a new file safely: upload it under another name (e.g. /local/devlib.new.json with fileupload), devman/typefile/check?file=/local/devlib.new.json to see what it does, then devman/typefile/apply?file=/local/devlib.new.json, and after the restart devman/typefile (its crc is the uploaded file's). A file with an error never replaces the one in use.

Example Requests:

/devman/typefile
/devman/typefile?entries=1
/devman/typefile/check?file=/local/devlib.new.json
/devman/typefile/apply?file=/local/devlib.new.json
/devman/typefile/apply

Example Success Response:

{
    "req": "devman/typefile",
    "file": "/local/devlib.json",
    "state": "applied",
    "present": true,
    "applied": true,
    "crc": "2c68",
    "added": 1, "replaced": 1, "unchanged": 0, "disabled": 1, "rejected": 1, "warnings": 0,
    "firstError": "BenchBad: detectionValues BadCheck at 7",
    "firstWarning": "",
    "records": 1, "maxRecords": 256, "bytes": 1015, "maxBytes": 262144,
    "maxFileBytes": 65536,
    "identReady": true,
    "raftCore": "1.62.0", "recordFormat": 1, "decode": {"attrs": true, "code": false},
    "rslt": "ok"
}

Fields:

Field	Meaning
state	none (no file), missing (no file, and typeFileRequired), error (the file couldn't be read or isn't valid JSON with a devTypes object), applied, or loading
present	A file was found at startup
applied	Something from the file is in effect
crc	CRC16-CCITT of the file as loaded - the algorithm of filehash, so comparing the two tells whether the file on disk is the one in effect
added, replaced, unchanged, disabled, rejected, warnings	Records added, compiled records overridden, records identical to one present, types disabled, entries rejected, and warnings
firstError, firstWarning	"<key>: <reason>" for the first entry rejected (or the reason the file was), and the first warning
records, maxRecords, bytes, maxBytes	Extended records in use (from the file and static devices) and their limits
runtimeDecoders, decoders, decodersFailed, decoderBytes, maxDecoderBytes	When runtime decoders are made (typeTable runtimeDecoders), how many have been made, how many couldn't be when needed, the bytes they use and the limit (-1: none)
identReady	Devices are being identified (the file has been loaded, or its timeout has passed)
restartRequired	The file on disk differs from the one loaded at startup (or the device has changed it): devman/typefile/apply (a restart) is needed to apply it. A client making several changes can restart once, when it chooses
raftCore, recordFormat, decode	The firmware's rules (RaftCore 1.62.0 and later): its RaftCore version, the record format its loader reads (the formatVersion of a source's raftdevtypes.json), and the on-device decoding built in - decode.attrs from a record's attributes (RAFT_RUNTIME_DECODE), decode.code custom decode and init code (RAFT_RUNTIME_DECODE_CODE). A client building a type file for the device uses them to choose records and say which will be decoded on the device
entries	(entries=1, and in a check) One per entry of the file: key, outcome (added, replaced, unchanged, disabled or rejected), error (why it was rejected), warnings, and noDecoder: true for a record with data but no on-device decoder - a new record, or an override whose response layout differs from the compiled record's, in firmware without runtime decoding (or with custom decode code, resp.c, which needs the code interpreter). raftjs and the WebUI decode such a record; DataLogger, RaftROS and named values don't. Also decoder (compiled, runtime, runtimePending or none) for a record with data that was added or replaced: where its on-device decoder comes from

Check response

{"req":"/devman/typefile/check?file=/local/devlib.new.json","file":"/local/devlib.new.json","bytes":1166,"crc":"20da",
 "valid":true,"added":1,"replaced":1,"unchanged":0,"disabled":1,"rejected":0,"warnings":0,"firstError":"","firstWarning":"",
 "entries":[{"key":"Gadget","outcome":"added","noDecoder":true},{"key":"MPU6050","outcome":"replaced"},{"key":"TrillRing","outcome":"disabled"}],
 "rslt":"ok"}

valid is true when the file is a device type file and nothing in it is rejected. failFileNotFound or failFileTooBigOrUnreadable if the file can't be read.

Error Responses:

• failNoTypeFile: apply with no type file configured.
• failBusy: another check or apply is in progress.
• failCheck: apply?file= and the file has something rejected (the response has the check's fields). Nothing is changed.
• failTypeFileWrite: apply?file= and the file couldn't be moved or copied to the device type file's path.

/devlib

The same status with the fields of the device library endpoint of the feature/device-library firmware: file, present, applied, appliedCrc16, added (records in effect from the file), suppressed (types disabled), rejected, maxRecords (extended records free for the file), maxFileBytes and firstError.

---

12. /devman/reident

Description:

Identifies devices again. A device that is identified keeps its type, and is polled as before, until a different result is known: if the same type matches nothing changes (it isn't initialised again); if another type matches it is initialised and reported as TypeChanged; if nothing matches it is reported as Lost. A device that isn't identified is tried at once. Devices identified by an identification hook (e.g. Robotical RSAOs) are identified again by the hook, which probes them, as other devices are (RaftI2C 1.22.0 and later; before that, only when asked for by deviceid).

URL Parameters (one of):

Parameter	Description
deviceid (or bus + addr)	One device
deviceTypeKey or deviceTypeIndex (or type)	Devices identified as this type (see Naming a device type)
all=1	Every bus device
unidentified=1	Devices not identified

Example Requests:

/devman/reident?deviceid=1_68
/devman/reident?deviceTypeKey=MPU6050
/devman/reident?all=1

Example Success Response:

{"req":"devman/reident?all=1","buses":2,"rslt":"ok"}

buses is the number of buses that accepted the request; the work is done on each bus's task straight after.

---

13. /devman/typepolicy

Description:

Sets a device type's policy at runtime, and identifies the devices it affects again: devices identified as the type if it is no longer enabled (they become another type, or Lost), and devices identified as a type it now outranks if it is enabled. Unidentified devices are tried again at once. This includes devices identified by an identification hook (e.g. a Robotical RSAO type that is disabled is Lost at once - RaftI2C 1.22.0 and later); a hook-identified device is never treated as outranked by an address-based type.

URL Parameters:

Parameter	Description
deviceTypeKey or deviceTypeIndex (or type)	The device type (see Naming a device type)
policy	enabled, disabled or disabledClaim
save	1: also set it in the device type file ("disable": true or "claim" in the type's entry; for enabled, "disable" is removed). The rest of the file is kept as it is. The change made now applies at once; the file is applied by the next restart, and the response and devman/typefile report restartRequired

Without save the policy lasts until the restart. A policy can also be set with typePolicy in the settings.

Example Request and Response:

/devman/typepolicy?deviceTypeKey=APDS9960&policy=disabled

{"req":"devman/typepolicy?deviceTypeKey=APDS9960&policy=disabled","deviceTypeKey":"APDS9960","policy":"disabled","rslt":"ok"}

Error Responses:

• failTypeNotFound, failUnknownPolicy, failProtected (a type a system device expects - see expectType - can't be disabled).
• With save=1: failNoTypeFile (no type file is configured), failTypeFileRead, failTypeFileWrite.

---

14. /devman/types

Description:

The device type table, a page at a time: each type's index, key, where its record comes from (base compiled in, override a compiled record replaced by the type file, extended added at runtime) and its policy. generation increases whenever the table changes. A type a system device expects (expectType) has "protected":true: it can't be overridden or disabled (RaftCore 1.62.0 and later).

URL Parameters:

Parameter	Description
offset	First entry (default 0)
count	Number of entries (default 50, at most 200)

Example Request and Response:

/devman/types?offset=0&count=2

{"req":"devman/types?offset=0&count=2","total":53,"generation":1,"types":[{"dtIdx":0,"key":"RoboticalLightSensor","src":"base","policy":"enabled"},{"dtIdx":1,"key":"RoboticalServo","src":"base","policy":"enabled"}],"rslt":"ok"}

The whole record of a type, in the device type file format (so it can be copied into a type file), is returned by devman/typeinfo?deviceTypeKey=<key>&full=1 (or deviceid=<id>&full=1) as record.

---

15. /devman/identinfo

Description:

How a bus device is being identified.

URL Parameters:

Parameter	Description
deviceid (or bus + addr)	The device

Example Response:

{"req":"devman/identinfo?deviceid=1_229","deviceID":"1_229","ident":{"online":"online","state":"identified","attempts":0,"nextInMs":0,"dtIdx":1,"polled":true,"reverify":false,"reident":false,"hookDeclined":false,"candidates":[{"dtIdx":1,"key":"VL6180"},{"dtIdx":2,"key":"VL53L0X"}],"hook":true},"rslt":"ok"}

Field	Meaning
online	The bus element's state (online, offline, ...)
state	pending, identified, deferred (an identification hook asked to be asked again), noMatch, busError or initFailed
attempts	Attempts with the current outcome (they set the retry backoff)
nextInMs	Time to the next attempt (0 if none is due or it is due now)
dtIdx	The type it is identified as (omitted, or invalid, if none)
polled	It is being polled (false while polling is stopped with devman/devenable)
reverify, reident	Its type is being checked after a poll error, or it is waiting to be identified again
hookDeclined	The identification hook has said twice that it isn't its device, so it isn't offered to the hook again (the hook's probe can change an ordinary device) until it goes offline and comes back, it is asked for with devman/reident?deviceid=, or the hook's claims change. Records are still tried (RaftI2C 1.22.0 and later)
candidates	The types tried at its address, in the order they are tried
hook	An identification hook is registered for its address

failDeviceNotOnBus for a device that isn't on a bus (a static device), failNotSupported for a bus that doesn't report identification.

---

16. /devman/reinit

Description:

Runs a device's initialisation (its initValues) again, without identifying it again; its devconfig settings are then applied again. The work is done on the bus task. Where the connection supports deferred responses (HTTP, serial console, BLE and WebSocket via RICREST) the response is sent when it is done, with rslt ok, or fail and error failInit (a bus error) or failTimeout (5 s); otherwise the response is sent at once with "queued":true.

URL Parameters:

Parameter	Description
deviceid (or bus + addr)	The device

Example Request and Response:

/devman/reinit?deviceid=1_68

{"req":"/devman/reinit?deviceid=1_68","rslt":"ok"}

failDeviceNotOnline if the device isn't identified and online.

---

17. /devman/devenable

Description:

Stops or resumes polling one device. The device stays identified (it is still in listdevs and can still be sent commands); only its polling, and so its published data, stops. The setting is kept while the device is offline, and applied when it is identified again; with save=1 it is also kept over a restart.

URL Parameters:

Parameter	Description
deviceid (or bus + addr)	The device
poll	0 stop polling, 1 resume. Omit to query
save	1: save it in the device settings file

Example Request and Response:

/devman/devenable?deviceid=1_68&poll=0&save=1

{"req":"/devman/devenable?deviceid=1_68&poll=0&save=1","deviceID":"1_68","poll":false,"online":true,"saved":true,"rslt":"ok"}

online is whether the device was online, so the change applied at once (otherwise it applies when the device is identified).

---

18. /devman/reserved

Description:

The addresses device type records identify devices at - re-addressable devices (e.g. Robotical RSAOs) keep off them. A system module may reserve further addresses of its own, which aren't listed here.

Example Response:

{"req":"devman/reserved","addrs":["0x10","0x11","0x68"],"rslt":"ok"}

---

19. /devman/busstatus

Description:

Diagnostics for each bus: poll and scan statistics are reported here (there are no separate poll or scan statistics endpoints).

URL Parameters:

Parameter	Description
busnum	One bus (default: every bus)
reset	1: restart the poll timing statistics after reporting them

Response (per bus, under buses.<busName>):

Field	Meaning
pollIntegrity	Poll responses checked, failed, recovered and dropped, and bus recoveries
pollLoadPct	Share of bus time the configured polls need
activity	The bus task over the last window: passes, busy time and its split (us: scan, poll, requests, multiplexer IO), probes and poll steps
pollTiming	By address: configured and measured poll interval (mean, min, max, 95th percentile error, histogram), missed polls, rate and bus time per poll
identTiming	By address: when it was first seen, came online and was identified (ms since startup), attempts and identification state
scan	Scan mode, priority list sizes, background addresses, scan share in use, probe counts, multiplexer slots (slots, slotsKnown, slotsChanged, slotCycle) and multiplexer checks and rescans - see I2C Device Scanning