MQTT API Documentation

This document provides details on how to send data using MQTT to the given topic structure. It includes topic formatting, payload structure, and valid data types and units.

---

1. MQTT Topic Structure

Clients should publish data to the following topic: v1/$MQTT_USERNAME/things/$CLIENT_ID/data/json

Topic Variables

Variable	Description
$MQTT_USERNAME	Unique MQTT username assigned to the client.
$CLIENT_ID	Unique identifier for the device sending data.

Example Topic

v1/3ab28f2b-e837-4ffc-8dab-0db62ef86120/things/90CF1B14/data/json

---

2. Payload Format

The payload should be a JSON array of objects, where each object represents a data point.

[
  {
    "channel": "$UNIQUE_CHANNEL_NUMBER",
    "type": "$DATA_TYPE",
    "unit": "$DATA_UNIT",
    "value": NUMERIC_VALUE,
    "name": "OPTIONAL_NAME"
  }
]

Payload Fields

The payload consists of a JSON array where each object represents a data point.

Field	Type	Description
channel	Integer	Unique channel number assigned to the data point.
type	String	Data type being sent (e.g., temperature, humidity).
unit	String	Measurement unit (e.g., C, RH).
value	Numeric	The actual reading (integer or float).
name	String (Optional)	Descriptive name for the data point (e.g., "SNR", "CO2").

---

Example

[
  {
    "channel": 100,
    "type": "rssi",
    "unit": "dbm",
    "value": -55
  },
  {
    "channel": 101,
    "type": "snr",
    "unit": "db",
    "value": 12,
    "name": "SNR"
  },
  {
    "channel": 6,
    "type": "co2",
    "unit": "ppm",
    "value": 450,
    "name": "CO2"
  },
  {
    "channel": 107,
    "type": "voltage",
    "unit": "v",
    "value": 3.3,
    "name": "Battery Voltage"
  }
]

3. List of Supported Data Types and Units

Below are commonly supported data types and their corresponding measurement units.

Environmental Data

Type	Unit	Description
temperature	C	Temperature in Celsius.
humidity	RH	Relative Humidity percentage.
pressure	Pa	Atmospheric pressure in Pascals.
co2	ppm	Carbon Dioxide concentration in ppm.

Signal Strength

Type	Unit	Description
rssi	dbm	Received Signal Strength Indicator.
snr	db	Signal-to-Noise Ratio.

Electrical Data

Type	Unit	Description
voltage	v	Voltage in Volts.
current	a	Current in Amperes.
power	w	Power in Watts.

4. Python Example (paho-mqtt)

import paho.mqtt.client as mqtt
import json

# MQTT Broker Info
BROKER = "mqtt.zafron.dev"
PORT = 1883
USERNAME = "MQTT_USERNAME"
CLIENT_ID = "MQTT_CLIENT_ID"
TOPIC = f"v1/{USERNAME}/things/{CLIENT_ID}/data/json"

# MQTT Payload
payload = json.dumps([
    {"channel": 100, "type": "rssi", "unit": "dbm", "value": -55},
    {"channel": 6, "type": "co2", "unit": "ppm", "value": 450, "name": "CO2"}
])

# MQTT Client Setup
client = mqtt.Client()
client.username_pw_set(USERNAME, "your_password")
client.connect(BROKER, PORT, 60)

# Publish Data
client.publish(TOPIC, payload)
client.disconnect()

5. Javascript (NodeJS) Example

const mqtt = require('mqtt');

// MQTT Broker Configuration
const BROKER_URL = "mqtt://mqtt.zafron.dev";
const MQTT_USERNAME = "MQTT_USERNAME";
const CLIENT_ID = "CLIENT_ID";
const PASSWORD = "MQTT_PASSWORD";

const TOPIC = `v1/${MQTT_USERNAME}/things/${CLIENT_ID}/data/json`;

// Create MQTT Client and Connect
const client = mqtt.connect(BROKER_URL, {
    username: MQTT_USERNAME,
    password: PASSWORD
});

// Payload Data
const payload = JSON.stringify([
    { "channel": 100, "type": "rssi", "unit": "dbm", "value": -55 },
    { "channel": 101, "type": "snr", "unit": "db", "value": 12, "name": "SNR" },
    { "channel": 6, "type": "co2", "unit": "ppm", "value": 450, "name": "CO2" },
    { "channel": 107, "type": "voltage", "unit": "v", "value": 3.3, "name": "Battery Voltage" }
]);

// Publish Data Once Connected
client.on("connect", () => {
    console.log("Connected to MQTT Broker");
    
    client.publish(TOPIC, payload, { qos: 1 }, (err) => {
        if (err) {
            console.error("Failed to publish message:", err);
        } else {
            console.log("Message published successfully!");
        }
        
        client.end(); // Close connection after publishing
    });
});

// Handle Errors
client.on("error", (err) => {
    console.error("MQTT Error:", err);
    client.end();
});