From 26a71711e3aaf717692490ed891dcb3638ae30ef Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 24 Sep 2025 16:26:21 -0700 Subject: [PATCH 01/14] update the ci to validate the necessary file links --- .../workflows/aws-service-sanity-check.yml | 31 +++++++++++++++++++ utils/doc-links.txt | 2 ++ 2 files changed, 33 insertions(+) create mode 100644 .github/workflows/aws-service-sanity-check.yml create mode 100644 utils/doc-links.txt diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml new file mode 100644 index 00000000..8e4b05a5 --- /dev/null +++ b/.github/workflows/aws-service-sanity-check.yml @@ -0,0 +1,31 @@ +name: Main Branch Checks + +on: + push: + branches-ignore: + - 'main' + - 'docs' + +jobs: + verify-documentation-links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Verify documentation files and links + run: | + missing_count=0 + while read -r file; do + if [ ! -f "$file" ]; then + missing_files="$missing_files $file" + fi + done < utils/doc-links.txt + + if [ $missing_count -gt 0 ]; then + echo "" + echo "Instructions:" + echo " These files are required for AWS services or documentations. Restore missing files or update documentation before merge." + echo " Refer to team wiki "AWS Service and Documentation Links" for details. + exit 1 + else + echo "✅ All documentation-referenced files exist" + fi \ No newline at end of file diff --git a/utils/doc-links.txt b/utils/doc-links.txt new file mode 100644 index 00000000..12e8e2a1 --- /dev/null +++ b/utils/doc-links.txt @@ -0,0 +1,2 @@ +samples/mqtt/mqtt5_x509.py +samples/basic_discovery.py \ No newline at end of file From 9eabcb0636d67814b9a381765fca71538cfd8133 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 24 Sep 2025 16:27:39 -0700 Subject: [PATCH 02/14] eof --- .github/workflows/aws-service-sanity-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index 8e4b05a5..954107b1 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -28,4 +28,4 @@ jobs: exit 1 else echo "✅ All documentation-referenced files exist" - fi \ No newline at end of file + fi From b0351ba1f9d610e0e3599434fbd2f866de894b74 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 24 Sep 2025 16:44:42 -0700 Subject: [PATCH 03/14] fix doc links ci --- .github/workflows/aws-service-sanity-check.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index 954107b1..dc0a5d21 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -19,12 +19,12 @@ jobs: missing_files="$missing_files $file" fi done < utils/doc-links.txt - + if [ $missing_count -gt 0 ]; then - echo "" + echo "❌ Missing files referenced in AWS documentation:" echo "Instructions:" echo " These files are required for AWS services or documentations. Restore missing files or update documentation before merge." - echo " Refer to team wiki "AWS Service and Documentation Links" for details. + echo " Refer to team wiki "AWS Service and Documentation Links" for details. " exit 1 else echo "✅ All documentation-referenced files exist" From 8d55df64bc4d71f10726cb962837dc189447e91f Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 24 Sep 2025 17:00:28 -0700 Subject: [PATCH 04/14] improve script to handle file list --- .../workflows/aws-service-sanity-check.yml | 27 ++++++++++--------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index dc0a5d21..922c5640 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -12,20 +12,21 @@ jobs: steps: - uses: actions/checkout@v4 - name: Verify documentation files and links + # check if the files exists in the repository. The file list is in utils/doc-links.txt. run: | - missing_count=0 + missing=0 while read -r file; do - if [ ! -f "$file" ]; then - missing_files="$missing_files $file" - fi + if [ ! -f "$file" ]; then + if [ $missing -eq 0 ]; then + echo "❌ Missing files referenced in AWS documentation:" + missing=$((missing + 1)) + fi + echo " - $file" + fi done < utils/doc-links.txt - - if [ $missing_count -gt 0 ]; then - echo "❌ Missing files referenced in AWS documentation:" - echo "Instructions:" - echo " These files are required for AWS services or documentations. Restore missing files or update documentation before merge." - echo " Refer to team wiki "AWS Service and Documentation Links" for details. " - exit 1 + + if [ $missing -ge 1 ]; then + exit 1 else - echo "✅ All documentation-referenced files exist" - fi + echo "✅ All documentation-referenced files exist" + fi \ No newline at end of file From f8cf657f67ea263da1cd1f998fee29e3ac1d7cb3 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 24 Sep 2025 17:03:07 -0700 Subject: [PATCH 05/14] udpate instructions --- .github/workflows/aws-service-sanity-check.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index 922c5640..fe583f63 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -26,6 +26,10 @@ jobs: done < utils/doc-links.txt if [ $missing -ge 1 ]; then + echo "Instructions:" + echo " The above files are required for AWS services or documentations." + echo " Restore missing files or update documentation before merge." + echo " Refer to team wiki "AWS Service and Documentation Links" for details. " exit 1 else echo "✅ All documentation-referenced files exist" From 33b778ba65192045893b0a769e8dd97b258ad55f Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Wed, 24 Sep 2025 17:11:25 -0700 Subject: [PATCH 06/14] handle file list --- .github/workflows/aws-service-sanity-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index fe583f63..50d4ee3b 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -15,7 +15,7 @@ jobs: # check if the files exists in the repository. The file list is in utils/doc-links.txt. run: | missing=0 - while read -r file; do + while read -r file || [ -n "$file" ]; do if [ ! -f "$file" ]; then if [ $missing -eq 0 ]; then echo "❌ Missing files referenced in AWS documentation:" From f1d3ea314dcfdd5803b14597f084984019e74228 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Thu, 25 Sep 2025 10:00:48 -0700 Subject: [PATCH 07/14] remove gg doc for now --- utils/doc-links.txt | 1 - 1 file changed, 1 deletion(-) diff --git a/utils/doc-links.txt b/utils/doc-links.txt index 12e8e2a1..f353fe55 100644 --- a/utils/doc-links.txt +++ b/utils/doc-links.txt @@ -1,2 +1 @@ samples/mqtt/mqtt5_x509.py -samples/basic_discovery.py \ No newline at end of file From a32134f7830d1c716b6aafb987f857543a359d1a Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Thu, 25 Sep 2025 10:02:49 -0700 Subject: [PATCH 08/14] Potential fix for code scanning alert no. 16: Workflow does not contain permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> --- .github/workflows/aws-service-sanity-check.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index 50d4ee3b..e8f60324 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -1,4 +1,6 @@ name: Main Branch Checks +permissions: + contents: read on: push: From d76f154debfec171ac1385ab6b728d364d652810 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Thu, 25 Sep 2025 10:25:34 -0700 Subject: [PATCH 09/14] remove old pubsub sample --- samples/README.md | 84 --------------------- samples/pubsub.md | 73 ------------------ samples/pubsub.py | 183 ---------------------------------------------- 3 files changed, 340 deletions(-) delete mode 100644 samples/README.md delete mode 100644 samples/pubsub.md delete mode 100644 samples/pubsub.py diff --git a/samples/README.md b/samples/README.md deleted file mode 100644 index 23552f8a..00000000 --- a/samples/README.md +++ /dev/null @@ -1,84 +0,0 @@ -# Sample Applications for the AWS IoT Device SDK v2 for Python -This directory contains sample applications for [aws-iot-device-sdk-python-v2](../README.md). - -### Table of Contents -* [Samples](#samples) - * [MQTT5 Client Samples](#mqtt5-client-samples) - * [Service Client Samples](#service-client-samples) - * [Greengrass Samples](#greengrass-samples) -* [Instructions](#instructions) -* [Sample Help](#sample-help) -* [Enable Logging](#enable-logging) - - -## Samples -### MQTT5 Client Samples -##### MQTT5 is the recommended MQTT Client. Additional infomration and usage instructions can be found in the [MQTT5 User Guide](../documents/MQTT5_Userguide.md). The samples below will create an MQTT5 client, connect using the selected method, subscribe to a topic, publish to the topic, and then disconnect. -| MQTT5 Client Sample | Description | -|--------|-------------| -| [X509-based mutual TLS](./mqtt/mqtt5_x509.md) | Demonstrates connecting to AWS IoT Core using X.509 certificates and private keys. -| [Websockets with Sigv4 authentication](./mqtt/mqtt5_aws_websocket.md) | Shows how to authenticate over websockets using AWS Signature Version 4 credentials. | -| [AWS Custom Authorizer Lambda Function](./mqtt/mqtt5_custom_auth.md) | Examples of connecting with a signed and unsigned Lambda-backed custom authorizer. -| [PKCS11](./mqtt/mqtt5_pkcs11_connect.md) | Demonstrates connecting using a hardware security module (HSM) or smartcard with PKCS#11. | -| [Other Connection Methods](../documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method) | More connection methods are available for review in the MQTT5 Userguide - -### Service Client Samples -##### AWS offers a number of IoT related services using MQTT. The samples below demonstrate how to use the service clients provided by the SDK to interact with those services. -| Service Client Sample | Description | -|--------|-------------| -| [Shadow](./service_clients//shadow.md) | Manage and sync device state using the IoT Device Shadow service. | -| [Jobs](./service_clients//jobs.md) | Receive and execute remote operations sent from the Jobs service. | -| [Basic Fleet Provisioning](./service_clients//fleet_provisioning_basic.md) | Provision a device using the Fleet Provisioning template. | -| [CSR Fleet Provisioning](./service_clients//fleet_provisioning_csr.md) | Demonstrates CSR-based device certificate provisioning. | - - -### Greengrass Samples -##### Samples that interact with [AWS Greengrass](https://aws.amazon.com/greengrass/). -| Greengrass Sample | Description | -|--------|-------------| -| [Greengrass Discovery](./greengrass//basic_discovery.md) | Discover and connect to a local Greengrass core. | -| [Greengrass IPC](./greengrass//ipc_greengrass.md) | Demonstrates Inter-Process Communication (IPC) with Greengrass components. | - -### Instructions - -First, install `aws-iot-device-sdk-python-v2`. Installation instructions for the SDK are [Provided Here](../README.md#Installation). - -Each sample's README contains prerequisites, arguments, and detailed instructions. For example, the [MQTT5 X509 Sample README](./mqtt/mqtt5_x509.md) is `mqtt5_x509.md` and the sample can be run with the following command: - -``` sh -# For Windows: replace 'python3' with 'python' and '/' with '\' -python3 mqtt5_x509.py --endpoint --cert --key -``` - -### Sample Help - -All samples will show their options and arguments by passing in `--help`. For example: -``` sh -# For Windows: replace 'python3' with 'python' and '/' with '\' -python3 mqtt5_x509.py --help -``` - -will result in the following print output: -``` -MQTT5 X509 Sample (mTLS) - -options: - -h, --help show this help message and exit - -required arguments: - --endpoint IoT endpoint hostname (default: None) - --cert Path to the certificate file to use during mTLS connection establishment (default: None) - --key Path to the private key file to use during mTLS connection establishment (default: None) - -optional arguments: - --client_id Client ID (default: mqtt5-sample-5873a450) - --topic Topic (default: test/topic) - --message Message payload (default: Hello from mqtt5 sample) - --count Messages to publish (0 = infinite) (default: 5) -``` - -The sample will not run without the required arguments and will notify you of missing arguments. - -### Enable Logging - -Instructions to enable logging are available in the [FAQ](../documents/FAQ.md) under [How do I enable logging](../documents/FAQ.md#how-do-i-enable-logging). diff --git a/samples/pubsub.md b/samples/pubsub.md deleted file mode 100644 index 0ba8ac91..00000000 --- a/samples/pubsub.md +++ /dev/null @@ -1,73 +0,0 @@ -# PubSub - -[**Return to main sample list**](./README.md) - -This sample uses the -[Message Broker](https://docs.aws.amazon.com/iot/latest/developerguide/iot-message-broker.html) -for AWS IoT to send and receive messages through an MQTT connection. - -On startup, the device connects to the server, subscribes to a topic, and begins publishing messages to that topic. The device should receive those same messages back from the message broker, since it is subscribed to that same topic. Status updates are continually printed to the console. This sample demonstrates how to send and receive messages on designated IoT Core topics, an essential task that is the backbone of many IoT applications that need to send data over the internet. This sample simply subscribes and publishes to a topic, printing the messages it just sent as it is received from AWS IoT Core, but this can be used as a reference point for more complex Pub-Sub applications. - -Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html) must provide privileges for this sample to connect, subscribe, publish, and receive. Below is a sample policy that can be used on your IoT Core Thing that will allow this sample to run as intended. - -
-(see sample policy) -
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Publish",
-        "iot:Receive"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topic/test/topic"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Subscribe"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:topicfilter/test/topic"
-      ]
-    },
-    {
-      "Effect": "Allow",
-      "Action": [
-        "iot:Connect"
-      ],
-      "Resource": [
-        "arn:aws:iot:region:account:client/test-*"
-      ]
-    }
-  ]
-}
-
- -Replace with the following with the data from your AWS account: -* ``: The AWS IoT Core region where you created your AWS IoT Core thing you wish to use with this sample. For example `us-east-1`. -* ``: Your AWS IoT Core account ID. This is the set of numbers in the top right next to your AWS account name when using the AWS IoT Core website. - -Note that in a real application, you may want to avoid the use of wildcards in your ClientID or use them selectively. Please follow best practices when working with AWS on production applications using the SDK. Also, for the purposes of this sample, please make sure your policy allows a client ID of `test-*` to connect or use `--client_id ` to send the client ID your policy supports. - -
- -## How to run - -To Run this sample from the `samples` folder, use the following command: - -```sh -# For Windows: replace 'python3' with 'python' and '/' with '\' -python3 pubsub.py --endpoint --cert --key -``` - -You can also pass a Certificate Authority file (CA) if your certificate and key combination requires it: - -```sh -# For Windows: replace 'python3' with 'python' and '/' with '\' -python3 pubsub.py --endpoint --cert --key --ca_file -``` diff --git a/samples/pubsub.py b/samples/pubsub.py deleted file mode 100644 index 924cb140..00000000 --- a/samples/pubsub.py +++ /dev/null @@ -1,183 +0,0 @@ -# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. -# SPDX-License-Identifier: Apache-2.0. - -from awsiot import mqtt5_client_builder -from awscrt import mqtt5 -import threading -import time -# This sample uses the Message Broker for AWS IoT to send and receive messages -# through an MQTT connection. On startup, the device connects to the server, -# subscribes to a topic, and begins publishing messages to that topic. -# The device should receive those same messages back from the message broker, -# since it is subscribed to that same topic. - -# --------------------------------- ARGUMENT PARSING ----------------------------------------- -import argparse -import uuid - -parser = argparse.ArgumentParser( - description="MQTT5 X509 Sample (mTLS)", - formatter_class=argparse.ArgumentDefaultsHelpFormatter, -) -required = parser.add_argument_group("required arguments") -optional = parser.add_argument_group("optional arguments") - -# Required Arguments -required.add_argument("--endpoint", required=True, metavar="", dest="input_endpoint", - help="IoT endpoint hostname") -required.add_argument("--cert", required=True, metavar="", dest="input_cert", - help="Path to the certificate file to use during mTLS connection establishment") -required.add_argument("--key", required=True, metavar="", dest="input_key", - help="Path to the private key file to use during mTLS connection establishment") - -# Optional Arguments -optional.add_argument("--client_id", metavar="", dest="input_clientId", default=f"mqtt5-sample-{uuid.uuid4().hex[:8]}", - help="Client ID") -optional.add_argument("--topic", metavar="", default="test/topic", dest="input_topic", - help="Topic") -optional.add_argument("--message", metavar="", default="Hello from mqtt5 sample", dest="input_message", - help="Message payload") -optional.add_argument("--count", type=int, metavar="", default=5, dest="input_count", - help="Messages to publish (0 = infinite)") -optional.add_argument("--ca_file", metavar="", dest="input_ca", default=None, - help="Path to root CA file") - -# args contains all the parsed commandline arguments used by the sample -args = parser.parse_args() -# --------------------------------- ARGUMENT PARSING END ----------------------------------------- - -TIMEOUT = 100 -message_count = args.input_count -message_topic = args.input_topic -message_string = args.input_message -# Events used within callbacks to progress sample -connection_success_event = threading.Event() -stopped_event = threading.Event() -received_all_event = threading.Event() -received_count = 0 - - -# Callback when any publish is received -def on_publish_received(publish_packet_data): - publish_packet = publish_packet_data.publish_packet - print("==== Received message from topic '{}': {} ====\n".format( - publish_packet.topic, publish_packet.payload.decode('utf-8'))) - - # Track number of publishes received - global received_count - received_count += 1 - if received_count == args.input_count: - received_all_event.set() - - -# Callback for the lifecycle event Stopped -def on_lifecycle_stopped(lifecycle_stopped_data: mqtt5.LifecycleStoppedData): - print("Lifecycle Stopped\n") - stopped_event.set() - - -# Callback for lifecycle event Attempting Connect -def on_lifecycle_attempting_connect(lifecycle_attempting_connect_data: mqtt5.LifecycleAttemptingConnectData): - print("Lifecycle Connection Attempt\nConnecting to endpoint: '{}' with client ID'{}'".format( - args.input_endpoint, args.input_clientId)) - - -# Callback for the lifecycle event Connection Success -def on_lifecycle_connection_success(lifecycle_connect_success_data: mqtt5.LifecycleConnectSuccessData): - connack_packet = lifecycle_connect_success_data.connack_packet - print("Lifecycle Connection Success with reason code:{}\n".format( - repr(connack_packet.reason_code))) - connection_success_event.set() - - -# Callback for the lifecycle event Connection Failure -def on_lifecycle_connection_failure(lifecycle_connection_failure: mqtt5.LifecycleConnectFailureData): - print("Lifecycle Connection Failure with exception:{}".format( - lifecycle_connection_failure.exception)) - - -# Callback for the lifecycle event Disconnection -def on_lifecycle_disconnection(lifecycle_disconnect_data: mqtt5.LifecycleDisconnectData): - print("Lifecycle Disconnected with reason code:{}".format( - lifecycle_disconnect_data.disconnect_packet.reason_code if lifecycle_disconnect_data.disconnect_packet else "None")) - - -if __name__ == '__main__': - print("\nStarting MQTT5 X509 PubSub Sample\n") - message_count = args.input_count - message_topic = args.input_topic - message_string = args.input_message - - # Create MQTT5 client using mutual TLS via X509 Certificate and Private Key - print("==== Creating MQTT5 Client ====\n") - client = mqtt5_client_builder.mtls_from_path( - endpoint=args.input_endpoint, - cert_filepath=args.input_cert, - pri_key_filepath=args.input_key, - on_publish_received=on_publish_received, - on_lifecycle_stopped=on_lifecycle_stopped, - on_lifecycle_attempting_connect=on_lifecycle_attempting_connect, - on_lifecycle_connection_success=on_lifecycle_connection_success, - on_lifecycle_connection_failure=on_lifecycle_connection_failure, - on_lifecycle_disconnection=on_lifecycle_disconnection, - client_id=args.input_clientId, - ca_filepath=args.input_ca) - - # Start the client, instructing the client to desire a connected state. The client will try to - # establish a connection with the provided settings. If the client is disconnected while in this - # state it will attempt to reconnect automatically. - print("==== Starting client ====") - client.start() - - # We await the `on_lifecycle_connection_success` callback to be invoked. - if not connection_success_event.wait(TIMEOUT): - raise TimeoutError("Connection timeout") - - # Subscribe - print("==== Subscribing to topic '{}' ====".format(message_topic)) - subscribe_future = client.subscribe(subscribe_packet=mqtt5.SubscribePacket( - subscriptions=[mqtt5.Subscription( - topic_filter=message_topic, - qos=mqtt5.QoS.AT_LEAST_ONCE)] - )) - suback = subscribe_future.result(TIMEOUT) - print("Suback received with reason code:{}\n".format(suback.reason_codes)) - - # Publish - if message_count == 0: - print("==== Sending messages until program killed ====\n") - else: - print("==== Sending {} message(s) ====\n".format(message_count)) - - publish_count = 1 - while (publish_count <= message_count) or (message_count == 0): - message = f"{message_string} [{publish_count}]" - print(f"Publishing message to topic '{message_topic}': {message}") - publish_future = client.publish(mqtt5.PublishPacket( - topic=message_topic, - payload=message, - qos=mqtt5.QoS.AT_LEAST_ONCE - )) - publish_completion_data = publish_future.result(TIMEOUT) - print("PubAck received with {}\n".format(repr(publish_completion_data.puback.reason_code))) - time.sleep(1.5) - publish_count += 1 - - received_all_event.wait(TIMEOUT) - print("{} message(s) received.\n".format(received_count)) - - # Unsubscribe - print("==== Unsubscribing from topic '{}' ====".format(message_topic)) - unsubscribe_future = client.unsubscribe(unsubscribe_packet=mqtt5.UnsubscribePacket( - topic_filters=[message_topic])) - unsuback = unsubscribe_future.result(TIMEOUT) - print("Unsubscribed with {}\n".format(unsuback.reason_codes)) - - # Stop the client. Instructs the client to disconnect and remain in a disconnected state. - print("==== Stopping Client ====") - client.stop() - - if not stopped_event.wait(TIMEOUT): - raise TimeoutError("Stop timeout") - - print("==== Client Stopped! ====") From 38d71d07cf6090d6447541c662e3f0dc2fc33366 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Fri, 3 Oct 2025 09:22:46 -0700 Subject: [PATCH 10/14] add back main readme --- samples/README.md | 84 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 samples/README.md diff --git a/samples/README.md b/samples/README.md new file mode 100644 index 00000000..23552f8a --- /dev/null +++ b/samples/README.md @@ -0,0 +1,84 @@ +# Sample Applications for the AWS IoT Device SDK v2 for Python +This directory contains sample applications for [aws-iot-device-sdk-python-v2](../README.md). + +### Table of Contents +* [Samples](#samples) + * [MQTT5 Client Samples](#mqtt5-client-samples) + * [Service Client Samples](#service-client-samples) + * [Greengrass Samples](#greengrass-samples) +* [Instructions](#instructions) +* [Sample Help](#sample-help) +* [Enable Logging](#enable-logging) + + +## Samples +### MQTT5 Client Samples +##### MQTT5 is the recommended MQTT Client. Additional infomration and usage instructions can be found in the [MQTT5 User Guide](../documents/MQTT5_Userguide.md). The samples below will create an MQTT5 client, connect using the selected method, subscribe to a topic, publish to the topic, and then disconnect. +| MQTT5 Client Sample | Description | +|--------|-------------| +| [X509-based mutual TLS](./mqtt/mqtt5_x509.md) | Demonstrates connecting to AWS IoT Core using X.509 certificates and private keys. +| [Websockets with Sigv4 authentication](./mqtt/mqtt5_aws_websocket.md) | Shows how to authenticate over websockets using AWS Signature Version 4 credentials. | +| [AWS Custom Authorizer Lambda Function](./mqtt/mqtt5_custom_auth.md) | Examples of connecting with a signed and unsigned Lambda-backed custom authorizer. +| [PKCS11](./mqtt/mqtt5_pkcs11_connect.md) | Demonstrates connecting using a hardware security module (HSM) or smartcard with PKCS#11. | +| [Other Connection Methods](../documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method) | More connection methods are available for review in the MQTT5 Userguide + +### Service Client Samples +##### AWS offers a number of IoT related services using MQTT. The samples below demonstrate how to use the service clients provided by the SDK to interact with those services. +| Service Client Sample | Description | +|--------|-------------| +| [Shadow](./service_clients//shadow.md) | Manage and sync device state using the IoT Device Shadow service. | +| [Jobs](./service_clients//jobs.md) | Receive and execute remote operations sent from the Jobs service. | +| [Basic Fleet Provisioning](./service_clients//fleet_provisioning_basic.md) | Provision a device using the Fleet Provisioning template. | +| [CSR Fleet Provisioning](./service_clients//fleet_provisioning_csr.md) | Demonstrates CSR-based device certificate provisioning. | + + +### Greengrass Samples +##### Samples that interact with [AWS Greengrass](https://aws.amazon.com/greengrass/). +| Greengrass Sample | Description | +|--------|-------------| +| [Greengrass Discovery](./greengrass//basic_discovery.md) | Discover and connect to a local Greengrass core. | +| [Greengrass IPC](./greengrass//ipc_greengrass.md) | Demonstrates Inter-Process Communication (IPC) with Greengrass components. | + +### Instructions + +First, install `aws-iot-device-sdk-python-v2`. Installation instructions for the SDK are [Provided Here](../README.md#Installation). + +Each sample's README contains prerequisites, arguments, and detailed instructions. For example, the [MQTT5 X509 Sample README](./mqtt/mqtt5_x509.md) is `mqtt5_x509.md` and the sample can be run with the following command: + +``` sh +# For Windows: replace 'python3' with 'python' and '/' with '\' +python3 mqtt5_x509.py --endpoint --cert --key +``` + +### Sample Help + +All samples will show their options and arguments by passing in `--help`. For example: +``` sh +# For Windows: replace 'python3' with 'python' and '/' with '\' +python3 mqtt5_x509.py --help +``` + +will result in the following print output: +``` +MQTT5 X509 Sample (mTLS) + +options: + -h, --help show this help message and exit + +required arguments: + --endpoint IoT endpoint hostname (default: None) + --cert Path to the certificate file to use during mTLS connection establishment (default: None) + --key Path to the private key file to use during mTLS connection establishment (default: None) + +optional arguments: + --client_id Client ID (default: mqtt5-sample-5873a450) + --topic Topic (default: test/topic) + --message Message payload (default: Hello from mqtt5 sample) + --count Messages to publish (0 = infinite) (default: 5) +``` + +The sample will not run without the required arguments and will notify you of missing arguments. + +### Enable Logging + +Instructions to enable logging are available in the [FAQ](../documents/FAQ.md) under [How do I enable logging](../documents/FAQ.md#how-do-i-enable-logging). From c12a55014096773e1daf6bac8e6a3ed55c782f3e Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Fri, 3 Oct 2025 09:24:39 -0700 Subject: [PATCH 11/14] revert sample read me --- samples/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/samples/README.md b/samples/README.md index 23552f8a..21fcae26 100644 --- a/samples/README.md +++ b/samples/README.md @@ -82,3 +82,13 @@ The sample will not run without the required arguments and will notify you of mi ### Enable Logging Instructions to enable logging are available in the [FAQ](../documents/FAQ.md) under [How do I enable logging](../documents/FAQ.md#how-do-i-enable-logging). + +## ⚠️ Usage disclaimer + +These code examples interact with services that may incur charges to your AWS account. For more information, see [AWS Pricing](https://aws.amazon.com/pricing/). + +Additionally, example code might theoretically modify or delete existing AWS resources. As a matter of due diligence, do the following: + +- Be aware of the resources that these examples create or delete. +- Be aware of the costs that might be charged to your account as a result. +- Back up your important data. From 98236ee3c6d8cb2dcc2a0a4e49a22bf6551a66de Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Fri, 3 Oct 2025 09:42:09 -0700 Subject: [PATCH 12/14] rename the script file --- utils/{doc-links.txt => ci-aws-doc-links.txt} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename utils/{doc-links.txt => ci-aws-doc-links.txt} (100%) diff --git a/utils/doc-links.txt b/utils/ci-aws-doc-links.txt similarity index 100% rename from utils/doc-links.txt rename to utils/ci-aws-doc-links.txt From c165a3ca145c84658cb0d87b5155cef837649761 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Fri, 3 Oct 2025 09:42:54 -0700 Subject: [PATCH 13/14] rename the file --- .github/workflows/aws-service-sanity-check.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/aws-service-sanity-check.yml b/.github/workflows/aws-service-sanity-check.yml index e8f60324..30904a41 100644 --- a/.github/workflows/aws-service-sanity-check.yml +++ b/.github/workflows/aws-service-sanity-check.yml @@ -25,7 +25,7 @@ jobs: fi echo " - $file" fi - done < utils/doc-links.txt + done < utils/ci-aws-doc-links.txt if [ $missing -ge 1 ]; then echo "Instructions:" From 131fd60677e62d238a028124da4056b4fd1bb164 Mon Sep 17 00:00:00 2001 From: Vera Xia Date: Thu, 30 Oct 2025 14:04:16 -0700 Subject: [PATCH 14/14] add gg file --- utils/ci-aws-doc-links.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/utils/ci-aws-doc-links.txt b/utils/ci-aws-doc-links.txt index f353fe55..6b2e8c6c 100644 --- a/utils/ci-aws-doc-links.txt +++ b/utils/ci-aws-doc-links.txt @@ -1 +1,2 @@ samples/mqtt/mqtt5_x509.py +samples/greengrass/basic_discovery.py \ No newline at end of file