Amazon AWS IoT MQTT Client for CircuitPython

  • Author(s): Brent Rubell

Implementation Notes


Software and Dependencies:

exception adafruit_aws_iot.AWS_IOT_ERROR

Exception raised on MQTT API return-code errors.

class adafruit_aws_iot.MQTT_CLIENT(mmqttclient: adafruit_minimqtt.adafruit_minimqtt.MQTT, keep_alive: int = 30)

Client for interacting with Amazon AWS IoT MQTT API.

  • mmqttclient (MQTT) – Pre-configured MiniMQTT Client object.

  • keep_alive (int) – Optional Keep-alive timer interval, in seconds. Provided interval must be 30 <= keep_alive <= 1200.

connect(clean_session: bool = True) None

Connects to Amazon AWS IoT MQTT Broker with Client ID.


clean_session (bool) – Establishes a clean session with AWS broker.

disconnect() None

Disconnects from Amazon AWS IoT MQTT Broker and de-initializes the MiniMQTT Client.

property is_connected: bool

Returns if MQTT_CLIENT is connected to AWS IoT MQTT Broker

loop() None

Starts a synchronous message loop which maintains connection with AWS IoT. Must be called within the keep_alive timeout specified to init. This method does not handle network connection/disconnection.

Example of “pumping” an AWS IoT message loop: ..code-block::python

while True:


loop_forever() None

Begins a blocking, asynchronous message loop. This method handles network connection/disconnection.

publish(topic: str, payload: str | float | bytes, qos: int = 1) None

Publishes to a AWS IoT Topic.

  • topic (str) – MQTT topic to publish to.

  • payload (str|float|bytes) – Data to publish to topic. Must be able to be converted to a string using str()

  • qos (int) – Quality of service level for publishing

reconnect() None

Reconnects to the AWS IoT MQTT Broker

shadow_delete() None

Publishes an empty message to the shadow delete topic to delete a device’s shadow

shadow_get() None

Publishes an empty message to shadow get topic to get the device’s shadow.

shadow_get_subscribe(qos: int = 1) None

Subscribes to device’s shadow get response.


qos (int) – Optional quality of service level.

shadow_subscribe(qos: int = 1) None

Subscribes to all notifications on the device’s shadow update topic.


qos (int) – Optional quality of service level.

shadow_update(document: str)

Publishes a request state document to update the device’s shadow.


state_document (str) – JSON-formatted state document string.

subscribe(topic: str, qos: int = 1) None

Subscribes to an AWS IoT Topic.

  • topic (str) – MQTT topic to subscribe to.

  • qos (int) – Desired topic subscription’s quality-of-service.

static validate_topic(topic: str) None

Validates if user-provided pub/sub topics adhere to AWS Service Limits.


topic (str) – Desired topic to validate