Skip to content

Commit b927d0a

Browse files
sbSteveKsbSteveK
committed
update more readme files
1 parent 3ffa0a2 commit b927d0a

File tree

4 files changed

+143
-24
lines changed

4 files changed

+143
-24
lines changed

‎samples/mqtt/mqtt5_aws_websocket.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# MQTT5 AWS Websocket PubSub
2+
3+
[**Return to main sample list**](../README.md)
4+
*__Jump To:__*
5+
* [Introduction](#introduction)
6+
* [Requirements](#requirements)
7+
* [How To Run](#how-to-run)
8+
* [Additional Information](#additional-information)
9+
10+
## Introduction
11+
This sample uses the
12+
[Message Broker](https://docs.aws.amazon.com/iot/latest/developerguide/iot-message-broker.html)
13+
for AWS IoT to send and receive messages through an MQTT connection using MQTT5 and a websocket as transport. AWS Websocket requires the initial handshake request to be signed with the AWS Sigv4 signing algorithm. [`AwsCredentialsProvider.new_default_chain`](https://github.com/awslabs/aws-crt-python/blob/main/awscrt/auth.py) is used to source credentials via the default credentials provider chain to sign the websocket handshake.
14+
15+
You can read more about MQTT5 for the Python IoT Device SDK V2 in the [MQTT5 user guide](../../documents/MQTT5_Userguide.md).
16+
17+
## Requirements
18+
19+
The AWS IAM permission policy associated with the AWS credentials resolved by the default credentials provider chain must provide privileges for the sample to connect, subscribe, publish, and receive. Below is a sample policy will allow this sample to run as intended.
20+
21+
<details>
22+
<summary>(see sample policy)</summary>
23+
<pre>
24+
{
25+
"Version": "2012-10-17",
26+
"Statement": [
27+
{
28+
"Effect": "Allow",
29+
"Action": [
30+
"iot:Publish",
31+
"iot:Receive"
32+
],
33+
"Resource": [
34+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/test/topic"
35+
]
36+
},
37+
{
38+
"Effect": "Allow",
39+
"Action": [
40+
"iot:Subscribe"
41+
],
42+
"Resource": [
43+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/test/topic"
44+
]
45+
},
46+
{
47+
"Effect": "Allow",
48+
"Action": [
49+
"iot:Connect"
50+
],
51+
"Resource": [
52+
"arn:aws:iot:<b>region</b>:<b>account</b>:client/test-*"
53+
]
54+
}
55+
]
56+
}å
57+
</pre>
58+
59+
Replace with the following with the data from your AWS account:
60+
* `<region>`: 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`.
61+
* `<account>`: 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.
62+
63+
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 <client ID here>` to send the client ID your policy supports.
64+
65+
</details>
66+
67+
## How to run
68+
69+
To Run this sample from the `samples\mqtt` folder, use the following command:
70+
71+
```sh
72+
# For Windows: replace 'python3' with 'python' and '/' with '\'
73+
python3 mqtt5_aws_websocket.py \
74+
--endpoint <AWS IoT endpoint> \
75+
--signing-region <Signing region for websocket connection>
76+
```
77+
If you would like to see what optional arguments are available, use the `--help` argument:
78+
``` sh
79+
# For Windows: replace 'python3' with 'python' and '/' with '\'
80+
python3 mqtt5_aws_websocket.py --help
81+
```
82+
83+
will result in the following output:
84+
```
85+
MQTT5 AWS Websocket Sample.
86+
87+
options:
88+
-h, --help show this help message and exit
89+
90+
required arguments:
91+
--endpoint IoT endpoint hostname (default: None)
92+
--signing-region Signing region for websocket connection (default: None)
93+
94+
optional arguments:
95+
--client-id Client ID (default: mqtt5-sample-809571c8)
96+
--ca_file Path to optional CA bundle (PEM) (default: None)
97+
--topic Topic (default: test/topic)
98+
--message Message payload (default: Hello from mqtt5 sample)
99+
--count Messages to publish (0 = infinite) (default: 5)
100+
```
101+
102+
The sample will not run without the required arguments and will notify you of missing arguments.
103+
104+
## Additional Information
105+
Additional help with the MQTT5 Client can be found in the [MQTT5 Userguide](../../documents/MQTT5_Userguide.md). This guide will provide more details on MQTT5 [operations](../../documents/MQTT5_Userguide.md#optional-keyword-arguments), [lifecycle events](../../documents/MQTT5_Userguide.md#lifecycle-events), [connection methods](../../documents/MQTT5_Userguide.md#connecting-to-aws-iot-core), and other useful information.

‎samples/mqtt/mqtt5_custom_auth.md‎

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Custom Authorizer Connect
1+
# MQTT5 Custom Authorizer PubSub
22

33
[**Return to main sample list**](../README.md)
44
*__Jump To:__*
@@ -76,19 +76,19 @@ To Run this sample from the `samples\mqtt` folder, use the following command:
7676
# For an unsigned custom authorizer
7777
python3 mqtt5_custom_auth_unsigned.py \
7878
--endpoint <AWS IoT endpoint> \
79-
--authorizer_name <authorizer name> \
80-
--auth_username <username data used by the authorizer Lambda>\
81-
--auth_password <password data used by the authorizer Lambda>
79+
--authorizer_name <The name of the custom authorizer to connect to invoke> \
80+
--auth_username <The name to send when connecting through the custom authorizer>\
81+
--auth_password <The password to send when connecting through a custom authorizer>
8282

8383
# For a signed custom authorizer
8484
python3 mqtt5_custom_auth_signed.py \
8585
--endpoint <AWS IoT endpoint> \
86-
--authorizer_name <authorizer name> \
87-
--auth_token_key_name <name used to pass the token key value during authentication> \
88-
--auth_token_key_value <developer-chosen value whose digital signature passed to authenticate> \
89-
--auth_signature <url-encoded base64-encoded digital signature of <authorizer-token-key-value>> \
90-
--auth_username <username data used by the authorizer Lambda> \
91-
--auth_password <password data used by the authorizer Lambda>
86+
--authorizer_name <The name of the custom authorizer to connect to invoke> \
87+
--auth_token_key_name <Authorizer token key name> \
88+
--auth_token_key_value <Authorizer token key value> \
89+
--auth_signature <Custom authorizer signature> \
90+
--auth_username <The name to send when connecting through the custom authorizer> \
91+
--auth_password <The password to send when connecting through a custom authorizer>
9292

9393
```
9494
If you would like to see optional arguments, use the `--help` argument:
@@ -104,22 +104,27 @@ python3 mqtt5_custom_auth_signed.py --help
104104

105105
will result in the following output:
106106
```
107-
MQTT5 X509 Sample (mTLS)
107+
MQTT5 Unsigned Custom Authorizer Sample
108108
109109
options:
110-
-h, --help show this help message and exit
110+
-h, --help show this help message and exit
111111
112112
required arguments:
113-
--endpoint IoT endpoint hostname (default: None)
114-
--cert Path to the certificate file to use during mTLS connection establishment (default: None)
115-
--key Path to the private key file to use during mTLS connection establishment (default: None)
113+
--endpoint IoT endpoint hostname (default: None)
114+
--authorizer_name The name of the custom authorizer to connect to invoke (default: None)
115+
--auth_signature Custom authorizer signature (default: None)
116+
--auth_token_key_name
117+
Authorizer token key name (default: None)
118+
--auth_token_key_value
119+
Authorizer token key value (default: None)
120+
--auth_username The name to send when connecting through the custom authorizer (optional) (default: None)
121+
--auth_password The password to send when connecting through a custom authorizer (optional) (default: None)
116122
117123
optional arguments:
118-
--client-id Client ID (default: mqtt5-sample-5873a450)
119-
--ca_file Path to optional CA bundle (PEM) (default: None)
120-
--topic Topic (default: test/topic)
121-
--message Message payload (default: Hello from mqtt5 sample)
122-
--count Messages to publish (0 = infinite) (default: 5)
124+
--client-id Client ID (default: test-f3168b42)
125+
--topic Topic (default: test/topic)
126+
--message Message payload (default: Hello from mqtt5 sample)
127+
--count Messages to publish (0 = infinite) (default: 5)
123128
```
124129

125130
The sample will not run without the required arguments and will notify you of missing arguments.

‎samples/mqtt/mqtt5_pkcs11_connect.md‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# PKCS#11 Connect
1+
# MQTT5 PKCS#11 PubSub
22

33
[**Return to main sample list**](../README.md)
44
*__Jump To:__*
@@ -73,7 +73,13 @@ The MQTT5 PKCS11 connect sample can be run from the `samples\mqtt` folder using
7373

7474
```sh
7575
# For Windows: replace 'python3' with 'python' and '/' with '\'
76-
python3 mqtt5_pkcs11_connect.py --endpoint <endpoint> --cert <path to certificate> --pkcs11_lib <path to PKCS11 lib> --pin <user-pin> --token_label <token-label> --key_label <key-label>
76+
python3 mqtt5_pkcs11_connect.py \
77+
--endpoint <AWS IoT endpoint> \
78+
--cert <path to certificate file> \
79+
--pkcs11_lib <Path to PKCS#11 Library> \
80+
--pin <User PIN for logging into PKCS#11 token> \
81+
--token_label <Label of the PKCS#11 token to use (optional)> \
82+
--key_label <Label of private key on the PKCS#11 token (optional)>
7783
```
7884

7985
If you would like to see what optional arguments are available, use the `--help` argument:

‎samples/mqtt/mqtt5_x509.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ Your IoT Core Thing's [Policy](https://docs.aws.amazon.com/iot/latest/developerg
5555
]
5656
}
5757
]
58-
}
58+
}å
5959
</pre>
6060

6161
Replace with the following with the data from your AWS account:
@@ -72,7 +72,10 @@ To Run this sample from the `samples\mqtt` folder, use the following command:
7272

7373
```sh
7474
# For Windows: replace 'python3' with 'python' and '/' with '\'
75-
python3 mqtt5_x509.py --endpoint <endpoint> --cert <file> --key <file>
75+
python3 mqtt5_x509.py \
76+
--endpoint <AWS IoT endpoint> \
77+
--cert <Path to certificate file> \
78+
--key <Path to private key file>
7679
```
7780
If you would like to see what optional arguments are available, use the `--help` argument:
7881
``` sh

0 commit comments

Comments
 (0)