Logging

This document describes how to send warning and error logs to the Numio platform. For information about MQTT communication setup, please refer to the MQTT documentation.

1. Introduction

Logging is used for reporting warnings and errors from your device to the Numio platform. These logs are displayed on a dedicated page in the Numio interface and help with monitoring and troubleshooting device issues.

2. Log Data Format

Log data is sent in JSON format. Each message should contain relevant information about the warning or error event.

2.1. Example JSON Structure

{
  "timestamp": 1710937800000,
  "message": "High inverter power output detected",
  "details": {
    "metrics": {
      "P_AC_Instant": {
        "value": 8500.5,
        "error": null,
        "metadata": {
          "inverterSerialNumber": "SN12345678"
        }
      },
      "P_AC_Instant_Threshold": {
        "value": 8000.0,
        "error": null,
        "metadata": {
          "inverterSerialNumber": "SN12345678"
        }
      }
    }
  }
}

3. MQTT Topics

Log data is published to one of the following topics:

For warnings:

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

For errors:

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

4. Example Implementation

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

import json
import paho.mqtt.client as mqtt
from datetime import datetime

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

# Prepare warning log data
warning_payload = {
  "timestamp": int(datetime.utcnow().timestamp() * 1000),
  "message": "High inverter power output detected",
  "details": {
    "metrics": {
      "P_AC_Instant": {
        "value": 8500.5,
        "error": null,
        "metadata": {
          "inverterSerialNumber": "SN12345678"
        }
      },
      "P_AC_Instant_Threshold": {
        "value": 8000.0,
        "error": null,
        "metadata": {
          "inverterSerialNumber": "SN12345678"
        }
      }
    }
  }
}

# Publish warning log
client.publish(f"$aws/things/{THING_NAME}/numio/warning/post", json.dumps(warning_payload))

# Prepare error log data
error_payload = {
  "timestamp": int(datetime.utcnow().timestamp() * 1000),
  "message": "Inverter communication failure",
  "details": {
    "metrics": {
      "P_AC_Instant": {
        "value": null,
        "error": {
          "code": "E001",
          "message": "Connection timeout"
        },
        "metadata": {
          "inverterSerialNumber": "SN12345678"
        }
      }
    }
  }
}

# Publish error log
client.publish(f"$aws/things/{THING_NAME}/numio/error/post", json.dumps(error_payload))

5. Best Practices

• Include timestamps as Unix timestamps (milliseconds since epoch)
• Use clear and descriptive messages
• Include relevant context in the details field
• Use appropriate severity levels (warning vs error)
• Keep the payload size reasonable
• Consider using QoS 1 for critical error logs

6. Troubleshooting

6.1. No response after publishing logs

Symptoms:

• Device publishes logs 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
• Verify the full topic paths:

$aws/things/{thingName}/numio/warning/post
$aws/things/{thingName}/numio/error/post

7. Conclusion

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