ChangingDeviceTypeSupport

Changing Which Devices Your Firmware Supports

Start here if you want to add, remove or adjust the I2C sensors and other devices your Raft firmware recognises, without changing the Raft libraries. Each task gives the short answer and links to the full reference.

Background in one paragraph: each device type (for example an SHT40 humidity sensor) is described by a device type record, a JSON file in RaftCore's devtypes/records/. A project chooses which records are compiled in with a DeviceTypeSources.json file in its SysType folders. Records can also be added to a device without rebuilding, in a device type file pushed to the device. Board-specific choices such as poll rate and bus speed are set in the SysType, not in the record.

---

See which device types exist

• In a browser: the Device Types app lists every RaftCore record, for each release and for main. Search by name, manufacturer, class or I2C address. See Raft Web Apps.
• In the repo: devtypes/records/, one <Key>.json per device type.
• Which breakout board uses which record: devtypes/breakouts/breakouts.csv lists STEMMA QT, Qwiic, Grove and similar boards and the record that supports each, and tests.csv what has been checked on real hardware.
• For your project: raft devtypes list -s <SysType> shows what your build selects.

Choose which device types are built into the firmware

Put a DeviceTypeSources.json in systypes/Common/ or systypes/<SysType>/ (the SysType's file adds to Common's):

{
    "sources": { "raftcore": { "bundled": true } },
    "builtin": { "include": ["raftcore:@common", "raftcore:MCP9808"] }
}

• "raftcore:@common" (about 10 popular sensors) or "raftcore:@extended" (about 25) are ready-made sets. "raftcore:*" is every record.
• Add or remove single records by key: "raftcore:<Key>" in include or exclude.
• Or from the command line: raft devtypes init, raft devtypes add <Key>, raft devtypes remove <Key> (with -s <SysType>).
• Then rebuild. A key that doesn't exist stops the build with a message.
• Fewer records means a smaller build and fewer chances of a wrong match at a shared address, so select only what the product can have attached.

Projects with no DeviceTypeSources.json work as before: /devtypes/DeviceTypeRecords.json in DEV_TYPE_JSON_FILES (in features.cmake) means every RaftCore record. Don't use both methods.

Reference: Selecting Device Types.

Use your own version of a record, or a record of your own

• Change a RaftCore record for one project: copy its file into a folder in your project, add that folder as a source ("local": { "path": "devtypes" }), and include "local:*". Your copy replaces RaftCore's, with a build message.
• Add a new device type: raft devtypes new <Key> --address 0xHH creates a record file to fill in. Adding an I2C Device Type walks through writing one, and Device Type Record Format is the full format.
• Share records between projects: put them in a git repo and add it as a git source; the commit used is pinned in a lock file. See Git sources.
• Contribute it to RaftCore so every project can use it: a pull request adding devtypes/records/<Key>.json, and a row in the breakout list if it's for a breakout board.

Turn a device type off without removing it

Add a policy in builtin: "policy": { "TrillRing": "disabled" }. The record stays in the build but isn't used to identify devices. See typePolicy.

Change poll rate, bus speed or sample rate for your board

Don't edit the record. Set it for the type in the SysType's DeviceManager typeSettings:

"typeSettings": {
    "LSM6DS3": { "busHz": 400000, "busHzSlots": "1,2,3,4,7" },
    "VL6180": { "intervalUs": 50000, "scanPriority": "low" }
}

Settings: intervalUs, numSamples, busHz, busHzSlots, sampleRateHz, scanPriority. See DeviceManager Settings: typeSettings.

Add device types to a device without rebuilding the firmware

Use a device type file, loaded by the device at startup:

• In the browser: in the Device Types app, connect to the device (Bluetooth or USB serial, Chrome or Edge), pick the records, then build and push the file.
• From a project: list the records under typeFile in DeviceTypeSources.json, then raft devtypes push <device>.
• Install it with the firmware: add "fsImage": true under typeFile, and a full raft flash (not --no-fs, not OTA) installs it.

A type file has a size limit (256 KB with PSRAM, 64 KB without). Records with custom decode code only decode on the device if the firmware has the code interpreter. See Runtime type files.

Select a record that has a warning

A few records affect other devices on the bus. For example, selecting the CaliPile makes the bus send an I2C general call on every slot. Wildcards and sets don't select these records. Name the record in include, and add its key to "acknowledge": ["CaliPile"] to accept the warning. See Records with a warning.

Fix a device that's identified as the wrong type

Several chips share some I2C addresses, and a few records have little or no ID check, so they claim whatever is at their address. For example, the MPRLS record claims any device at 0x18.

• Leave out records your product doesn't need (exclude), so they can't claim the address.
• If both records are needed, the one with the higher identPriority is tried first. Set it in your own copy of the record, or raise it in a pull request.
• The Device Types app shows what the device found at each address, and catalogue records for addresses it couldn't identify. From a script, devman/listdevs lists the devices found and their types, and devman/identinfo shows how one was identified.

See I2C Device Identification and Polling.

When the online catalogue and app update

The GitHub Pages site is rebuilt automatically when a change to devtypes/ is merged to RaftCore main, and on each RaftCore release. Each release's records stay published. The Device Types app is built from the raftjs version pinned in the site's workflow. See Raft Web Apps.