SMART Project – MQTT Protocol Stack Documentation

1. Architecture Overview

The current protocol stack consists of:

• Shelly Pro 3EM → Publishes to local MQTT broker running on the gateway (port 60011)
• Gateway → Listens locally, parses and flattens incoming messages, maintains last message as buffer
• Server → Connected via secure MQTT (mqtts://nippari.com:60012)

2. Shelly → Gateway (Local MQTT Broker)

The gateway starts a local Aedes MQTT broker. The Shelly Pro 3EM publishes JSON messages to this broker.

Example payload:

{
  "src": "shellypro3em-a0dd6c9f4d5c",
  "dst": "shellypro3em-a0dd6c9f4d5c/events",
  "method": "NotifyStatus",
  "params": {
    "ts": 1750612659.62,
    "em:0": {
      "voltage": 234.2,
      "current": 2.09,
      "act_power": 100.9
    }
  }
}

The gateway flattens this structure and stores it as the most recent buffer.

3. Gateway → Server (MQTTS)

The gateway connects to mqtts://nippari.com:60012 using TLS (no certificate check).

Once connected, the gateway:

• Sends ping messages every 5 seconds to topic up/<gwmac>/<shprefix>
• Waits for a pong from the server, enters state 3
• On receiving ping from server, responds with pong + current buffer contents

4. Flattening Logic

All nested objects in params["em:0"] are flattened using prefix notation:

{
  "src": "...",
  "dst": "...",
  "method": "NotifyStatus",
  "ts": 1750612659.62,
  "em:0_voltage": 234.2,
  "em:0_current": 2.09,
  ...
}

This ensures the buffer is easy to parse and index.

5. Protocol Summary

• Communication: MQTT over TLS for upstream, unencrypted MQTT for LAN
• Roles: Shelly = publisher, Gateway = broker + bridge, Server = MQTT sink
• State machine: Gateway tracks connection state (1 = disconnected, 2 = connected, 3 = confirmed)
• Response topic: Server sends to down/<gwmac>, Gateway replies to up/<gwmac>/<shprefix>

6. Next Steps

1. Store incoming messages to PostgreSQL database on the server
2. Implement rate-limiting and history buffer for each Shelly
3. Add config broadcast mechanism from server to gateway