Thanks for helping to grow the akenza device type library! To add, remove or change a device type, submit a pull request.
Please only contribute types you have used before or are familiar with. This helps to keep the quality of the library high.
Each device type lives in its own folder types/<manufacturer>/<MODEL>/.
| File | Required | Purpose |
|---|---|---|
meta.json |
Yes | Metadata: name, manufacturer, sensors, topics, connectivity |
uplink.js |
Yes | Uplink decoder implementing function consume(event) |
uplink.spec.js |
Yes | Mocha tests for the decoder |
<topic>.schema.json |
Yes (one per topic) | JSON Schema (draft-07) describing the data of each topic |
downlink.js |
No | Downlink encoder |
downlink.schema.json |
No | Schema of the downlink payload |
<MODEL>.png |
No | Picture of the device |
- Encoder and decoder scripts must implement the akenza scripting interface. See the scripting docs.
- Reuse the shared measurement types in
data-models/via$refwherever a property matches one. - A topic always contains all of its data keys. Emit
nullfor unknown values instead of omitting them. - More guidance on structuring a device type is in the README.
Requires Node.js 20, 22 or 24 (the versions tested in CI).
npm install
cp .env.template .envnpm testRuns every *.spec.js in types/ and lib/ in-process. This is what CI runs on every pull request.
To run the tests of a single device type:
npx mocha types/<manufacturer>/<MODEL>/uplink.spec.jsTEST_MODE controls how tests run. It is read from the shell first and from .env second:
TEST_MODE |
Decoder runs | $ref schemas loaded from |
|---|---|---|
LOCAL |
in-process | local data-models/ |
INTEGRATION |
on the akenza script runner | GitHub main branch |
Keep TEST_MODE="LOCAL" in your .env (as in the template) so that npm test stays local.
Integration tests send every decoder and test payload to the akenza script runner API and assert on what it returns. This catches differences between Node.js and the akenza runtime, for example the runtime timezone (UTC) or floating point results.
-
Set
SCRIPT_RUN_URLandAPI_KEYin your.env(or export them in your shell):SCRIPT_RUN_URL="https://api.akenza.io/v3/run-script" API_KEY="<your akenza API key>"
-
Run all tests against the script runner:
npm run integration-test
To stop at the first failing test, or to run a single device type:
TEST_MODE=INTEGRATION npx mocha --bail "types/**/*.spec.js" "lib/**/*.spec.js" TEST_MODE=INTEGRATION npx mocha types/<manufacturer>/<MODEL>/uplink.spec.js
Never commit .env or your API key.
Integration tests are not run in CI, so please run them for the device types you changed. When writing tests that hold up in both modes:
- Compare floating point values with
assert.closeToinstead ofassert.equal. - Don't depend on the timezone of the machine. Build expected dates in UTC, e.g.
new Date("2026-02-03T15:15:00Z").
Code is formatted with Prettier (double quotes, 2-space indentation, trailing commas) and linted with ESLint:
npx prettier --write types/<manufacturer>/<MODEL>
npx eslint types/<manufacturer>/<MODEL>- Add an entry to
CHANGELOG.md. This is enforced by a GitHub Action; maintainers can skip it with theSkip-Changeloglabel. - Make sure
npm testpasses, and ideally the integration tests for the types you changed. - Every PR must be approved by at least one code owner. The code owners review your PR and tag it if information is missing. They wait 8 days for your response, after that the PR is closed.
Please open an issue if you would like to discuss improvements or have suggestions.