aws · xiazhvera · Sep 26, 2025 · Sep 11, 2025 · Sep 11, 2025 · Sep 11, 2025
diff --git a/.builder/actions/build_samples.py b/.builder/actions/build_samples.py
@@ -19,23 +19,26 @@ def run(self, env):
 
         steps = []
         samples = [
-            'samples/commands/commands-sandbox',
+            'samples/service_clients/commands/commands-sandbox',
             'samples/greengrass/basic_discovery',
             'samples/greengrass/ipc',
-            'samples/fleet_provisioning/provision-basic',
-            'samples/fleet_provisioning/provision-csr',
-            'samples/jobs/jobs-sandbox',
-            'samples/mqtt5/mqtt5_pubsub',
-            'samples/secure_tunneling/secure_tunnel',
-            'samples/secure_tunneling/tunnel_notification',
-            'samples/shadow/shadow-sandbox',
+            'samples/service_clients/fleet_provisioning/provision-basic',
+            'samples/service_clients/fleet_provisioning/provision-csr',
+            'samples/service_clients/jobs/jobs-sandbox',
+            'samples/mqtt/mqtt5_x509',
+            'samples/mqtt/mqtt5_aws_websocket',
+            'samples/mqtt/mqtt5_custom_auth_signed',
+            'samples/mqtt/mqtt5_custom_auth_unsigned',
+            'samples/mqtt/mqtt5_pkcs11',
+            'samples/others/secure_tunneling/secure_tunnel',
+            'samples/others/secure_tunneling/tunnel_notification',
+            'samples/service_clients/shadow/shadow-sandbox',
         ]
 
         defender_samples = []
         # Linux only builds
         if sys.platform == "linux" or sys.platform == "linux2":
-            defender_samples.append('samples/device_defender/basic_report')
-            defender_samples.append('samples/device_defender/mqtt5_basic_report')
+            defender_samples.append('samples/others/device_defender/mqtt5_basic_report')
 
         servicetests = [
             'servicetests/tests/JobsExecution/',

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -240,7 +240,7 @@ jobs:
         run: |
           cd ${{ env.CI_FOLDER }}
           echo "Starting to run AppVerifier with mqtt5 pub-sub sample"
-          python ${{ env.CI_UTILS_FOLDER }}/appverifier_launch_sample.py --sample_file ".\aws-iot-device-sdk-cpp-v2\build\samples\mqtt5\mqtt5_pubsub\RelWithDebInfo\mqtt5_pubsub.exe" --sample_secret_endpoint 'ci/endpoint' --sample_secret_certificate 'ci/mqtt5/us/mqtt5_thing/cert' --sample_secret_private_key 'ci/mqtt5/us/mqtt5_thing/key'
+          python ${{ env.CI_UTILS_FOLDER }}/appverifier_launch_sample.py --sample_file ".\aws-iot-device-sdk-cpp-v2\build\samples\mqtt\mqtt5_x509\RelWithDebInfo\mqtt5_x509.exe" --sample_secret_endpoint 'ci/endpoint' --sample_secret_certificate 'ci/mqtt5/us/mqtt5_thing/cert' --sample_secret_private_key 'ci/mqtt5/us/mqtt5_thing/key'
 
   windows-shared-lib:
     runs-on: windows-latest

diff --git a/devicedefender/script/DDTestRun.py b/devicedefender/script/DDTestRun.py
@@ -229,17 +229,17 @@ def delete_thing_with_certi(thingName, certiId, certiArn):
 
     if use_mqtt5:
         # Run the sample:
-        exe_path = "build/samples/device_defender/mqtt5_basic_report/"
+        exe_path = "build/samples/others/device_defender/mqtt5_basic_report/"
         # If running locally, comment out the line above and uncomment the line below:
-        #exe_path = "samples/device_defender/basic_report/build/"
+        #exe_path = "samples/others/device_defender/basic_report/build/"
 
         # Windows has a different build folder structure, but this ONLY runs on Linux currently so we do not need to worry about it
         exe_path = os.path.join(exe_path, "mqtt5-basic-report")
     else:
         # Run the sample:
-        exe_path = "build/samples/device_defender/basic_report/"
+        exe_path = "build/samples/others/device_defender/basic_report/"
         # If running locally, comment out the line above and uncomment the line below:
-        #exe_path = "samples/device_defender/basic_report/build/"
+        #exe_path = "samples/others/device_defender/basic_report/build/"
 
         # Windows has a different build folder structure, but this ONLY runs on Linux currently so we do not need to worry about it
         exe_path = os.path.join(exe_path, "basic-report")

diff --git a/documents/MIGRATION_GUIDE.md b/documents/MIGRATION_GUIDE.md
@@ -1369,8 +1369,8 @@ samples.
 
 It's always helpful to look at a working example to see how new functionality works,
 to be able to tweak different options, to compare with existing code.
-For that reason, we implemented a [Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt5/mqtt5_pubsub)
-([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_pubsub/main.cpp))
+For that reason, we implemented a [X509 Publish/Subscribe example](https://github.com/aws/aws-iot-device-sdk-cpp-v2/tree/main/samples/mqtt/mqtt5_x509)
+([source code](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt/mqtt5_x509/main.cpp))
 in the v2 SDK similar to a sample provided by the v1 SDK (see a corresponding
 [readme section](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/README.md) and
 [source code](https://github.com/aws/aws-iot-device-sdk-cpp/blob/master/samples/PubSub/PubSub.cpp)).
@@ -1438,9 +1438,7 @@ method in PublishPacketBuilder class.
 
 **Shared Subscriptions**\
 Shared Subscriptions allow multiple clients to share a subscription to a topic and only one client
-will receive messages published to that topic using a random distribution.\
-For more information, see a [shared subscription sample](https://github.com/aws/aws-iot-device-sdk-cpp-v2/blob/main/samples/mqtt5/mqtt5_shared_subscription/README.md)
-in the v2 SDK.
+will receive messages published to that topic using a random distribution.
 
 > [!NOTE]
 > AWS Iot Core supports Shared Subscriptions for both MQTT3 and MQTT5. For more information, see

diff --git a/documents/Secure_Tunnel_Userguide.md b/documents/Secure_Tunnel_Userguide.md
@@ -249,9 +249,9 @@ secureTunnel->SendMessage(message);
 
 # Secure Tunnel Best Practices
 * You MUST NOT perform blocking operations on any callback, or you will cause a deadlock.
-* If you do not provide a Client Token during creation of the Secure Tunnel, one will be automatically generated for you to use in reconnections. This token is not saved outside of the current Secure Tunnel Client. If the Client is destroyed, the original access tokens must be rotated to connect to the secure tunnel again. Information on rotating tokens can be found here: https://docs.aws.amazon.com/iot/latest/developerguide/iot-secure-tunneling-troubleshooting.html
+* If you do not provide a Client Token during creation of the Secure Tunnel, one will be automatically generated for you to use in reconnection. This token is not saved outside of the current Secure Tunnel Client. If the Client is destroyed, the original access tokens must be rotated to connect to the secure tunnel again. Information on rotating tokens can be found here: https://docs.aws.amazon.com/iot/latest/developerguide/iot-secure-tunneling-troubleshooting.html
 * Client tokens MUST be unique. You cannot for example, pair a Client Token with an Access Token on one secure tunnel, and then use the same Client Token with a different Access Token on a separate secure tunnel. The Secure Tunnel Service will not allow a Client Token to be paired with more than one Access Token.
 * A Secure Tunnel Client that has called `Start()` will continue to attempt to connect the Secure Tunnel Service until `Stop()` is called, even if the Secure Tunnel it is trying to connect with has been closed. You MUST call `Stop()` to cease future connection attempts.
-* The [onStreamStarted](#onstreamstarted) and [onConnectionStarted](#onconnectionstarted) callbacks should be set to detect and store the service id and/or connection id of streams started by a source device for use with messages. The [Secure Tunnel sample](../samples/secure_tunneling/secure_tunnel/README.md) provides an basic example of how this can be done.
+* The [onStreamStarted](#onstreamstarted) and [onConnectionStarted](#onconnectionstarted) callbacks should be set to detect and store the service id and/or connection id of streams started by a source device for use with messages. The [Secure Tunnel sample](../samples/others/secure_tunneling/secure_tunnel/README.md) provides an basic example of how this can be done.
 * Outgoing messages MUST be assigned a service id and/or a connection id if the established stream contains a service id or a connection id or the message will be rejected. e.g. If a stream is started using service id "ssh" and connection id (1), a message sent in response must also include the service id "ssh" and connection id (1) or it will not find an active stream to send it on. Refer to the [Send Message](#send-message) code block for instruction on adding a service id and/or connection id to your message.
 
diff --git a/samples/CMakeLists.txt b/samples/CMakeLists.txt
@@ -2,15 +2,18 @@ cmake_minimum_required(VERSION 3.9...3.31)
 
 project(aws-iot-device-sdk-cpp-v2-samples)
 
-add_subdirectory(device_defender/basic_report)
-add_subdirectory(device_defender/mqtt5_basic_report)
-add_subdirectory(fleet_provisioning/provision-basic)
-add_subdirectory(fleet_provisioning/provision-csr)
+add_subdirectory(others/device_defender/mqtt5_basic_report)
+add_subdirectory(service_clients/fleet_provisioning/provision-basic)
+add_subdirectory(service_clients/fleet_provisioning/provision-csr)
 add_subdirectory(greengrass/ipc)
 add_subdirectory(greengrass/basic_discovery)
-add_subdirectory(jobs/jobs-sandbox)
-add_subdirectory(mqtt5/mqtt5_pubsub)
-add_subdirectory(secure_tunneling/secure_tunnel)
-add_subdirectory(secure_tunneling/tunnel_notification)
-add_subdirectory(shadow/shadow_sync)
-add_subdirectory(commands/commands-sandbox)
+add_subdirectory(service_clients/jobs/jobs-sandbox)
+add_subdirectory(mqtt/mqtt5_x509)
+add_subdirectory(mqtt/mqtt5_aws_websocket)
+add_subdirectory(mqtt/mqtt5_custom_auth_signed)
+add_subdirectory(mqtt/mqtt5_custom_auth_unsigned)
+add_subdirectory(mqtt/mqtt5_pkcs11)
+add_subdirectory(others/secure_tunneling/secure_tunnel)
+add_subdirectory(others/secure_tunneling/tunnel_notification)
+add_subdirectory(service_clients/shadow/shadow-sandbox)
+add_subdirectory(service_clients/commands/commands-sandbox)
diff --git a/samples/README.md b/samples/README.md
@@ -1,28 +1,56 @@
-# Sample apps for the AWS IoT Device SDK for C++ v2
-
-## MQTT5 Samples
-#### MQTT5 is the recommended MQTT Client. It has many benefits over MQTT311 outlined in the [MQTT5 User Guide](../documents/MQTT5_Userguide.md)
-* [Mqtt5 Pub-Sub](./mqtt5/mqtt5_pubsub/README.md)
-    + [Direct MQTT with X509-based mutual TLS](./mqtt5/mqtt5_pubsub/README.md#direct-mqtt-with-x509-based-mutual-tls)
-    + [MQTT over Websockets with Sigv4 authentication](./mqtt5/mqtt5_pubsub/README.md#mqtt-over-websockets-with-sigv4-authentication)
-    + [Direct MQTT with Custom Authentication](./mqtt5/mqtt5_pubsub/README.md#direct-mqtt-with-custom-authentication)
-    + [MQTT over Websockets with Cognito](./mqtt5/mqtt5_pubsub/README.md#mqtt-over-websockets-with-cognito)
-    + [HTTP Proxy](./mqtt5/mqtt5_pubsub/README.md#http-proxy)
-## Other Samples
-* [Jobs Sandbox](./jobs/jobs-sandbox/README.md)
-* [Shadow Sandbox](./shadow/shadow-sandbox/README.md)
-* [Basic Fleet Provisioning](./fleet_provisioning/provision-basic/README.md)
-* [CSR Fleet Provisioning](./fleet_provisioning/provision-csr/README.md)
-* [Commands Sandbox](./commands/commands-sandbox/README.md)
-* [Secure Tunnel](./secure_tunneling/secure_tunnel/README.md)
-* [Secure Tunnel Notification](./secure_tunneling/tunnel_notification/README.md)
-* [Cycle Pub-Sub](./pub_sub/cycle_pub_sub/README.md)
-* [Greengrass discovery](./greengrass/basic_discovery/README.md)
-* [Greengrass IPC](./greengrass/ipc/README.md)
-* [Mqtt5 Device Defender](./device_defender/mqtt5_basic_report/README.md)
-* [Mqtt311 Device Defender](./device_defender/basic_report/README.md)
-
-## Build Instruction
+# Sample for the AWS IoT Device SDK v2 for C++
+This directory contains sample applications for [aws-iot-device-sdk-cpp-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 information 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/README.md) | Demonstrates connecting to AWS IoT Core using X.509 certificates and private keys.
+| [Websockets with Sigv4 authentication](./mqtt/mqtt5_aws_websocket/README.md) | Shows how to authenticate over websockets using AWS Signature Version 4 credentials. |
+| [AWS Custom Authorizer Lambda Function](./mqtt/mqtt5_custom_auth_signed/README.md) | Examples of connecting with a signed and unsigned Lambda-backed custom authorizer.
+| [PKCS11](./mqtt/mqtt5_pkcs11/README.md) | Demonstrates connecting using a hardware security module (HSM) or smartcard with PKCS#11. |
+| [Other Connection Methods](../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core) | 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/shadow-sandbox/README.md) | Manage and sync device state using the IoT Device Shadow service. |
+| [Jobs](./service_clients/jobs/jobs-sandbox/README.md) | Receive and execute remote operations sent from the Jobs service. |
+| [Basic Fleet Provisioning](./service_clients/fleet_provisioning/provision-basic/README.md) | Provision a device using the Fleet Provisioning template. |
+| [CSR Fleet Provisioning](./service_clients/fleet_provisioning/provision-csr/README.md) | Demonstrates CSR-based device certificate provisioning. |
+| [Commands](./service_clients/commands/commands-sandbox/README.md) | Receive and process remote instructions using AWS IoT Device Management commands |
+
+
+### Greengrass Samples
+##### Samples that interact with [AWS Greengrass](https://aws.amazon.com/greengrass/).
+| Greengrass Sample | Description |
+|--------|-------------|
+| [Greengrass Discovery](./greengrass/basic_discovery/README.md) | Discover and connect to a local Greengrass core. |
+| [Greengrass IPC](./greengrass/ipc/README.md) | Demonstrates Inter-Process Communication (IPC) with Greengrass components. |
+
+### Others
+##### Samples that interact with other AWS IoT Services
+| Sample | Description |
+|--------|-------------|
+| [Device Defender](./others/device_defender/mqtt5_basic_report/README.md) | Monitor the health of your IoT device using AWS IoT Device Defender. |
+| [Secure Tunneling](./others/secure_tunneling/secure_tunnel/README.md) | Connect a destination or a source Secure Tunnel Client to an AWS IoT Secure Tunnel endpoint. |
+| [Secure Tunneling Notification](./others/secure_tunneling/tunnel_notification/README.md) | Receive a tunnel notification using a Secure Tunnel Client. |
+
+
+
+## Instructions
 
 First build and install aws-iot-devices-sdk-cpp-v2 with following instructions from [Installation](../README.md#Installation).
 
@@ -53,13 +81,7 @@ cmake -B build -S . -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>"
 cmake --build build --config "<Release|RelWithDebInfo|Debug>"
 ```
 
-This will compile all the samples at once and place the executables under the `build` directory relative to their file path. To view the commands for a given sample, run the compiled program and pass `--help`. For example, with the MQTT5 PubSub sample:
-
-```sh
-./build/mqtt5/mqtt5_pubsub/mqtt5_pubsub --help
-```
-
-This will compile all of the samples at once. You can then find the samples in the `aws-iot-device-sdk-cpp-v2/samples/build` folder. For example, the MQTT5 PubSub sample will be located at `aws-iot-device-sdk-cpp-v2/samples/build/mqtt5/mqtt5_pubsub`.
+This will compile all of the samples at once. You can then find the samples in the `aws-iot-device-sdk-cpp-v2/samples/build` folder. For example, the MQTT5 PubSub sample will be located at `aws-iot-device-sdk-cpp-v2/samples/build/mqtt/mqtt5_x509`.
 
 For CMake versions that do not support the `-B` command, go to the `aws-iot-device-sdk-cpp-v2/samples` directory and run the following commands:
 
@@ -78,23 +100,31 @@ Note that building all the samples at once is currently only available in the V2
 
 * `-DCMAKE_BUILD_TYPE` and `--config` needs to match the `CMAKE_BUILD_TYPE` when aws-iot-device-sdk-cpp-v2 built. `--config` is only REQUIRED for multi-configuration build tools.
 
-### Sample help
+## Sample help
 
-All samples will show their options by passing in `--help`. For example:
+All samples will show their options and arguments by passing in `--help`. For example:
 
 ```sh
-./build/mqtt5/mqtt5_pubsub/mqtt5_pubsub --help
+./build/mqtt/mqtt5_x509/mqtt5_x509 --help
 ```
-
-Which will result in output showing all of the options that can be passed in at the command line, along with descriptions of what each does and whether or not they are optional or not.
-
-### Enable logging in samples
-
-To enable logging in the samples, you can pass in `--verbosity`, and optionally `--log_file`, to the sample:
-
-```sh
-./build/basic-pub-sub --verbosity "Trace" --log_file "log.txt"
+will result in the following print output:
 ```
+MQTT5 X509 Sample (mTLS)
+options:
+  --help        show this help message and exit
+required arguments:
+  --endpoint    IoT endpoint hostname
+  --cert        Path to the certificate file to use during mTLS connection establishment
+  --key         Path to the private key file to use during mTLS connection establishment
+optional arguments:
+  --client_id   Client ID (default: mqtt5-sample-<uuid>)
+  --ca_file     Path to optional CA bundle (PEM)
+  --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 in samples
 
-* `--verbosity`: The level of logging shown. Can be `Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal` or `None`. Logging will not occur if this is not passed in with `None` or greater logging level.
-* `--log_file`: The filepath to store the logs at. This is optional, and if undefined the logs will be printed to `stdout` instead.
+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/device_defender/basic_report/CMakeLists.txt b/samples/device_defender/basic_report/CMakeLists.txt