MQTT Integration Handlers

This document provides an overview of the supported MQTT handlers for integration with Azure IoT Hub, AWS IoT, and Sparkplug v3 systems (in addition to the default Ayyeka proprietary handler). These handlers are designed to ensure compatibility, security, and efficient data exchange between Ayyeka's devices and cloud platforms.

---

Azure IoT Handler

This handler is designed for secure and seamless communication with Microsoft Azure IoT Hub.

Connection Configuration

• Client ID: Set by gsm_settings.mqtt_client_id.

• Authentication:

  • The device symmetric key must be stored in gsm_settings.user_defined_pass.

  • Username format: <hostname>/<client_id>/version

  • Password: A Shared Access Signature (SAS) token, generated using the device ID, hostname, and symmetric key.

If authentication fails, the handler attempts fallback credentials:

• lkgc_mqtt_user: Last Known Good Client ID

• lkgc_mqtt_pass: Last Known Good Symmetric Key

Last Will and Testament (LWT)

• Format matches Ayyeka’s standard MQTT client.

• Topic: devices/<client_id>/messages/events

Publishing

• Message Format: Default Protobuf.

• Topic: devices/<client_id>/messages/events

Disconnection

• A report-end message is sent to the same topic upon disconnection.

---

AWS IoT Handler

This handler is based on Ayyeka’s standard MQTT client with adjustments for AWS IoT Core.

Key Differences from Ayyeka’s Client

• All messages (including LWT and report-end) are sent with .retain = 0.

• TLS connection uses Application-Layer Protocol Negotiation (ALPN) as required by AWS IoT. This is handled in the handler’s tls_cb function.

---

Sparkplug v3 Handler

This handler supports integration with platforms using the Sparkplug v3 specification.

Authentication

• Primary mode: Uses gsm_settings.user_defined_username and gsm_settings.user_defined_password.

• Fallback: Falls back to hardware ID–based authentication (same as Ayyeka's default handler).

Identifiers

• Sparkplug Node ID: The device’s AK-ID

• Sparkplug Group Name: Value of gsm_settings.client_id

Sparkplug Topics

Messages are published to:

spBv1.0/<gsm_settings.client_id>/[NDATA|NBIRTH|NDEATH]/<AKID>

Payload Format

• Sparkplug-compliant encoding.

• Only scalar values are sent.

  • No GPS data is included.

  • No camera image is included.

---

Channel Mapping to Metrics

Channel Type	Metric Name Prefix	Metric Alias Offset
Serial (MODBUS_S32)	s_	+0
Analog (ADC_S32)	a_	+100
Digital (GPIO/PCNT)	d_	+200
Battery Voltage	vbat_	+300
GSM Signal Strength	gsm_sig_	+400
Temperature	tem_	+500
LoRa Signal Strength	lora_sig_	+600

Note: Serial samples with the value 0xFFFFFFFF are marked as invalid using the Quality attribute with a value of QUALITY_BAD = 0.

---

Optional Arguments

NBIRTH and NDEATH message behavior is configurable via the mqtt_handler_args setting (under Advanced Configuration → GSM):

• -d NDEATH (Node Death) Policy:

  • 0 (default): Send on every disconnection and LWT.

  • 1: Send only in LWT.

  • 2: Never send.

• -b NBIRTH (Node Birth) Policy:

  • 0 (default): Send on each connection.

  • 1: Send only once.

  • 2: Never send.