Skip to main content

Connect a Direct Device to the AirNgin MQTT server

MQTT is the primary cloud messaging transport for Direct Device integrations. Before implementing this page, read What is MQTT? and complete the provisioning/login flow.

Use server-issued MQTT identity​

The provisioning flow supplies the complete MQTT identity and credentials, including:

  • projectCode
  • DeviceSerial
  • ClientId
  • MQTT username/password
  • broker information
  • Direct Device encryptionKey when the optional AES layer is enabled.

Treat ClientId as an opaque, server-issued credential. The Backend currently constructs it using server-side project metadata, but firmware must not reconstruct or parse it. Persist the exact value that provisioning returns and reuse it across normal reconnects, reboots, and broker failover.

Brokers and ports​

Canonical AirNgin broker endpoints:

Primary:  mqtt.airngin.com
Fallback: mqtt.airngin.ir

Supported MQTT ports:

1883  MQTT without TLS
8883  MQTT over TLS

WebSocket clients may use the documented WSS endpoint when applicable to that client type.

Connection behavior​

For Direct Device firmware, use non-blocking reconnect behavior. The canonical integration policy is:

  • MQTT 3.1.1;
  • KeepAlive: 30 seconds;
  • socket timeout: 15 seconds;
  • CleanSession = true;
  • retain disabled unless a specific topic contract says otherwise;
  • try the primary broker three times before switching to the fallback;
  • after sustained failure, return to a long retry interval of about five minutes;
  • restore subscriptions after reconnect;
  • keep local product control working while the network or AirNgin cloud is unavailable;
  • do not reboot the device merely because MQTT is down.

Subscribe after connection​

Subscribe only to the topics required by your product. Common Direct Device subscriptions include:

projectCode/ServerToDevice/{deviceSerial}
projectCode/DeviceSetting/{deviceSerial}
projectCode/ReceiveGeneralData/{deviceSerial}
projectCode/DeviceLastValue/{deviceSerial}
projectCode/Debugger/{deviceSerial}
projectCode/SendScenarioSetting
projectCode/ReceiveRunScenario
projectCode/Time
projectCode/Time/Tehran

Use the /AES variant only for topics that the Direct Device security contract marks as encrypted.

Receive callback​

Your MQTT receive callback should:

  1. validate the project/topic;
  2. identify the target DeviceSerial where the topic/payload is device-scoped;
  3. parse JSON safely;
  4. route the message to the relevant feature handler;
  5. never let malformed cloud input block local product control.

Typical feature branches include normal server commands, Dedicated Settings, Debugger actions, scenarios, General Data, and time synchronization.

Publish helper​

When publishing, prepend the current projectCode exactly once and use the canonical topic/QoS rules. Do not publish if the MQTT session is unavailable; local behavior should continue and the product should reconnect asynchronously.

ESP32 sample​

The legacy ESP32 sample remains useful as an implementation reference, but the canonical contracts in these docs take precedence when an old sample uses outdated topic shapes, retry timing, or ClientId assumptions.

AirNgin MQTT ESP32 Arduino sample

For TLS, see TLS in AirNgin. For application-layer encryption, see AES security.