Telemetry

This document describes how to send telemetry data to the Numio platform. For information about MQTT communication setup, please refer to the MQTT documentation.

1. Introduction

Telemetry is used for regular reporting of data from your device to the Numio platform. Data is sent at regular intervals and serves to monitor the device’s state.

2. Telemetry Data Format

Telemetry data is sent in JSON format. Each message can contain various metrics relevant to your device.

2.1. Example JSON Structure

{
  "P_AC_Instant": {
    "avg": 313974.5,
    "min": 280866.0,
    "max": 324578.2,
    "med": 313974.7,
    "time_start": 1749138900000,
    "time_end": 1749139800000
  },
  "AB_Voltage": {
    "avg": 434,
    "min": 435,
    "max": 434,
    "med": 431,
    "time_start": 1749138900000,
    "time_end": 1749139800000
  }
}

3. MQTT Topic

Telemetry data is published to the topic:

$aws/things/{thingName}/numio/telemetry/post

4. Example Implementation

Here’s an example of how to send telemetry data using Python:

import json
import paho.mqtt.client as mqtt

# Initialize MQTT client and connect (see MQTT documentation for details)
client = mqtt.Client()
# ... MQTT setup code ...

# Prepare telemetry data
payload = {
  "P_AC_Instant": {
    "avg": 313974.5,
    "min": 280866.0,
    "max": 324578.2,
    "med": 313974.7,
    "time_start": 1749138900000,
    "time_end": 1749139800000
  },
  "AB_Voltage": {
    "avg": 434,
    "min": 435,
    "max": 434,
    "med": 431,
    "time_start": 1749138900000,
    "time_end": 1749139800000
  }
}

# Publish telemetry data
client.publish(f"$aws/things/{THING_NAME}/numio/telemetry/post", json.dumps(payload))

5. Best Practices

• Send telemetry data at regular intervals appropriate for your use case
• Include timestamps in your telemetry data when relevant
• Keep the payload size reasonable to optimize network usage
• Consider using QoS 1 for critical telemetry data

6. Troubleshooting

6.1. No response after publishing data

Symptoms:

• Device publishes data but receives no confirmation

Possible Causes:

• MQTT client disconnected too early
• Payload is invalid JSON or does not match expected format
• Topic name contains typos or wrong thingName

Recommended Actions:

• Enable loop_start() or wait before disconnecting
• Validate payload with a JSON linter
• Use the following topic and verify the full path:

$aws/things/{thingName}/numio/telemetry/post

7. Conclusion

This document describes how to send telemetry data to the Numio platform. The implementation is flexible and supports various data types in telemetry messages. For MQTT communication setup and troubleshooting, please refer to the MQTT documentation.