Mapping Code

Introduction

Mapping code transforms JSON payloads into human-readable status text for your integrations. It converts raw IoT sensor data into meaningful messages for Discord and Telegram notifications.

A mapping code consists of text with dynamic placeholders (variables, boolean conditions, GPS maps) that are replaced with real values when Heliumtenna receives a device’s payload via webhook.

Example:

The current temperature is { temperature }°C. The humidity is { boolean(humidity>70){high}{low} }.

With the payload:

{
  "temperature": 17,
  "humidity": 76
}

This translates to:

The current temperature is 17°C. The humidity is high.

The processed message is then sent to your linked Discord or Telegram integrations.

Interface

To configure mapping code in the Heliumtenna dashboard:

1. Navigate to the device’s details page and select the “JSON Payload” tab
2. Enter the JSON payload data from your sensor (often prefilled with the latest payload received via webhook)

3. In the “Mapping Code” tab, write the mapping code using text with dynamic placeholders (see Types of Mapping Codes for details)

4. Use the “Available JSON Keys” section to quickly insert placeholders for variables, boolean conditions, or GPS map keys
5. Preview the result in the “Result” tab, which updates in real-time

Types of Mapping Codes

1. Simple Variable Substitution

Replace a variable with its value from the JSON payload.

Syntax: { variableName }

Examples:

Temperature: { temperature }°C
Battery: { batteryLevel }%
Device: { deviceName }

With payload:

{
  "temperature": 23.5,
  "batteryLevel": 97,
  "deviceName": "Sensor-01"
}

Result:

Temperature: 23.5°C
Battery: 97%
Device: Sensor-01

2. Boolean Conditions

Evaluate a variable’s truthiness and display different text based on the result.

Syntax: { boolean(variableName){trueText}{falseText} }

Examples:

Door status: { boolean(doorOpen){Open}{Closed} }
Motion: { boolean(isMotionDetected){Detected}{Not detected} }
Online: { boolean(isOnline){🟢 Connected}{🔴 Disconnected} }

Truthiness Rules

3. Conditional Expressions

Compare variables against specific values using comparison operators.

Syntax: { boolean(variableName operator value){trueText}{falseText} }

Supported Operators

String Comparison Examples

Status: { boolean(status=="online"){🟢 Online}{🔴 Offline} }
Mode: { boolean(operatingMode=="auto"){Automatic}{Manual} }
Alert: { boolean(alertLevel!="normal"){⚠️ Alert Active}{✅ Normal} }

Numeric Comparison Examples

Battery: { boolean(batteryLevel>=50){🔋 Good}{🪫 Low} }
Temperature: { boolean(temperature>25){🌡️ Hot}{🌡️ Cool} }
Signal: { boolean(signalStrength>-70){📶 Strong}{📶 Weak} }
RSSI: { boolean(rssi<=-90){Poor Signal}{Good Signal} }

4. GPS Map Generation

Generate interactive maps showing device and gateway locations using OpenStreetMap.

Syntax:

• { gps_map } - Show sensor location only (default)
• { gps_map(false) } - Show sensor location only (explicit)
• { gps_map(true) } - Show sensor + 5 nearest gateways (default limit)
• { gps_map(true)(10) } - Show sensor + 10 nearest gateways (custom limit)
• { gps_map(true)(0) } - Show sensor + all gateways (no limit)

Gateway Limiting Rules

• Default behavior: { gps_map(true) } shows the 5 nearest gateways
• Custom limit: Use any number > 0 to show that many nearest gateways
• Show all: Use 0 to show all available gateways
• Gateway limit ignored: When using { gps_map(false) }, any gateway limit parameter is ignored

Examples:

Current location: { gps_map }
Default network view: { gps_map(true) }
Device position only: { gps_map(false) }
Nearest 3 gateways: { gps_map(true)(3) }
All available gateways: { gps_map(true)(0) }
Detailed network (15 nearest): { gps_map(true)(15) }

Requirements

• Sensor coordinates must be available as latitude and longitude fields
• For Helium Console: Gateway data in hotspots array with lat/long fields
• For ChirpStack: Gateway data in rxInfo array with location.latitude/location.longitude fields

Output Format

📍 Device Location: 51.020644, 6.902095
🏠 Gateways shown on map

Complete Examples

Door Sensor with Battery Monitoring

JSON Payload:

{
  "doorOpen": true,
  "batteryLevel": 85,
  "temperature": 22.1,
  "lastSeen": "2025-09-15T10:30:00Z"
}

Mapping Code:

🚪 Door is { boolean(doorOpen){OPEN}{CLOSED} }
🔋 Battery: { boolean(batteryLevel>=20){Good ({ batteryLevel }%)}{Low ({ batteryLevel }%)} }
🌡️ Temperature: { temperature }°C

Result:

🚪 Door is OPEN
🔋 Battery: Good (85%)
🌡️ Temperature: 22.1°C

Environmental Sensor

JSON Payload:

{
  "temperature": 28.5,
  "humidity": 65,
  "pressure": 1013.25,
  "status": "online",
  "batteryVoltage": 3.2
}

Mapping Code:

{ boolean(status=="online"){🟢 ONLINE}{🔴 OFFLINE} } - Environmental Data
🌡️ { boolean(temperature>25){Hot ({ temperature }°C)}{Cool ({ temperature }°C)} }
💧 { boolean(humidity>70){Very Humid}{Normal} } ({ humidity }%)
⚡ { boolean(batteryVoltage>=3.0){Battery OK}{Battery Low} } ({ batteryVoltage }V)

Result:

🟢 ONLINE - Environmental Data
🌡️ Hot (28.5°C)
💧 Normal (65%)
⚡ Battery OK (3.2V)

GPS Tracking Device (Helium Console)

JSON Payload:

{
  "decoded": {
    "payload": {
      "latitude": 51.020644,
      "longitude": 6.902095,
      "battery": 3.689,
      "accuracy": 3,
      "altitude": 0
    }
  },
  "hotspots": [
    {
      "name": "hidden-tiger-pike",
      "lat": 51.020645632560594,
      "long": 6.902218129834184,
      "rssi": -39,
      "snr": 5.5
    },
    {
      "name": "round-rouge-swallow",
      "lat": 51.02044634673636,
      "long": 6.899678836036385,
      "rssi": -104,
      "snr": 3.5
    }
  ]
}

Mapping Code:

🚗 Vehicle Tracker Status
{ gps_map(true) }
🔋 Battery: { boolean(battery>=3.0){Good ({ battery }V)}{Low ({ battery }V)} }
📡 Accuracy: { accuracy }m
🏔️ Altitude: { altitude }m

Result:

🚗 Vehicle Tracker Status
📍 Device Location: 51.020644, 6.902095
🏠 Gateways shown on map (blue), sensor (orange), lines show connections
🔋 Battery: Good (3.689V)
📡 Accuracy: 3m
🏔️ Altitude: 0m

Best Practices

1. Use descriptive variable names in your JSON payload for clarity
2. Quote string values in comparisons: status=="online"
3. Use emojis to make messages visually appealing and easier to scan
4. Combine multiple conditions to create comprehensive status messages
5. Keep messages concise but informative for mobile notifications

Testing Your Mapping Codes

To test your mapping code:

1. Navigate to your device’s details page
2. Enter your JSON payload in the “JSON Payload” tab
3. Write your mapping code in the “Mapping Code” tab
4. View the result in the “Result” tab, which updates in real-time

Troubleshooting

Common Issues

Limitations

Not Supported:

{
  "sensor": {
    "temperature": 25
  }
}

Supported:

{
  "temperature": 25
}

Need Help?

If you encounter issues or have questions:

• Review the troubleshooting section above
• Refer to the complete examples for guidance
• Contact support through the Heliumtenna dashboard

Next Steps

• Add an integration
• View device data