Custom Decoders

This document provides technical details on the Goja-based JavaScript decoding environment and advanced parsing techniques for IoT binary data.

The Runtime Environment

AdaTrack embeds the Goja engine, a pure Go implementation of ECMAScript 5.1.

• Concurrency: Goja runtimes are not thread-safe. AdaTrack maintains a sync.Pool of runtimes. Each worker borrows a runtime, executes the script, and returns it to the pool.

• Performance: While Goja does not use JIT compilation (like V8), it is extremely efficient for bitwise operations and object manipulation, typically completing a decode in less than 500 microseconds.

• Sandboxing: The environment is strictly isolated. The global this object is empty. No require, process, or fs modules are available.

Input Specification

Your Decoder(bytes, port) function receives:

• bytes: A standard JavaScript Array of numbers (0-255).

• port: A number (1-65535).

Advanced Parsing Patterns

1. Multi-byte Integers (Big Endian)

To combine multiple bytes into a larger integer, use bit-shifting:

// 32-bit Signed Integer (e.g., Latitude/Longitude)
var val = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];

// 16-bit Unsigned Integer
var val = (bytes[0] << 8) | bytes[1];

2. Handling Signed 16-bit Integers (Shorts)

JavaScript's bitwise operators return 32-bit signed integers. For 16-bit signed values, you must manually handle the sign bit:

var raw = (bytes[0] << 8) | bytes[1];
var signedVal = (raw > 32767) ? raw - 65536 : raw;

3. Floating Point (IEEE 754)

Goja does not provide a native Float32Array buffer view for easy parsing. If your device sends raw IEEE 754 floats, you can use a helper function:

function decodeFloat(bytes) {
    var binary = (bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3];
    var s = (binary >> 31) ? -1 : 1;
    var e = (binary >> 23) & 0xFF;
    var m = (e === 0) ? (binary & 0x7FFFFF) << 1 : (binary & 0x7FFFFF) | 0x800000;
    return s * m * Math.pow(2, e - 150);
}

4. Bit Flags (Status Bytes)

Devices often pack multiple boolean flags into a single byte:

var statusByte = bytes[0];
var isMoving = (statusByte & 0x01) !== 0;  // Bit 0
var isCharging = (statusByte & 0x02) !== 0; // Bit 1
var alarmState = (statusByte & 0x04) !== 0; // Bit 2

Decoder Metadata & State

The Decoder can return a simple JSON object. If you want to trigger specific platform behaviors, include these metadata fields:

Field	Type	Description
_ignore	boolean	If true, AdaTrack will process the packet but won't save it to the database (useful for heartbeat packets).
_timestamp	number	Override the server/device timestamp with a value from the payload (UNIX ms).
_device_type	string	Dynamically update the device's type based on its reporting mode.

Limitations & Timeouts

• Execution Time: Scripts are killed if they run for longer than 100ms.

• Memory: Scripts are limited to 16MB of memory allocation.

• Output Size: The returned JSON object must be less than 64KB when serialized.

Testing your Decoder

We recommend using the Simulator found in deploy/backend/test/ to send real binary data to your local/dev instance and verifying the output in the dashboard's "Decoder Logs."