Skip to content

Commit 188f65d

Browse files
graebmgraebm
authored
README (#6)
1 parent a90c1a1 commit 188f65d

File tree

3 files changed

+181
-11
lines changed

3 files changed

+181
-11
lines changed

‎README.md

Lines changed: 166 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,169 @@
1-
## AWS IoT SDK for Python v2
1+
# AWS IoT SDK for Python v2
22

3-
Next generation AWS IoT Client SDK for Python using the AWS Common Runtime
3+
Next generation AWS IoT Client SDK for Python.
44

5-
## License
5+
This SDK is built on the AWS Common Runtime, a collection of libraries
6+
([1](https://github.com/awslabs/aws-c-common),
7+
[2](https://github.com/awslabs/aws-c-io),
8+
[3](https://github.com/awslabs/aws-c-mqtt), ...) written in C to be
9+
cross-platform, high-performance, secure, and reliable. The libraries are bound
10+
to Python by the [awscrt](https://github.com/awslabs/aws-crt-python) package.
611

7-
This library is licensed under the Apache 2.0 License.
12+
Integration with AWS IoT Services such as
13+
[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
14+
and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
15+
is provided by code that been generated from a model of the service.
16+
17+
# Installation
18+
## Minimum Requirements
19+
* Python 3.5+ or Python 2.7+
20+
* CMake 3.1+
21+
* Clang 3.9+ or GCC 4.4+ or MSVC 2015+
22+
23+
## Build from source
24+
```
25+
git clone https://github.com/awslabs/aws-crt-python.git --recursive
26+
git clone https://github.com/awslabs/aws-iot-device-sdk-python-v2.git
27+
pip install ./aws-crt-python
28+
pip install ./aws-iot-device-sdk-python-v2
29+
```
30+
31+
# Samples
32+
33+
## pubsub
34+
This sample uses the Message Broker for AWS IoT to send and receive messages
35+
through an MQTT connection. On startup, the device connects to the server,
36+
subscribes to a topic, and begins publishing messages to that topic.
37+
The device should receive those same messages back from the message broker,
38+
since it is subscribed to that same topic.
39+
Status updates are continually printed to the console.
40+
41+
Source: `samples/pubsub.py`
42+
43+
Run the sample like this:
44+
```
45+
python pubsub.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file>
46+
```
47+
48+
Your Thing's
49+
[Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html)
50+
must provide privileges for this sample to connect, subscribe, publish,
51+
and receive. The Policy document should look something like this:
52+
53+
<pre>
54+
{
55+
"Version": "2012-10-17",
56+
"Statement": [
57+
{
58+
"Effect": "Allow",
59+
"Action": [
60+
"iot:Publish",
61+
"iot:Receive"
62+
],
63+
"Resource": [
64+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/samples/test"
65+
]
66+
},
67+
{
68+
"Effect": "Allow",
69+
"Action": [
70+
"iot:Subscribe"
71+
],
72+
"Resource": [
73+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/samples/test"
74+
]
75+
},
76+
{
77+
"Effect": "Allow",
78+
"Action": [
79+
"iot:Connect"
80+
],
81+
"Resource": [
82+
"arn:aws:iot:<b>region</b>:<b>account</b>:client/samples-client-id"
83+
]
84+
}
85+
]
86+
}
87+
</pre>
88+
89+
## shadow
90+
91+
This sample uses the AWS IoT Device Shadow Service to keep a property in
92+
sync between device and server. Imagine a light whose color may be changed
93+
through an app, or set by a local user.
94+
95+
Once connected, type a value in the terminal and press Enter to update
96+
the property's "reported" value. The sample also responds when the "desired"
97+
value changes on the server. To observe this, edit the Shadow document in
98+
the AWS Console and set a new "desired" value.
99+
100+
On startup, the sample requests the shadow document to learn the property's
101+
initial state. The sample also subscribes to "delta" events from the server,
102+
which are sent when a property's "desired" value differs from its "reported"
103+
value. When the sample learns of a new desired value, that value is changed
104+
on the device and an update is sent to the server with the new "reported"
105+
value.
106+
107+
Source: `samples/shadow.py`
108+
109+
Run the sample like this:
110+
```
111+
python shadow.py --endpoint <endpoint> --root-ca <file> --cert <file> --key <file> --thing-name <name>
112+
```
113+
114+
Your Thing's
115+
[Policy](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html)
116+
must provide privileges for this sample to connect, subscribe, publish,
117+
and receive. The Policy document should look something like this:
118+
119+
<pre>
120+
{
121+
"Version": "2012-10-17",
122+
"Statement": [
123+
{
124+
"Effect": "Allow",
125+
"Action": [
126+
"iot:Publish"
127+
],
128+
"Resource": [
129+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/get",
130+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update"
131+
]
132+
},
133+
{
134+
"Effect": "Allow",
135+
"Action": [
136+
"iot:Receive"
137+
],
138+
"Resource": [
139+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/get/accepted",
140+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/get/rejected",
141+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update/accepted",
142+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update/rejected",
143+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/shadow/update/delta"
144+
]
145+
},
146+
{
147+
"Effect": "Allow",
148+
"Action": [
149+
"iot:Subscribe"
150+
],
151+
"Resource": [
152+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/get/accepted",
153+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/get/rejected",
154+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/update/accepted",
155+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/update/rejected",
156+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/shadow/update/delta"
157+
]
158+
},
159+
{
160+
"Effect": "Allow",
161+
"Action": "iot:Connect",
162+
"Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:client/samples-client-id"
163+
}
164+
]
165+
}
166+
</pre>
167+
# License
168+
169+
This library is licensed under the Apache 2.0 License.

‎samples/pubsub.py

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -18,21 +18,22 @@
1818
import threading
1919
import time
2020

21-
# This sample uses the Message Broken for AWS IoT to send and receive messages
21+
# This sample uses the Message Broker for AWS IoT to send and receive messages
2222
# through an MQTT connection. On startup, the device connects to the server,
2323
# subscribes to a topic, and begins publishing messages to that topic.
24-
# The device should receive those same messages back from the message broken,
24+
# The device should receive those same messages back from the message broker,
2525
# since it is subscribed to that same topic.
2626

2727
parser = argparse.ArgumentParser(description="Send and receive messages through and MQTT connection.")
2828
parser.add_argument('--endpoint', required=True, help="Your AWS IoT custom endpoint, not including a port. " +
29-
"Ex: \"w6zbse3vjd5b4p-ats.iot.us-west-2.amazonaws.com\"")
29+
"Ex: \"abcd123456wxyz-ats.iot.us-east-1.amazonaws.com\"")
3030
parser.add_argument('--cert', required=True, help="File path to your client certificate, in PEM format.")
3131
parser.add_argument('--key', required=True, help="File path to your private key, in PEM format.")
3232
parser.add_argument('--root-ca', help="File path to root certificate authority, in PEM format. " +
3333
"Necessary if MQTT server uses a certificate that's not already in " +
3434
"your trust store.")
35-
parser.add_argument('--topic', default="sample/test", help="Topic to subscribe to, and publish messages to.")
35+
parser.add_argument('--client-id', default='samples-client-id', help="Client ID for MQTT connection.")
36+
parser.add_argument('--topic', default="samples/test", help="Topic to subscribe to, and publish messages to.")
3637
parser.add_argument('--message', default="Hello World!", help="Message to publish. " +
3738
"Specify empty string to publish nothing.")
3839
parser.add_argument('--count', default=10, type=int, help="Number of messages to publish/receive before exiting. " +
@@ -102,10 +103,13 @@ def on_message_received(topic, message):
102103

103104
# Create connection
104105
port = 443 if io.is_alpn_available() else 8883
105-
print("Connecting to {} on port {}...".format(args.endpoint, port))
106+
107+
print("Connecting to {} on port {} with client ID '{}'...".format(
108+
args.endpoint, port, args.client_id))
109+
106110
mqtt_connection = mqtt.Connection(
107111
client=mqtt_client,
108-
client_id='samples_client_id')
112+
client_id=args.client_id)
109113
mqtt_connection.connect(
110114
host_name = args.endpoint,
111115
port = port,
@@ -152,6 +156,9 @@ def on_message_received(topic, message):
152156

153157
# Wait for all messages to be received.
154158
# This waits forever if count was set to 0.
159+
if args.count != 0 and not received_all_event.is_set():
160+
print("Waiting for all messages to be received...")
161+
155162
received_all_event.wait()
156163
print("{} message(s) received.".format(received_count))
157164

‎samples/shadow.py

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@
4747
parser.add_argument('--root-ca', help="File path to root certificate authority, in PEM format. " +
4848
"Necessary if MQTT server uses a certificate that's not already in " +
4949
"your trust store")
50+
parser.add_argument('--client-id', default='samples-client-id', help="Client ID for MQTT connection.")
5051
parser.add_argument('--thing-name', required=True, help="The name assigned to your IoT Thing")
5152
parser.add_argument('--shadow-property', default="color", help="Name of property in shadow to keep in sync")
5253

@@ -244,7 +245,7 @@ def user_input_thread_fn():
244245
print("Connecting to {} on port {}...".format(args.endpoint, port))
245246
mqtt_connection = mqtt.Connection(
246247
client=mqtt_client,
247-
client_id='samples_client_id')
248+
client_id=args.client_id)
248249
mqtt_connection.connect(
249250
host_name = args.endpoint,
250251
port = port,

0 commit comments

Comments
 (0)