MQTT Integration ​

LumiotLoRaWAN provides a robust, secure, and fully isolated MQTT interface using Multi-Tenant technology. This integration allows external applications, dashboards (such as Node-RED or Grafana), and third-party platforms to consume real-time sensor telemetry and send commands to devices.

Security Architecture (Edge Broker) ​

To ensure maximum security and compliance with industry standards (ISO-Aligned), the platform uses a Public MQTT Broker (Edge Broker) exposed on ports 8883 (MQTTS - encrypted with TLS 1.3) and 8084 (WSS - WebSockets Secure).

The internal broker of the Network Server is completely isolated (logically Air-Gapped) and is never exposed to the Internet. An internal microservice acts as a secure bridge to transfer only authorized information between the core network and the outside world.

Authentication Parameters ​

To connect to the integration MQTT broker, you must provide:

• Host: The IP or domain of your LumiotLoRaWAN server.
• Port: 8883 (For standard MQTT clients) or 8084 (For WebSockets).
• Username: Your registered email or username.
• Password: The MQTT Token assigned to your user (This hash is managed from the user profile panel and is independent of your web login password).
• TLS/SSL: Active (Required).

MQTT Client Configuration for Connection ​

To facilitate testing and development, we recommend using the MQTTX client.

To add a new simple configuration in MQTTX, click on the New Connection button (or the + icon) and fill out the fields in the General section as follows:

• Name: A descriptive name to identify your connection (e.g., LumiotLoRaWAN Production).
• Host: Select mqtts:// (or wss:// if using WebSockets) and enter the IP or domain of your LumiotLoRaWAN server.
• Port: Enter 8883 (for mqtts://) or 8084 (for wss://).
• Client ID: You can leave the randomly generated default value.
• Username: Your registered email or username on the platform.
• Password: The MQTT Token assigned to your user (obtainable from your user profile panel).
• SSL/TLS: Enable it (toggle on) as it is a mandatory requirement for secure connections.

You can leave the fields in the Advanced section (such as MQTT Version 5.0, Keep Alive, etc.) at their default values. Once completed, click the green Connect button in the top right corner.

Topic Structure (Namespace) ​

The topic tree in LumiotLoRaWAN is designed hierarchically to ensure data sovereignty and isolation. The base structure is:

lumiot/v1/{tenantId}/{subsidiaryId}/devices/{deviceId}/{direction}

• {tenantId}: Unique ID of the tenant (Distributor/Integrator) in the Lumiot database (PostgreSQL), not the internal LNS ID.
• {subsidiaryId}: Unique ID of the subsidiary or application in the Lumiot database (PostgreSQL), not the LNS Application ID.
• {deviceId}: DevEUI of the LoRaWAN device (in lowercase hexadecimal format).
• {direction}: rx for telemetry (reception), tx for sending commands (publish), and rx/downlink for confirmation of queued commands.

Available Topics ​

Note: To subscribe to all devices of a subsidiary, you can use the single-level wildcard: lumiot/v1/{tenantId}/{subsidiaryId}/devices/+/rx.

Sending Commands Example (Downlink) ​

To send a command to a device, you must publish a JSON payload to the tx topic of that device:

Publish Topic:

lumiot/v1/{tenantId}/{subsidiaryId}/devices/{deviceId}/tx

Payload (JSON):

{
  "payloadHex": "030000",
  "fPort": 2,
  "confirmed": true,
  "isEncrypted": false
}

Response Examples (Telemetry in rx) ​

Messages sent by sensors are received decoded as a flat JSON on the rx topic:

Normal Payload Example:

{
  "Count1_times": 0,
  "First_status": "No",
  "RO2_status": "OFF",
  "Work_mode_desc": "1Count+2AVI+1ACI",
  "ACI1_mA": 0,
  "Hardware_mode": "LT22222",
  "AVI1_V": 0,
  "Work_mode": "MOD5_HYBRID_ANALOG",
  "AVI2_V": 0,
  "DO1_status": "H",
  "DO2_status": "H",
  "RO1_status": "OFF"
}

Device Error Report Example:

{
  "error": "Unsupported FPort"
}

Role-Based Access Control (ACL) ​

The system dynamically validates every Subscribe and Publish attempt against the real-time identity database. Permissions are strictly applied based on the hierarchical role of the connected user:

1. SuperAdmin (Infrastructure Level) ​

• Access: Full and unrestricted.
• Permissions: Can subscribe and publish to any topic of any tenant or subsidiary (#).
• Usage: Exclusive for global administrators and cluster maintenance tasks.

2. Integrator / Distributor (Tenant Level) ​

• Allowed Namespace: lumiot/v1/{tenantId}/#
• Permissions: Read (Subscribe) and Write (Publish).
• Isolation: Can interact with all devices of all subsidiaries belonging to their tenant. The system will immediately block at the socket level any subscription attempt to a different {tenantId}, preventing data leakage.

3. Client (Subsidiary Level) ​

• Allowed Namespace: lumiot/v1/{tenantId}/{subsidiaryId}/#
• Permissions: Read (Subscribe) and Write (Publish).
• Isolation: Can only access telemetry and send commands to devices in their assigned subsidiary. Has no visibility of other subsidiaries, even if they belong to the same integrator.

4. Operator (Tactical Level - Read Only) ​

• Allowed Namespace: lumiot/v1/{tenantId}/{subsidiaryId}/#
• Permissions: Exclusively Read (Subscribe).
• Security Restrictions:
  • Cannot send any message to the network (Publish is blocked by the ACL).
  • Can subscribe to command channels (/tx or /rx/downlink) and telemetry (/rx), but strictly for passive monitoring of their assigned subsidiary's traffic.

Suspension States (Kill-Switch) ​

The MQTT integration is coupled with the billing and auditing engine. It respects the platform's commercial lifecycle:

• If a user is deactivated, their MQTT connections will be rejected at authentication, and any open session will be cut.
• If a Tenant is suspended due to arrears or end of contract, all clients, operators, and integrators associated with that tenant will immediately lose their access to the public MQTT broker, interrupting the data flow without the need to delete the equipment.