From 64f11c7cf06fdea06c0e26df0d47d3e9bb705ab7 Mon Sep 17 00:00:00 2001 From: hani_bad7 Date: Mon, 3 Mar 2025 10:14:09 +0100 Subject: [PATCH 1/3] Added reference manual for aws library --- docs/API_reference/en/cloudlib/README.md | 8 +- docs/API_reference/en/cloudlib/aws.md | 173 +++++++++++++++++++++++ docs/API_reference/en/sidebar.yaml | 5 + 3 files changed, 182 insertions(+), 4 deletions(-) create mode 100644 docs/API_reference/en/cloudlib/aws.md diff --git a/docs/API_reference/en/cloudlib/README.md b/docs/API_reference/en/cloudlib/README.md index 521809f1..c1c22bb7 100644 --- a/docs/API_reference/en/cloudlib/README.md +++ b/docs/API_reference/en/cloudlib/README.md @@ -1,8 +1,8 @@ -# QuecPython IoT Platform +# QuecPython IoT Connection -> The QuecPython IoT platform library includes the Lwm2m platform. +> The QuecPython IoT platform library includes the AWS library. -## QuecPython IoT Platform Library List +## QuecPython IoT Connection Library List -- [Lwm2m IoT Platform](./Lwm2m.md) +- [AWS IoT Core cloud service ](./aws.md) diff --git a/docs/API_reference/en/cloudlib/aws.md b/docs/API_reference/en/cloudlib/aws.md new file mode 100644 index 00000000..6f05d7c5 --- /dev/null +++ b/docs/API_reference/en/cloudlib/aws.md @@ -0,0 +1,173 @@ +# AWS IoT Core Client API Reference + +## **Overview** +A client for connecting to AWS IoT Core, managing MQTT connections, and handling device shadows. + +--- +## **Base Class: Aws** + +```python +class Aws(object): + """ + AWS IoT Core client + """ + def __init__(self, client_id, server, port, keep_alive=60, ssl=False, ssl_params=None): + self.client_id = client_id # Client ID is a name of the IoT Thing + self.mqtt_client = MQTTClientWrapper(client_id, server, port, keep_alive, ssl, ssl_params) + self.shadow_manager = ShadowManager(self.mqtt_client, client_id) + self.logging = log.getLogger("AWS") +``` + +### **Description** +The `Aws` class provides an interface for connecting to AWS IoT Core, managing MQTT topics, and interacting with AWS IoT Shadows. + +### **Initialization** +```python +Aws(client_id, server, port, keep_alive=60, ssl=False, ssl_params=None) +``` + +| Parameter | Type | Description | +|-------------|--------|-------------| +| client_id | str | The unique identifier for the IoT Thing. | +| server | str | The AWS IoT Core endpoint. | +| port | int | The MQTT port (default 8883 for TLS, 1883 for non-TLS). | +| keep_alive | int | The keep-alive interval in seconds (default: 60). | +| ssl | bool | Whether to use SSL/TLS (default: False). | +| ssl_params | dict | SSL parameters for secure connection. | + +--- +## **Methods** + +### `connect()` +Establishes a connection to AWS IoT Core. It is important to make a connection first before using subscribe and publish. +```python +aws_client = Aws("my_device", "a1b2c3d4e5f6.iot.amazonaws.com", 8883, ssl=True) +aws_client.connect() +``` + +### `disconnect()` +Disconnects from AWS IoT Core. +```python +aws_client.disconnect() +``` + +### `subscribe(topic)` +Subscribes to an MQTT topic. +```python +aws_client.subscribe("my/topic") +``` + +### `publish(topic, payload)` +Publishes a message to an MQTT topic. +```python +data = {"temperature": 25, "humidity": 60} +aws_client.publish("sensor/data", data) +``` + +--- +## **Shadows** + +### `create_shadow(shadow_name="", state="")` +Creates an IoT shadow with an optional name and state. +```python +shadow_state = {"reported": {"status": "active"}} +aws_client.create_shadow("deviceShadow", shadow_state) +``` + +### `update_shadow(shadow_name="", state="")` +Updates the state of an IoT shadow. +```python +shadow_update = {"desired": {"temperature": 22}} +aws_client.update_shadow("deviceShadow", shadow_update) +``` + +### `get_shadow(shadow_name="")` +Retrieves the current state of an IoT shadow. +```python +aws_client.get_shadow("deviceShadow") +``` + +### `delete_shadow(shadow_name="")` +Deletes an IoT shadow. +```python +aws_client.delete_shadow("deviceShadow") +``` + +### `connect_shadow(shadow_name="", topics=None)` +Establishes a connection to an IoT shadow and subscribes to related topics. +```python +aws_client.connect_shadow("deviceShadow", ["shadow/update", "shadow/get"]) +``` + +### `set_callback(topic_name, callback)` +Sets a callback function for a specified MQTT topic. +```python +def message_callback(topic, msg): + print(f"Received message from {topic}: {msg}") +aws_client.set_callback("sensor/data", message_callback) +``` + +### `start()` +Starts a loop thread which is waiting for a messages from server. It is important to call this method so we don’t lose a message. + + +## **Python Example** +```python +import usr.aws as aws +import modem +import ujson +import sim # Check if PIN verification is needed for your SIM card +import net + +# AWS IoT credentials +certificate_content = """ +-----BEGIN CERTIFICATE----- + +-----END CERTIFICATE----- +""" + +private_content = """ +-----BEGIN RSA PRIVATE KEY----- + +-----END RSA PRIVATE KEY----- +""" + +client_id = 'qpthing' +server = 'abgka7vzgjoa0-ats.iot.eu-west-3.amazonaws.com' +port = 8883 + +def aws_callback(data): + print("HELLO from 1234 topic callback") + +def shadow_callback_get(data): + print("HELLO from get accepted callback") + +def shadow_callback_update(data): + print("HELLO from update accepted callback") + +def shadow_callback_delta(data): + print("HELLO from update delta callback") + +# Create AWS object +aws_obj = aws.Aws(client_id, server, port, keep_alive=60, ssl=True, + ssl_params={"cert": certificate_content, "key": private_content}) +print("Created AWS object") + +# Connect to AWS IoT +aws_obj.connect() +print("Connected to AWS IoT") + +# Subscribe and publish +aws_obj.set_callback("1234", aws_callback) +aws_obj.subscribe("1234") +aws_obj.publish("7777", "Hello from QuecPython") +aws_obj.start() + +# Shadow operations +aws_obj.create_shadow() +aws_obj.connect_shadow() +aws_obj.set_callback("$aws/things/qpthing/shadow/get/accepted", shadow_callback_get) +aws_obj.set_callback("$aws/things/qpthing/shadow/update/accepted", shadow_callback_update) +aws_obj.set_callback("$aws/things/qpthing/shadow/update/delta", shadow_callback_delta) +aws_obj.get_shadow() +aws_obj.update_shadow(state={"state": {"reported": {"welcome": "change reported"}}}) diff --git a/docs/API_reference/en/sidebar.yaml b/docs/API_reference/en/sidebar.yaml index 5e045d6a..57f92034 100644 --- a/docs/API_reference/en/sidebar.yaml +++ b/docs/API_reference/en/sidebar.yaml @@ -209,6 +209,11 @@ items: file: gnsslib/wifilocator.md - label: wifiScan - Wi-Fi Scan file: gnsslib/wifiScan.md +- label: IoT Connection + file: cloudlib/README.md + items: + - label: aws - AWS IoT Core + file: cloudlib/aws.md - label: Component Library file: componentlib/README.md items: -- Gitee From 8f93b252c433c4dd3859ced97ffc5cdb7de0c6b3 Mon Sep 17 00:00:00 2001 From: hani_bad7 Date: Tue, 4 Mar 2025 10:11:39 +0100 Subject: [PATCH 2/3] Changed the Aws API reference design --- docs/API_reference/en/cloudlib/aws.md | 189 +++++++++++++++++--------- 1 file changed, 124 insertions(+), 65 deletions(-) diff --git a/docs/API_reference/en/cloudlib/aws.md b/docs/API_reference/en/cloudlib/aws.md index 6f05d7c5..c3b0b45f 100644 --- a/docs/API_reference/en/cloudlib/aws.md +++ b/docs/API_reference/en/cloudlib/aws.md @@ -1,116 +1,174 @@ # AWS IoT Core Client API Reference -## **Overview** A client for connecting to AWS IoT Core, managing MQTT connections, and handling device shadows. ---- -## **Base Class: Aws** +## Constructor +### `Aws` ```python -class Aws(object): - """ - AWS IoT Core client - """ - def __init__(self, client_id, server, port, keep_alive=60, ssl=False, ssl_params=None): - self.client_id = client_id # Client ID is a name of the IoT Thing - self.mqtt_client = MQTTClientWrapper(client_id, server, port, keep_alive, ssl, ssl_params) - self.shadow_manager = ShadowManager(self.mqtt_client, client_id) - self.logging = log.getLogger("AWS") +class Aws(client_id,server,port,keep_alive,ssl,ssl_params): ``` +**Parameters:** + +- `client_id` (str) - The unique identifier for the IoT Thing. +- `server` (str) - The AWS IoT Core endpoint. +- `port` (int) - The MQTT port (default 8883 for TLS, 1883 for non-TLS). +- `keep_alive` (int) - The keep-alive interval in seconds (default: 60). +- `ssl` (bool) - Whether to use SSL/TLS (default: False). +- `ssl_params` (dict) - SSL parameters for secure connection. -### **Description** -The `Aws` class provides an interface for connecting to AWS IoT Core, managing MQTT topics, and interacting with AWS IoT Shadows. +**Example** -### **Initialization** ```python -Aws(client_id, server, port, keep_alive=60, ssl=False, ssl_params=None) +>>> # Create Aws object +>>> import aws +>>> aws = aws.Aws(client_id, server, port, keep_alive=60,ssl=True,ssl_params={"cert": +certificate_content,"key": private_content}) ``` -| Parameter | Type | Description | -|-------------|--------|-------------| -| client_id | str | The unique identifier for the IoT Thing. | -| server | str | The AWS IoT Core endpoint. | -| port | int | The MQTT port (default 8883 for TLS, 1883 for non-TLS). | -| keep_alive | int | The keep-alive interval in seconds (default: 60). | -| ssl | bool | Whether to use SSL/TLS (default: False). | -| ssl_params | dict | SSL parameters for secure connection. | +## **MQTT Communication** ---- -## **Methods** +Uses umqtt library methods to establish connection and communication with cloud. + +### `aws.connect` -### `connect()` -Establishes a connection to AWS IoT Core. It is important to make a connection first before using subscribe and publish. ```python -aws_client = Aws("my_device", "a1b2c3d4e5f6.iot.amazonaws.com", 8883, ssl=True) -aws_client.connect() +connect() ``` +This method establishes a connection to AWS IoT Core. + +**Return Value:** + +None + +### `aws.disconnect` -### `disconnect()` -Disconnects from AWS IoT Core. ```python -aws_client.disconnect() +disconnect() ``` +This method disconnects from AWS IoT Core. + +**Return Value:** + +None + +### `aws.subscribe` -### `subscribe(topic)` -Subscribes to an MQTT topic. ```python -aws_client.subscribe("my/topic") +subscribe(topic) ``` +Method for mqtt subscribing to a topic. + +**Parameters:** + +- `topic` (str) - The MQTT topic to subscribe to. + +**Return Value:** + +None + +### `aws.publish` -### `publish(topic, payload)` -Publishes a message to an MQTT topic. ```python -data = {"temperature": 25, "humidity": 60} -aws_client.publish("sensor/data", data) +publish(topic, payload) ``` +Method for m mqtt publishing to a topic. + +**Parameters:** + +- `topic` (str) - The MQTT topic to publish to. +- `payload` (dict) - The message payload. + +**Return Value:** + +None --- -## **Shadows** +## **Shadow Device Management** + +### `aws.create_shadow` -### `create_shadow(shadow_name="", state="")` -Creates an IoT shadow with an optional name and state. ```python -shadow_state = {"reported": {"status": "active"}} -aws_client.create_shadow("deviceShadow", shadow_state) +create_shadow(shadow_name="", state="") ``` +**Parameters:** + +- `shadow_name` (str) - The name of the shadow (optional). +- `state` (dict) - The initial state of the shadow (optional). + +**Return Value:** + +None + +### `aws.update_shadow` -### `update_shadow(shadow_name="", state="")` -Updates the state of an IoT shadow. ```python -shadow_update = {"desired": {"temperature": 22}} -aws_client.update_shadow("deviceShadow", shadow_update) +update_shadow(shadow_name="", state="") ``` +**Parameters:** + +- `shadow_name` (str) - The name of the shadow. +- `state` (dict) - The new state of the shadow. + +**Return Value:** + + None + +### `aws.get_shadow` -### `get_shadow(shadow_name="")` -Retrieves the current state of an IoT shadow. ```python -aws_client.get_shadow("deviceShadow") +get_shadow(shadow_name="") ``` +**Parameters:** + +- `shadow_name` (str) - The name of the shadow. + +**Return Value:** + +The current shadow state. + +### `aws.delete_shadow` -### `delete_shadow(shadow_name="")` -Deletes an IoT shadow. ```python -aws_client.delete_shadow("deviceShadow") +delete_shadow(shadow_name="") ``` +**Parameters:** + +- `shadow_name` (str) - The name of the shadow. + +**Return Value:** + +None + +### `aws.connect_shadow` -### `connect_shadow(shadow_name="", topics=None)` -Establishes a connection to an IoT shadow and subscribes to related topics. ```python -aws_client.connect_shadow("deviceShadow", ["shadow/update", "shadow/get"]) +connect_shadow(shadow_name="", topics=None) ``` +**Parameters:** + +- `shadow_name` (str) - The name of the shadow (optional). +- `topics` (list) - List of MQTT topics related to the shadow (optional). + +**Return Value:** + +None + +### `aws.set_callback` -### `set_callback(topic_name, callback)` -Sets a callback function for a specified MQTT topic. ```python -def message_callback(topic, msg): - print(f"Received message from {topic}: {msg}") -aws_client.set_callback("sensor/data", message_callback) +set_callback(topic_name, callback) ``` +**Parameters:** + +- `topic_name` (str) - The MQTT topic for which the callback is set. +- `callback` (function) - The function to be executed when a message is received. -### `start()` -Starts a loop thread which is waiting for a messages from server. It is important to call this method so we don’t lose a message. +**Return Value:** +None +--- ## **Python Example** ```python import usr.aws as aws @@ -171,3 +229,4 @@ aws_obj.set_callback("$aws/things/qpthing/shadow/update/accepted", shadow_callba aws_obj.set_callback("$aws/things/qpthing/shadow/update/delta", shadow_callback_delta) aws_obj.get_shadow() aws_obj.update_shadow(state={"state": {"reported": {"welcome": "change reported"}}}) +``` -- Gitee From 6aa3d4a442438f28ca512470e3e8f3cfad6d8fc8 Mon Sep 17 00:00:00 2001 From: hani_bad7 Date: Thu, 6 Mar 2025 13:12:07 +0100 Subject: [PATCH 3/3] Fixed some issues in AWS API Reference --- docs/API_reference/en/cloudlib/aws.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/API_reference/en/cloudlib/aws.md b/docs/API_reference/en/cloudlib/aws.md index c3b0b45f..7e4a78e4 100644 --- a/docs/API_reference/en/cloudlib/aws.md +++ b/docs/API_reference/en/cloudlib/aws.md @@ -6,7 +6,7 @@ A client for connecting to AWS IoT Core, managing MQTT connections, and handling ### `Aws` ```python -class Aws(client_id,server,port,keep_alive,ssl,ssl_params): +class Aws(client_id,server,port,keep_alive,ssl,ssl_params) ``` **Parameters:** @@ -14,7 +14,7 @@ class Aws(client_id,server,port,keep_alive,ssl,ssl_params): - `server` (str) - The AWS IoT Core endpoint. - `port` (int) - The MQTT port (default 8883 for TLS, 1883 for non-TLS). - `keep_alive` (int) - The keep-alive interval in seconds (default: 60). -- `ssl` (bool) - Whether to use SSL/TLS (default: False). +- `ssl` (bool) - Whether to use SSL/TLS (default: False. If True, encription is enabled, so we have to provide ssl_params). - `ssl_params` (dict) - SSL parameters for secure connection. **Example** @@ -72,7 +72,7 @@ None ```python publish(topic, payload) ``` -Method for m mqtt publishing to a topic. +Method for mqtt publishing to a topic. **Parameters:** -- Gitee