> ## Documentation Index
> Fetch the complete documentation index at: https://docs.industrialpmr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MQTT Protocol & Telemetry Payloads

> Topic structure, JSON payload schemas, keep-alive mechanism, and telemetry actions.

Industrial PMR utilizes an optimized MQTT protocol hierarchy over TLS for telemetry ingestion and edge controller communication.

***

## MQTT Connection Parameters

| Parameter | Production Value | Development Value |
| :- | :- | :- |
| **Broker URL (TLS)** | `mqtts://mqtt.industrialpmr.com:8883` | `mqtt://localhost:1883` |
| **WebSockets (WSS)** | `wss://mqtt.industrialpmr.com:8084/mqtt` | `ws://localhost:8083` |
| **Protocol Version** | MQTT v3.1.1 / v5.0 | MQTT v3.1.1 |
| **Quality of Service** | QoS 1 (At least once) / QoS 2 | QoS 1 |
| **Clean Session** | False (Persistent client subscriptions) | True |

***

## Topic Hierarchy

```
ipmr/
├── {shard_id}/
│   └── {device_mac}/
│       ├── uplink        (Node -> Broker: High-frequency telemetry & cycle records)
│       ├── downlink      (Broker / Dashboard -> Node: Keep-alive, rate commands)
│       └── status        (Node -> Broker: Last Will & Testament online/offline state)
└── legacy/
    └── unit_to_server/   (Backward-compatible pipeline for v1 edge firmware)
```

***

## Telemetry Action Types

The edge firmware and cloud ingestion middleware communicate via standardized message actions:

| Action Identifier | Direction | Purpose |
| :- | :- | :- |
| **`RECORDS`** | Node $\to$ Broker | Batched machine production strokes, stroke duration, and mold code. |
| **`ELECTRICITY`** | Node $\to$ Broker | 3-Phase electrical parameters ($V_{RN}, V_{YN}, V_{BN}, I_R, I_Y, I_B, kW, kWh, PF$). |
| **`REALTIME_VALUES`** | Node $\to$ Broker | High-frequency 1Hz live stream active when an operator is viewing a machine card. |
| **`NO_RECORDS`** | Node $\to$ Broker | Heartbeat packet confirming the edge node is online but machine is stopped. |
| **`NO_ELECTRICITY`** | Node $\to$ Broker | Electrical heartbeat confirming sub-panel is de-energized. |
| **`SHUTDOWN`** | Node $\to$ Broker | Timestamped graceful power-down notice when the main machine isolator is switched off. |
| **`KEEP_ALIVE`** | Web $\to$ Node | Downlink pulse emitted by the dashboard to keep the high-rate stream alive. |
| **`OFFSETS`** | Server $\to$ Node | Calibrates baseline counter values after mold replacement or hardware swap. |

***

## JSON Payload Schemas

### 1. Production Records Payload (`RECORDS`)

Emitted by `ipmr223m-v1` and `ipmr226` nodes as machine cycles are completed:

```json theme={null}
{
  "action": "RECORDS",
  "mac": "24:6F:28:XX:XX:XX",
  "data": {
    "pulse_count": 1482,
    "cycle_time_ms": 19400,
    "mold_code": "GALLON_IML_6",
    "machine_status": "RUNNING",
    "timestamp": 1713801240,
    "rtc_synced": true
  }
}
```

The cloud ingestion worker processes this record, stores it in InfluxDB, updates the machine's live piece count in Firebase RTDB, and returns a `RECORDS_CALLBACK` acknowledgement.

***

### 2. 3-Phase Electrical Payload (`ELECTRICITY`)

Emitted exclusively by `ipmr226` nodes with integrated 3-phase power analysis:

```json theme={null}
{
  "action": "ELECTRICITY",
  "mac": "24:6F:28:YY:YY:YY",
  "data": {
    "voltage": {
      "V_RN": 228.4,
      "V_YN": 230.1,
      "V_BN": 229.2,
      "V_RY": 398.2,
      "V_YB": 400.1,
      "V_BR": 397.8
    },
    "current": {
      "I_R": 34.8,
      "I_Y": 35.2,
      "I_B": 34.6
    },
    "active_power_kw": 23.45,
    "reactive_power_kvar": 4.12,
    "power_factor": 0.94,
    "frequency_hz": 50.02,
    "cumulative_kwh": 14285.4,
    "timestamp": 1713801240
  }
}
```

***

### 3. Downlink Keep-Alive Mechanism (`KEEP_ALIVE`)

To conserve factory Wi-Fi and cellular bandwidth across large plants, edge nodes transmit low-frequency heartbeats (every 30–60 seconds) by default.

When a supervisor opens a machine's detailed card in the web dashboard, the dashboard begins emitting periodic keep-alive pulses to the node's downlink topic:

```json theme={null}
{
  "action": "KEEP_ALIVE",
  "data": {
    "client_session": "dash_usr_4920",
    "requested_rate_ms": 1000
  }
}
```

* The node escalates its publishing rate to **1 Hz** for instantaneous dial movement.
* If the supervisor closes the card or navigates away, keep-alive pulses cease.
* After 30 seconds of inactivity, the node automatically throttles back down to low-bandwidth heartbeat mode.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.