Writing device profiles (Advanced JSON)

The Advanced JSON tab

• Profiles (left) lists every profile in your draft, with its address, draft state (custom draft or disabled), 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 definition from Axiom’s runtime type table.
• 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.

After clearing the draft

Clearing the draft, or removing its last profile, does not change Axiom. On Install, an empty draft offers the appropriate next step:

• If Axiom has a custom library file, Remove library & restart deletes it after a separate confirmation and returns Axiom to its built-in definitions.
• To keep Axiom's file and undo browser-only changes, use Reset draft from Axiom instead. A file that cannot be read or parsed must be recovered before this reset can be used.
• If Axiom has no custom file, there is nothing to write. If removed definitions are still running, restart Axiom to stop using them; otherwise add a profile from Catalogue to begin again.
• If the file state is unknown, refresh successfully before changing it.

Write to Axiom is disabled for an empty draft. Use the explicit removal action above if you intend to remove the device's library. Canceling either the clear confirmation or the unsaved-editor confirmation leaves your browser work unchanged. See Backup & updates for removal and reset details.

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.