Writing device profiles (Advanced JSON)

A device profile is a short piece of JSON that tells Axiom how to find, identify, set up and read a device. This page explains the format and the Advanced JSON editor, so you can write a profile for a device that isn't in the catalogue.

The Advanced JSON tab

• Profiles (left) lists every profile in your draft, with its address, origin (new, replaces built-in, …), polling interval and name. Search by name or address.
• The editor (right) shows the selected profile as JSON. The label above it tells you whether you are editing your local draft or looking at a read-only built-in definition.
• The Descriptor guide (below) is a quick reference to the fields and command syntax.

Below the editor, the page shows the draft's size and any Check messages. Checks are advice: they point out likely mistakes but don't stop you writing. The only verdict that counts is what Axiom reports after you install and restart: the rejected count and first error on the Install tab.

The library file

A library is one JSON object. Its devTypes object holds one entry per device type, keyed by the type's name:

{
  "devTypes": {
    "AHT20": { ... },
    "VL53L1X": { "disable": true }
  }
}

• A key that doesn't match a built-in profile adds a new type.
• A key that matches a built-in profile customises it: your version is tried first, with the built-in as a fallback.
• “disable”: true disables that type. If the entry also contains a full profile, it is kept but ignored until you enable it again.

Type names can use 1–48 letters, digits, underscores and hyphens (e.g. LTR-390).

A complete example: AHT20

This is the catalogue profile for the AHT20 temperature and humidity sensor:

{
  "_notes": "Temperature and humidity sensor. Data format: Status(8bit) + Humidity(20bit) + Temperature(20bit).",
  "addresses": "0x38",
  "deviceType": "AHT20",
  "detectionValues": "",
  "initValues": "0xbe0800=",
  "pollInfo": {
    "c": "=r6&0xac3300=",
    "i": 500,
    "s": 1
  },
  "devInfoJson": {
    "name": "Temperature & Humidity Sensor",
    "desc": "",
    "manu": "Asair",
    "type": "AHT20",
    "clas": ["TEMP", "RH"],
    "resp": {
      "b": 6,
      "a": [
        { "n": "status", "t": "B", "u": "", "f": "02x", "o": "uint8", "vs": false },
        { "n": "humidity", "t": ">I", "u": "%", "r": [0, 100],
          "m": "0xfffff000", "s": 12, "d": 10485.76, "f": "3.1f", "o": "float" },
        { "n": "temperature", "at": 2, "t": ">I", "u": "°C", "r": [-40, 80],
          "m": "0x000fffff", "d": 5242.88, "a": -50, "f": "3.2f", "o": "float" }
      ]
    }
  }
}

In words:

• Look for it at address 0x38. There is no identification check (detectionValues is empty), so anything at 0x38 is treated as an AHT20.
• When it's found, write 0xbe 0x08 0x00 to initialise it.
• Every 500 ms, read the 6-byte result of the previous measurement, then write 0xac 0x33 0x00 to start the next one. Keep 1 sample.
• Decode the 6 bytes as a status byte, a 20-bit humidity value and a 20-bit temperature value.

Profile fields

scanPriority and fields starting with _ (such as _notes) are accepted but not used. Profiles in a library are always scanned at the highest priority.

Command syntax

detectionValues, initValues and pollInfo.c use the same syntax. A command is a list of steps separated by & or ;. Each step is bytes to write=what happens next. The bytes before the = are written to the device as hex (the 0x is optional). What comes after the = depends on the field:

Examples:

You can test a detection command on a connected device before installing it. See Try a detection command in Testing and tuning devices.

Describing the data (devInfoJson)

Each attribute in resp.a describes one value:

For the AHT20 temperature, the steps are: read 4 bytes starting at byte 2, keep the low 20 bits, divide by 5242.88, then subtract 50.

Limits

• The connected Axiom reports how many custom profiles it can hold and how big the library can be. The Install tab shows both, e.g. 1 of 19 profiles · 1.6 KiB of 64 KiB.
• Addresses Axiom uses for its own hardware (including 0x25, 0x36 and 0x70–0x77) are reserved. The battery fuel gauge profile (MAX17048) can't be replaced or disabled.
• A profile you add needs an address (or a Robotical deviceTypeId). A library can't create devices that are wired directly to Axiom.