Telemetry & Decoders

One of AdaTrack's most powerful features is its ability to decode proprietary binary payloads without requiring any changes to the platform's core code. This is achieved through Dynamic Decoders.

What is a Decoder?

A decoder is a small JavaScript function that AdaTrack executes whenever a new UDP packet arrives. Its job is to take a raw array of bytes and transform it into a structured JSON object that AdaTrack can store, visualize, and use for alerting.

The Decoder Environment

AdaTrack uses the Goja VM (a high-performance, pure Go JavaScript engine) to execute your code. The environment is sandboxed for security:

• No Network Access: You cannot make HTTP requests.

• No File System Access: You cannot read or write files.

• Limited Standard Library: Basic JavaScript objects (Math, Date, Array) are available.

Writing your first Decoder

The decoder must be a function named Decoder that accepts two arguments:

1. bytes: An array of integers representing the raw binary payload.

2. port: The UDP port on which the packet was received (useful if your device sends different formats on different ports).

Example: Simple 4-byte Lat/Lon Decoder

function Decoder(bytes, port) {
    // Latitude: 4 bytes, signed, Big Endian, scaled 1,000,000
    var latRaw = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];
    var latitude = latRaw / 1000000.0;

    // Longitude: 4 bytes, signed, Big Endian, scaled 1,000,000
    var lonRaw = (bytes[4] << 24) | (bytes[5] << 16) | (bytes[6] << 8) | bytes[7];
    var longitude = lonRaw / 1000000.0;

    return {
        latitude: latitude,
        longitude: longitude,
        battery: bytes[8] // 1 byte battery percent
    };
}

Advanced Bit Manipulation

Since IoT payloads are often highly compressed, you may need to perform bitwise operations. JavaScript's bitwise operators (e.g., <<, |, &) operate on 32-bit signed integers, which makes them ideal for parsing signed binary data.

Handling 16-bit Signed Integers (Shorts)

// Example: Temperature in centidegrees (2 bytes, Big Endian)
var tempRaw = (bytes[0] << 8) | bytes[1];
if (tempRaw & 0x8000) {
    tempRaw = tempRaw - 0x10000; // Handle negative numbers
}
var temperature = tempRaw / 100.0;

Standard Output Fields

While you can return any JSON object, AdaTrack looks for specific keys to enable certain features:

Key	Type	Purpose
latitude	number	Enables real-time map visualization and geofencing.
longitude	number	Enables real-time map visualization and geofencing.
speed	number	Used for historical path analysis and speed alerts.
battery	number	Used for battery health monitoring and alerts.
rssi	number	Signal strength indicator (dBm).

Testing & Debugging

You can test your decoders directly in the Device Profiles dashboard:

1. Enter your JavaScript code.

2. Provide a sample payload in Hexadecimal (e.g., 01 02 03 04).

3. Click Run Test.

4. View the resulting JSON object or any error messages generated during execution.

Error Handling

If your decoder returns null, the packet will be ignored, and no data will be stored. It is good practice to validate the length of the bytes array before processing it:

if (bytes.length < 10) {
    return null; // Not enough data for a valid packet
}