Parser Guide

Parsers transform raw device payloads into structured readings. Each device type has its own parser written in JavaScript.

What is a Parser?

When an IoT device sends data, the payload is typically a compact binary or hex-encoded string. A parser is a JavaScript function that decodes this raw payload into human-readable values (temperature, humidity, battery level, etc.).

Example: A device sends 19FF03. The parser decodes this as:

{
  "temperature": 25,
  "humidity": 255,
  "battery": 3
}

Writing a Parser

A parser is a JavaScript function that receives the raw payload and returns an object with the decoded values.

// Simple temperature + humidity decoder
return {
  temperature: parseInt(payload.substring(0, 2), 16),
  humidity: parseInt(payload.substring(2, 4), 16),
  battery: parseInt(payload.substring(4, 6), 16)
};

Available Variables

Variable	Type	Description
payload	string	Raw hex-encoded payload from the device

Available Libraries

Parser code has access to these JavaScript libraries:

Library	Usage
_ (Lodash)	_.get(data, 'nested.path', default) — Utility functions
CryptoJS	CryptoJS.SHA256(payload) — Hashing and encryption
dateFns	dateFns.format(new Date(), 'yyyy-MM-dd') — Date formatting

Return Format

The parser must return a plain JavaScript object. Each key becomes a reading field stored in the database.

// Good: flat object with named readings
return {
  temperature: 25.3,
  humidity: 68,
  battery_voltage: 3.6,
  motion_detected: true
};

Version Management

Parsers are versioned. Each time you create a new parser for the same enterprise and device type, a new version is created. Only one version can be active at a time.

Action	Effect
Create new parser	New version created (inactive by default)
Activate a version	That version becomes active; previous version deactivated
Rollback	Activate a previous version

Testing

Before activating a parser, test it with known payloads:

1. Validate endpoint — Send a test payload and parser code to see the decoded output without affecting production
2. Test suite — Create ParserTestCase records with expected inputs and outputs for automated validation

Deploying a Parser

Via the Portal

1. Navigate to Parsers in the admin interface
2. Click Add Parser
3. Select the enterprise and device type
4. Enter the decoder code (JavaScript)
5. Add release notes describing the changes
6. Save — the parser is created as a new version
7. Test the parser with sample payloads
8. When satisfied, activate the new version

Via the API

# Create a new parser version
curl -X POST https://api.dev-au-03.nnnco.io/api/parsers/parsers/ \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enterprise": 1,
    "device_type": 1,
    "decoder_code": "return { temp: parseInt(payload.substring(0,2), 16) };",
    "is_active": false,
    "notes": "Fix temperature parsing for negative values"
  }'

# Activate a parser version
curl -X POST https://api.dev-au-03.nnnco.io/api/parsers/parsers/<id>/activate/ \
  -H "Authorization: Bearer <token>"

Rollback

If a new parser version causes issues:

1. Navigate to the parser list and filter by enterprise and device type
2. Find the previous working version
3. Activate it — the problematic version is automatically deactivated
4. Investigate and fix the issue in a new version

Best Practices

• Always test before activating — Use the validate endpoint with real device payloads
• Add release notes — Document what changed and why
• Monitor after deployment — Check logs for parsing errors after activating a new version
• Keep parsers simple — Parse the payload and return values; avoid complex logic
• Handle edge cases — Consider what happens with malformed or truncated payloads