Skip to main content

Device Gateway in AirNgin

Device Gateway is for products that manage one or more Child Devices on a local network or bus while only the Physical Gateway connects to the AirNgin cloud.

  1. Architecture and identity
  2. Provisioning and cloud connection
  3. Complete Gateway MQTT topic reference
  4. Security and AES
  5. Child onboarding
  6. Drivers, protocols, and compatibility
  7. Discovery
  8. Commands and execution ACK
  9. Shadow, telemetry, and events
  10. Hybrid Sync API
  11. HTML Live MQTT
  12. Gateway Analyzer
  13. Offline-first runtime
  14. Backend association
  15. Implementation checklist
  16. Troubleshooting

Three distinct roles​

Direct Device​

A device that connects to AirNgin itself and uses the Direct Device contract.

Physical Gateway​

A normal AirNgin Device with its own DeviceSerial. It is the only permanent MQTT/AES principal for Gateway-mediated traffic.

Child Device​

A Child remains an independent AirNgin Device identity with its own DeviceSerial, but it does not receive a separate Gateway MQTT credential. Its cloud traffic is mediated by its active Physical Gateway.

Architecture at a glance​

AirNgin Cloud
    │
    │ Gateway MQTT + HTTPS
    ▼
Physical Gateway
    │
    ├── Gateway Driver ── Native Protocol ── Child A
    ├── Gateway Driver ── Native Protocol ── Child B
    └── Gateway Driver ── Native Protocol ── Child C

AirNgin does not impose one universal Gateway-to-Child protocol. A Driver may manage Modbus, BLE, CAN, LAN, or a manufacturer-specific protocol.

Core v1 rules​

  • Gateway and Child both use the standard AirNgin DeviceSerial contract.
  • DeviceSerial is not ClientId, slaveId, MAC, IP, or a native address.
  • A Child has at most one active Gateway at a time.
  • Direct Device topics are never used for Gateway-mediated Children.
  • Active Gateway-cloud topics are AES protected.
  • HTML Live topics are the deliberate exception: WSS/TLS + temporary credentials, no /AES.
  • Analyzer is uplink-only; downlink translation belongs to the Driver.
  • MQTT PUBACK is not Child execution success.
  • Cloud outages must not unnecessarily stop the already-synchronized local runtime.

Implementation status​

These pages describe the canonical Gateway v1 contract. Some APIs/topics may not exist in production until Backend/Firmware implementation is completed. In that case, this documentation is the implementation contract, not a claim that the runtime is already deployed.