truvami Decoder is a command-line interface (CLI) tool written in Go for decoding truvami payloads. This reference implementation supports various payload types, including Nomad XS and different Tag formats. 🛠️
Check out this demo to see truvami Decoder in action! 👇
- 🔍 Payload Decoding: Decode Nomad XS, Tag S/L, and Tag XL payloads with ease.
- 🌐 HTTP Server: Start a local HTTP server to decode payloads using RESTful APIs.
- 📄 Flexible Output: Choose between standard console output and JSON format.
- 🛠️ Debugging & Verbosity: Enable debugging and verbose output for detailed insights.
- 🖋️ Autocompletion: Generate autocompletion scripts for your favorite shell.
- 🚀 Cross-Platform: Works on Windows, macOS, and Linux.
You can install the truvami Decoder binary easily using the following command:
# This will install the binary at $(go env GOPATH)/bin/decoder
curl -sSfL https://raw.githubusercontent.com/truvami/decoder/main/install.sh | sh -s -- -b $(go env GOPATH)/bin
# ✅ Verify the installation by checking the help
decoder --helpYou can also run the truvami Decoder using Docker:
# Pull the latest Docker image
docker pull ghcr.io/truvami/decoder
# Run the Docker container
docker run -it ghcr.io/truvami/decoder decoder --help
# Run the Docker container to start the HTTP server
docker run -p 8080:8080 ghcr.io/truvami/decoder decoder http --port 8080 --host 0.0.0.0truvami Decoder provides a variety of commands and options to help you decode payloads efficiently. Below is an overview of the available commands and flags.
decoder [command] [flags]completion- 🖋️ Generate the autocompletion script for the specified shell.help- ℹ️ Display help information about any command.nomadxs- 🧩 Decode Nomad XS payloads.tagsl- 🏷️ Decode Tag S / L payloads.tagxl- 🏷️ Decode Tag XL payloads.http- 🌐 Start local HTTP server to decode payloads.
-d, --debug- 🐛 Display debugging output in the console. (default: false)-h, --help- ℹ️ Display help information.-j, --json- 📄 Output the result in JSON format. (default: false)-v, --verbose- 📢 Display more verbose output in the console. (default: false)--solver- 🧩 Specify the solver to use passive GNSS payloads like tag XL or smartlabel. (default AWS)--loracloud-access-token- 🔑 Specify the LoraCloud access token for GNSS payloads. This will be deprecated by 31.07.2025 (default: "")
# 🔍 Decode a Nomad XS payload with verbose output
decoder nomadxs 1 0002c420ff005ed85a12b4180719142607240001ffbaffc2fc6f09a71d2e
# 📝 Decode a Tag S / L payload and output the result in JSON format
decoder tagsl 1 8002cdcd1300744f5e166018040b14341a -j
# 🌐 Start a HTTP server
decoder http --port 8080 --host 0.0.0.0
# 📄 Call HTTP server using curl for decoding
curl -XPOST -H "Content-type: application/json" -d '{
"port": 1,
"payload": "8002cdcd1300744f5e166018040b14341a",
"devEui": ""
}' 'http://localhost:8080/tagsl/v1'
# 📄 Call HTTP server using curl for encoding (Port 128)
curl -XPOST -H "Content-type: application/json" -d '{
"port": 128,
"payload": {
"ble": false,
"gnss": true,
"wifi": true,
"movingInterval": 3600,
"steadyInterval": 7200,
"configInterval": 86400,
"gnssTimeout": 120,
"accelerometerThreshold": 300,
"accelerometerDelay": 1500,
"batteryInterval": 21600,
"batchSize": 10,
"bufferSize": 4096
},
"devEui": ""
}' 'http://localhost:8080/encode/tagsl/v1'
# 📄 Call HTTP server using curl for encoding (Port 129)
curl -XPOST -H "Content-type: application/json" -d '{
"port": 129,
"payload": {
"timeToBuzz": 16
},
"devEui": ""
}' 'http://localhost:8080/encode/tagsl/v1'
# 📄 Call HTTP server using curl for encoding (Port 131)
curl -XPOST -H "Content-type: application/json" -d '{
"port": 131,
"payload": {
"accuracyEnhancement": 16
},
"devEui": ""
}' 'http://localhost:8080/encode/tagsl/v1'
# 📄 Call HTTP server using curl for encoding (Port 134)
curl -XPOST -H "Content-type: application/json" -d '{
"port": 134,
"payload": {
"scanInterval": 300,
"scanTime": 60,
"maxBeacons": 8,
"minRssi": -24,
"advertisingName": "deadbeef",
"accelerometerDelay": 2000,
"acceleratorThreshold": 1000,
"scanMode": 0,
"bleConfigUplinkInterval": 21600
},
"devEui": ""
}' 'http://localhost:8080/encode/tagsl/v1'
# 🖋️ Generate autocompletion script for bash
decoder completion bashFor more detailed information on each command, use:
decoder [command] --helpPOST /{device_type}/v1
Request Body:
{
"port": 1,
"payload": "hex_encoded_payload",
"devEui": ""
}Response:
{
"data": {
// Decoded payload fields
},
"metadata": {
// Metadata about the decoded payload
},
"warnings": [
// Any warnings that occurred during decoding
],
"traceId": "unique_trace_id"
}POST /encode/{device_type}/v1
Request Body:
{
"port": 128,
"payload": {
// Object with fields to encode based on device type and port
},
"devEui": ""
}Response:
{
"encoded": "hex_encoded_payload",
"metadata": {
// Any additional metadata
},
"warnings": [
// Any warnings that occurred during encoding
],
"traceId": "unique_trace_id"
}Available device types for encoding:
tagsl- Tag S/L devices- More device types will be added as they become available
For developers looking to contribute to the truvami Decoder, you can set up your local development environment by following these steps:
- Go 1.20 or later
- Make sure you have
goinstalled and configured properly. - Install dependencies using
go mod tidy. - If you want to develop for the AWS solver, you need to have the AWS CLI installed and configured with your credentials.
To run the tests, use the following command:
go test ./... -vor to run tests with coverage:
make check-coverage