Skip to content

Commit 89e17e9

Browse files
TwistedTwiglegTwistedTwigleg
authored
Minor modifications to the sample README file (#373)
* Modified the basic pub sub sample section of the README.md file * Adjusted Sample README to include a section on how to use Websockets with the pub-sub sample * Adjusted the samples README for the raw-pub-sub sample, the shadow sample, and the jobs sample * Adjusted samples README based on feedback and fixes for policy markdown rendering
1 parent f6e5fc1 commit 89e17e9

File tree

1 file changed

+84
-35
lines changed

1 file changed

+84
-35
lines changed

‎samples/README.md

Lines changed: 84 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,12 @@ cmake -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DCMAKE_BUILD_
2424
cmake --build . --config "<Release|RelWithDebInfo|Debug>"
2525
```
2626

27+
To view the commands for a given sample, run the compiled program and pass `--help`.
28+
29+
```
30+
./basic-pub-sub --help
31+
```
32+
2733
#### Note
2834

2935
* `-DCMAKE_PREFIX_PATH` needs to be set to the path aws-iot-device-sdk-cpp-v2 installed. Since [Installation](../README.md#Installation) takes sdk-cpp-workspace as an example, here takes that as an example too.
@@ -35,11 +41,7 @@ cmake --build . --config "<Release|RelWithDebInfo|Debug>"
3541
This sample uses the
3642
[Message Broker](https://docs.aws.amazon.com/iot/latest/developerguide/iot-message-broker.html)
3743
for AWS IoT to send and receive messages through an MQTT connection.
38-
On startup, the device connects to the server and subscribes to a topic.
39-
40-
The terminal prompts the user for input. Type something and press enter to publish a message to the topic.
41-
Since the sample is subscribed to the same topic, it will also receive the message back from the server.
42-
Type `quit` and press enter to end the sample.
44+
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.
4345

4446
Source: `samples/mqtt/basic_pub_sub/main.cpp`
4547

@@ -54,7 +56,6 @@ and receive.
5456
{
5557
"Version": "2012-10-17",
5658
"Statement": [
57-
5859
{
5960
"Effect": "Allow",
6061
"Action": [
@@ -83,7 +84,6 @@ and receive.
8384
"arn:aws:iot:<b>region</b>:<b>account</b>:client/test-*"
8485
]
8586
}
86-
8787
]
8888
}
8989
</pre>
@@ -97,6 +97,23 @@ To run the basic MQTT Pub-Sub use the following command:
9797
--topic <topic name>
9898
```
9999

100+
To run this sample using websockets, see below:
101+
102+
<details>
103+
<summary>(Websockets)</summary>
104+
105+
To run using Websockets, use the following command:
106+
107+
``` sh
108+
./basic-pub-sub --endpoint <endpoint> --topic <topic name> --ca_file <path to root CA>
109+
--use_websocket --signing_region <signing_region>
110+
```
111+
112+
Note that using Websockets will attempt to fetch the AWS credentials from your enviornment variables or local files.
113+
See the [authorizing direct AWS](https://docs.aws.amazon.com/iot/latest/developerguide/authorizing-direct-aws.html) page for documentation on how to get the AWS credentials, which then you can set to the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS`, and `AWS_SESSION_TOKEN` environment variables.
114+
115+
</details>
116+
100117
## PKCS#11 MQTT Pub-Sub
101118

102119
This sample is similar to the [Basic Pub-Sub](#basic-mqtt-pub-sub),
@@ -147,7 +164,7 @@ To run this sample using [SoftHSM2](https://www.opendnssec.org/softhsm/) as the
147164
148165
5) Now you can run the sample:
149166
```sh
150-
./pkcs11-pub-sub --endpoint <xxxx-ats.iot.xxxx.amazonaws.com> --ca_file <AmazonRootCA1.pem> --cert <certificate.pem.crt> --pkcs11_lib <libsofthsm2.so> --pin <user-pin> --token_label <token-label> --key_label <key-label>
167+
./pkcs11-pub-sub --endpoint <xxxx-ats.iot.xxxx.amazonaws.com> --ca_file <AmazonRootCA.pem> --cert <certificate.pem.crt> --pkcs11_lib <libsofthsm2.so> --pin <user-pin> --token_label <token-label> --key_label <key-label>
151168
```
152169
153170
@@ -159,6 +176,16 @@ This is a starting point for using custom
159176
160177
source: `samples/mqtt/raw_pub_sub/main.cpp`
161178
179+
To run the Raw MQTT Pub-Sub sample use the following command:
180+
181+
``` sh
182+
./raw-pub-sub --endpoint <endpoint> --ca_file <path to root CA>
183+
--cert <path to the certificate> --key <path to the private key>
184+
--topic <topic name> --user_name <user name to send on connect> --password <password to send on connect>
185+
```
186+
187+
This will allow you to run the program. To disconnect and exit the program, enter `exit`.
188+
162189
## Shadow
163190
164191
This sample uses the AWS IoT
@@ -192,7 +219,6 @@ and receive.
192219
{
193220
"Version": "2012-10-17",
194221
"Statement": [
195-
196222
{
197223
"Effect": "Allow",
198224
"Action": [
@@ -234,12 +260,21 @@ and receive.
234260
"Action": "iot:Connect",
235261
"Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:client/test-*"
236262
}
237-
238263
]
239264
}
240265
</pre>
241266
</details>
242267
268+
To run the Shadow sample use the following command:
269+
270+
``` sh
271+
./shadow-sync --endpoint <endpoint> --ca_file <path to root CA>
272+
--cert <path to the certificate> --key <path to the private key>
273+
--thing_name <thing name> --shadow_property <shadow property name>
274+
```
275+
276+
This will allow you to run the program and set the shadow property. To disconnect and exit the program, enter `quit`.
277+
243278
## Jobs
244279
245280
This sample uses the AWS IoT
@@ -263,54 +298,68 @@ and receive.
263298
{
264299
"Version": "2012-10-17",
265300
"Statement": [
266-
267301
{
268302
"Effect": "Allow",
269-
"Action": [
270-
"iot:Publish"
271-
],
303+
"Action": "iot:Connect",
272304
"Resource": [
273-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/start-next",
274-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*/update"
305+
"arn:aws:iot:<b>region</b>:<b>account</b>:client/<b>thingname</b>",
306+
"arn:aws:iot:<b>region</b>:<b>account</b>:client/test-*"
275307
]
276308
},
277309
{
278310
"Effect": "Allow",
279-
"Action": [
280-
"iot:Receive"
281-
],
311+
"Action": "iot:Publish",
282312
"Resource": [
283-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/notify-next",
284-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/start-next/accepted",
285-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/start-next/rejected",
286-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*/update/accepted",
287-
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*/update/rejected"
313+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/test/dc/pubtopic",
314+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/events/job/*",
315+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/events/jobExecution/*",
316+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*"
288317
]
289318
},
290319
{
291320
"Effect": "Allow",
292-
"Action": [
293-
"iot:Subscribe"
294-
],
321+
"Action": "iot:Subscribe",
295322
"Resource": [
296-
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/notify-next",
297-
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/start-next/accepted",
298-
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/start-next/rejected",
299-
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/*/update/accepted",
300-
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/*/update/rejected"
323+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/test/dc/subtopic",
324+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/events/jobExecution/*",
325+
"arn:aws:iot:<b>region</b>:<b>account</b>:topicfilter/$aws/things/<b>thingname</b>/jobs/*"
301326
]
302327
},
303328
{
304329
"Effect": "Allow",
305-
"Action": "iot:Connect",
306-
"Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:client/test-*"
330+
"Action": "iot:Receive",
331+
"Resource": [
332+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/test/dc/subtopic",
333+
"arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>/jobs/*"
334+
]
335+
},
336+
{
337+
"Effect": "Allow",
338+
"Action": [
339+
"iot:DescribeJobExecution",
340+
"iot:GetPendingJobExecutions",
341+
"iot:StartNextPendingJobExecution",
342+
"iot:UpdateJobExecution"
343+
],
344+
"Resource": "arn:aws:iot:<b>region</b>:<b>account</b>:topic/$aws/things/<b>thingname</b>"
307345
}
308-
309346
]
310347
}
311348
</pre>
349+
350+
See the [Basic job policy example](https://docs.aws.amazon.com/iot/latest/developerguide/basic-jobs-example.html) page for another policy example.
312351
</details>
313352

353+
To run the job sample use the following command:
354+
355+
``` sh
356+
./describe-job-execution --endpoint <endpoint> --ca_file <path to root CA>
357+
--cert <path to the certificate> --key <path to the private key>
358+
--thing_name <thing name> --job_id <the job id>
359+
```
360+
361+
Note that if you get a `Service Error 4 occurred` error, you may have incorrectly input the job id. The job id needs to exactly match the job id in the AWS console.
362+
314363
## Fleet provisioning
315364

316365
This sample uses the AWS IoT

0 commit comments

Comments
 (0)