This repository contains the necessary tools and guidelines for creating and managing decoders for the TagoIO platform. Decoders are scripts that interpret the payload data from an IoT Device or protocol and convert it into a TagoIO data format.
-
Validating your decoder manifest:
npm start validator
-
Running Unit Tests:
npm test
-
Running Linter:
npm linter
The project follows this folder structure:
./decoders/
: This directory contains the network and connector decoders../network/network-name/
: This directory should be named with the network name/model../connector/manufacturer-name/
: This directory should be named after the manufacturer of the device for which the decoder is being created. It groups together all decoders related to the specific manufacturer../connector/manufacturer-name/sensor-name/
: This directory should be named after the specific sensor or device model for which the decoder is being created. It contains all versions of the decoder for that specific sensor or device model.
./schema/
: This directory contains the JSON schemas for the network and connector decoders.
Manifests are JSONC files that describe the details of each version of a decoder. They are essential for ensuring that the decoder is correctly identified and processed by the TagoIO platform.
- Manifest File:
network.jsonc
- Details File:
network_details.jsonc
- Manifest File:
connector.jsonc
- Details File:
connector_details.jsonc
Here's an example of a connector.jsonc
file for a connector decoder:
{
"$schema": "../../../schema/connector.json",
"name": "Abeeway Compact Tracker",
"images": {
"logo": "./assets/logo.png"
},
"versions": {
"v1.0.0": {
"src": "./v1.0.0/payload.js",
"manifest": "./v1.0.0/payload-config.jsonc"
}
}
}
Here's an example of a connector_details.jsonc
file for a connector decoder:
{
"$schema": "../../../schema/connector_details.json",
"description": "./description.md",
"install_text": "**Compact tracker**\n\nMulti-mode tracker with embedded sensors combining GPS, Low-power GPS, Wi-Fi Sniffer, BLE",
"device_annotation": "",
"device_parameters": [
{
"name": "beacon_decoder",
"type": "dropdown",
"label": "Beacon decoder type",
"group": "main",
"options": [
{
"is_default": false,
"label": "One variable with all beacons",
"value": "simple"
},
{
"is_default": true,
"label": "Split beacon in different variables",
"value": "splitted"
}
]
}
],
"networks": [
"../../../network/lorawan-actility/v1.0.0/payload.js",
"../../../network/lorawan-chirpstack/v1.0.0/payload.js",
"../../../network/lorawan-citylink/v1.0.0/payload.js",
"../../../network/lorawan-helium/v1.0.0/payload.js",
"../../../network/lorawan-everynet/v1.0.0/payload.js",
"../../../network/lorawan-kerlink/v1.0.0/payload.js",
"../../../network/lorawan-loriot/v1.0.0/payload.js",
"../../../network/lorawan-machineq/v1.0.0/payload.js",
"../../../network/lorawan-senet/v1.0.0/payload.js",
"../../../network/lorawan-swisscom/v1.0.0/payload.js",
"../../../network/lorawan-ttn/v1.0.0/payload.js",
"../../../network/lorawan-twtg/v1.0.0/payload.js",
"../../../network/lorawan-twtg/v3/v1.0.0/payload.js",
"../../../network/lorawan-brodt/v1.0.0/payload.js"
]
}
-
Create a new folder:
- Navigate to
./decoders/network/
and create a new folder named after your network decoder.
- Navigate to
-
Create the manifest file:
- Inside this folder, create a
network.jsonc
file. Follow the structure defined innetwork.json
.
- Inside this folder, create a
-
Create version folders:
- For each version of your network decoder, create a new folder inside your network decoder's folder. Name the folder with the version number.
- The pattern utilized for versioning is the SemVer
-
Create version manifest files:
- Inside each version folder, create a
manifest.jsonc
file. Follow the structure defined innetwork_details.json
.
- Inside each version folder, create a
-
Create a new folder:
- Navigate to
./decoders/connector/
and create a new folder named after the manufacturer and the name of your connector decoder.
- Navigate to
-
Create the manifest file:
- Inside this folder, create a
connector.jsonc
file. Follow the structure defined inconnector.json
.
- Inside this folder, create a
-
Create version folders:
- For each version of your connector decoder, create a new folder inside your connector decoder's folder. Name the folder with the version number.
- The pattern utilized for versioning is the SemVer
-
Create version manifest files:
- Inside each version folder, create a
manifest.jsonc
file. Follow the structure defined inconnector_details.json
.
- Inside each version folder, create a
-
Create a new branch:
- Create a new branch for your decoder.
-
Add your decoder:
- Follow the instructions above to add your decoder.
-
Validate your manifest:
- Run the command
npm start validator
to check if all data in the manifest file is correct.
- Run the command
-
Commit your changes:
- Commit your changes and open a pull request for review.
-
Review and feedback:
- Wait for the Pull Request to be reviewed. You may need to make some changes based on the feedback you receive.
-
Merge your changes:
- Once your Pull Request is approved, it will be merged into the main codebase.
For more detailed information, please refer to the examples provided in the repository and the schema files located in the ./schema/
directory.