- Main
- Tutorials
- Library
- Samples

- File List
- Globals

tutorial/cloud/aws/README.md
Go to the documentation of this file.
1 How to build AWS IoT SDK for CPP {#aws}
2 ----
3 @brief Tutorial to build the AWS IoT SDK for CPP.
4
5 # ioThinx-4530-aws-iot {#aws-iothinx-4530-aws-iot}
6
7 > **Table of Contents**
8 >
9 > [Cloud: Create device instance for connecting by SDK program](#aws-cloud-aws)
10 >
11 > [Host: Cross-compiling the SDK](#aws-host-x86_64-linux)
12 >
13 > [Target: Executing the SDK program](#aws-target-arm-linux)
14
15 ## Cloud (AWS) {#aws-cloud-aws}
16
17 > Create device instance for connecting by SDK program
18
19 ### Sign in to Cloud {#aws-sign-in-to-cloud}
20
21 * Sign in to [AWS IoT Cloud][cloud]. If you do not have an account, please register a new one.
22
23 ### Create Device {#aws-create-device}
24
25 1. In the left navigation pane, expand **Manage** and then choose **Things**. On the page that says **You don't have any things yet**, choose **Register a thing**.
26
27 ![create_device_01][create_device_01]
28
29 2. On the **Creating AWS IoT things** page, choose **Create a single thing**.
30
31 ![create_device_02][create_device_02]
32
33 3. On the **Add your device to the thing registry** page, fill in the necessary information then choose **Next**.
34
35 ![create_device_03][create_device_03]
36 ![create_device_04][create_device_04]
37
38 4. On the **Add a certificate for your thing** page, choose **Create thing without certificate**.
39
40 ![create_device_05][create_device_05]
41
42 5. Finish creating the device
43
44 ![create_device_06][create_device_06]
45
46 ### Create Policy {#aws-create-policy}
47
48 1. In the left navigation pane, expand **Secure** and then choose **Policies**. On the page that says **You don't have any policies yet**, choose **Create a policy**.
49
50 ![create_policy_01][create_policy_01]
51
52 2. On the **Create a policy** page, fill in the necessary information and select the **Allow** check box then choose **Create**.
53
54 ![create_policy_02][create_policy_02]
55 ![create_policy_03][create_policy_03]
56
57 4. Finish creating the policy
58
59 ![create_policy_04][create_policy_04]
60
61 ### Create Certificate {#aws-create-certificate}
62
63 > You will need this infomation in the section [Build the SDK](#aws-build-the-sdk)
64
65 1. In the left navigation pane, expand **Secure** and then choose **Certificates**. On the page that says **You don't have any certificates yet**, choose **Create a certificate**.
66
67 ![create_certificate_01][create_certificate_01]
68
69 2. On the **Create a certificate** page, choose **Create certificate**.
70
71 ![create_certificate_02][create_certificate_02]
72
73 3. On the **Certificate created!** page, choose **Download** for the **certificate**, **private key**, and the **root CA** (the public key need not be downloaded). Save each of them to your computer, and then choose **Done**.
74
75 ![create_certificate_03][create_certificate_03]
76 * For downloading the **root CA** for AWS IoT, on the **Server Authentication** page, choose **Amazon Root CA 1**.
77
78 ![create_certificate_04][create_certificate_04]
79
80 4. Finish creating the certificate
81
82 ![create_certificate_05][create_certificate_05]
83
84 ### Active Certificate {#aws-active-certificate}
85
86 1. In the left navigation pane, expand **Secure** and then choose **Certificates**. In the box for the certificate you created before, choose **...** to open a drop-down menu, and then choose **Attach thing**.
87
88 ![active_certificate_01][active_certificate_01]
89
90 2. In the **Attach things to certificate(s)** dialog box, select the check box next to the device you created before, and then choose **Attach**.
91
92 ![active_certificate_02][active_certificate_02]
93
94 3. In the left navigation pane, expand **Secure** and then choose **Certificates**. In the box for the certificate you created before, choose **...** to open a drop-down menu, and then choose **Attach policy**.
95
96 ![active_certificate_01][active_certificate_03]
97
98 4. In the **Attach policies to certificate(s)** dialog box, select the check box next to the policy you created before, and then choose **Attach**.
99
100 ![active_certificate_02][active_certificate_04]
101
102 5. In the left navigation pane, expand **Secure** and then choose **Certificates**. In the box for the certificate you created before, choose **...** to open a drop-down menu, and then choose **Activate**.
103
104 ![active_certificate_05][active_certificate_05]
105
106 6. Finish activating the certificate
107
108 ![active_certificate_06][active_certificate_06]
109
110 ### Copy Device Endpoint {#aws-copy-device-endpoint}
111
112 > **Device Endpoint** is the key to build connection between physical and virtual device on cloud
113 >
114 > You will need this infomation in the section [Build the SDK](#aws-build-the-sdk)
115
116 * In the left navigation pane, choose **Settings**. On the **Custom endpoint** item, you can found the **Endpoint** that allows you to connect to AWS IoT.
117
118 ![copy_device_endpoint][copy_device_endpoint]
119
120 ### View Device Messages {#aws-view-device-messages}
121
122 > You can view the following device messages after section [Execute the SDK](#aws-execute-the-sdk)
123
124 1. In the left navigation pane, choose **Test**. On the **Subscribe** item, fill in the necessary information then choose **Subscribe to topic**.
125
126 ![view_device_messages_01][view_device_messages_01]
127
128 2. Device messages result
129
130 ![view_device_messages_02][view_device_messages_02]
131 ![view_device_messages_03][view_device_messages_03]
132
133 ## Host (x86_64-linux) {#aws-host-x86_64-linux}
134
135 > Cross-compiling the SDK
136
137 ### Setup the Environment {#aws-setup-the-environment}
138
139 1. Setup a network connection to allow host able to access the network.
140
141 2. Install GNU cross-toolchain provide by MOXA.
142
143 3. Install following package from package manager.
144 ```
145 cmake git rsync tree vim
146 ```
147
148 ### Build the SDK {#aws-build-the-sdk}
149
150 1. Clone repository of MOXA cloud connectivity tool from github.
151 ```
152 user@Linux:~$ git clone https://github.com/MoxaCorp/ioThinx-4530-aws-iot.git
153 ```
154
155 2. Setup dependencies and SDK to output directory.
156 ```
157 user@Linux:~$ cd ioThinx-4530-aws-iot
158 ```
159 ```
160 user@Linux:~/ioThinx-4530-aws-iot$ ./setup.sh
161 ```
162 * For more setup.sh options.
163 ```
164 user@Linux:~/ioThinx-4530-aws-iot$ ./setup.sh --help
165
166 Usage: ./setup.sh [options]
167
168 Options:
169 -git Git repository of SDK.
170 Default: https://github.com/aws/aws-iot-device-sdk-cpp.git
171
172 -ver Version of SDK.
173 Default: v1.4.0
174
175 --toolchain GNU cross-toolchain directory.
176 Default: /usr/local/arm-linux-gnueabihf
177
178 --help Display this help and exit.
179
180 Examples:
181 Default ./setup.sh
182 Specify ./setup.sh -git https://github.com/aws/aws-iot-device-sdk-cpp.git -ver v1.4.0
183 ./setup.sh --toolchain /usr/local/arm-linux-gnueabihf
184 ```
185
186 3. Copy the **certificate**, **private key**, and the **root CA** that downloaded from the cloud to the following directory. [[Download Certificate](#aws-create-certificate)]
187 ```
188 user@Linux:~/ioThinx-4530-aws-iot$ tree output/sdk_aws/certs
189 output/sdk_aws/certs
190 ├── abd17825b2-certificate.pem.crt
191 ├── abd17825b2-private.pem.key
192 └── AmazonRootCA1.pem
193 ```
194
195 4. Add the **endpoint** and the path of **certificate**, **private key**, and the **root CA** to **SampleConfig.json** file. [[Copy Device Endpoint](#aws-copy-device-endpoint)]
196 ```
197 user@Linux:~/ioThinx-4530-aws-iot$ vim output/sdk_aws/common/SampleConfig.json
198 ```
199 ```
200 {
201 "endpoint": "example.amazonaws.com",
202 "mqtt_port": 8883,
203 "https_port": 443,
204 "greengrass_discovery_port": 8443,
205 "root_ca_relative_path": "certs/AmazonRootCA1.pem",
206 "device_certificate_relative_path": "certs/abd17825b2-certificate.pem.crt",
207 "device_private_key_relative_path": "certs/abd17825b2-private.pem.key",
208 "tls_handshake_timeout_msecs": 60000,
209 "tls_read_timeout_msecs": 2000,
210 "tls_write_timeout_msecs": 2000,
211 "aws_region": "",
212 "aws_access_key_id": "",
213 "aws_secret_access_key": "",
214 "aws_session_token": "",
215 "client_id": "CppSDKTesting",
216 "thing_name": "CppSDKTesting",
217 "is_clean_session": true,
218 "mqtt_command_timeout_msecs": 20000,
219 "keepalive_interval_secs": 600,
220 "minimum_reconnect_interval_secs": 1,
221 "maximum_reconnect_interval_secs": 128,
222 "maximum_acks_to_wait_for": 32,
223 "action_processing_rate_hz": 5,
224 "maximum_outgoing_action_queue_length": 32,
225 "discover_action_timeout_msecs": 300000
226 }
227 ```
228
229 5. Build the whole SDK.
230 ```
231 user@Linux:~/ioThinx-4530-aws-iot$ ./build.sh
232 ```
233 * All compiled SDK program can be found in the following directory, including example **pub-sub-sample**.
234 ```
235 user@Linux:~/ioThinx-4530-aws-iot$ tree output/sdk_aws/build_cmake/bin
236 output/sdk_aws/build_cmake/bin
237 ├── aws-iot-integration-tests
238 ├── aws-iot-unit-tests
239 ├── certs
240 │ ├── abd17825b2-certificate.pem.crt
241 │ ├── abd17825b2-private.pem.key
242 │ └── AmazonRootCA1.pem
243 ├── config
244 │ ├── IntegrationTestConfig.json
245 │ └── SampleConfig.json
246 ├── jobs-sample
247 ├── pub-sub-sample
248 ├── shadow-delta-sample
249 └── TestParser.json
250 ```
251
252 * You can also reference to the MOXA sample code with ioThinx I/O library **moxa_sample_mqtt.cpp** in the following directory. This sample code can be executed directly on the target device with module 45MR-2606 located in slot 1.
253 ```
254 user@Linux:~/ioThinx-4530-aws-iot$ tree sample
255 sample
256 ├── binary
257 │ ├── certs
258 │ │ ├── abd17825b2-certificate.pem.crt
259 │ │ ├── abd17825b2-private.pem.key
260 │ │ ├── AmazonRootCA1.pem
261 │ ├── config
262 │ │ └── SampleConfig.json
263 │ └── moxa_sample_mqtt
264 └── source
265 ├── moxa_sample_mqtt.cpp
266 └── moxa_sample_mqtt.hpp
267 ```
268 * The compiled MOXA program **moxa_sample_mqtt** will be generated after the whole SDK is built.
269
270 * Note
271 ```
272 In general, the setup.sh only needs to be executed once.
273 The build.sh needs to be executed after any code change of the SDK.
274 ```
275
276 ## Target (arm-linux) {#aws-target-arm-linux}
277
278 > Executing the SDK program
279
280 ### Setup the Environment {#aws-setup-the-environment-1}
281
282 1. Setup a network connection to allow target able to access the network.
283
284 2. Install following package from package manager.
285 ```
286 tree
287 ```
288
289 3. Copy compiled SDK program from host to target.
290 ```
291 moxa@Moxa:~$ tree
292 .
293 ├── certs
294 │ ├── abd17825b2-certificate.pem.crt
295 │ ├── abd17825b2-private.pem.key
296 │ └── AmazonRootCA1.pem
297 ├── config
298 │ └── SampleConfig.json
299 └── pub-sub-sample
300 ```
301
302 ### Execute the SDK {#aws-execute-the-sdk}
303
304 1. Execute SDK program that cross-compiled by host.
305 ```
306 moxa@Moxa:~$ sudo ./pub-sub-sample
307 ```
308
309 2. [View device messages on cloud](#aws-view-device-messages).
310
311 ## Reference {#aws-reference}
312
313 [1] [https://github.com/aws/aws-iot-device-sdk-cpp][Reference_01]
314
315 [2] [https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html][Reference_02]
316
317 [comment]: # (Images)
318 [create_device_01]: readme/aws_create_device_01.png
319 [create_device_02]: readme/aws_create_device_02.png
320 [create_device_03]: readme/aws_create_device_03.png
321 [create_device_04]: readme/aws_create_device_04.png
322 [create_device_05]: readme/aws_create_device_05.png
323 [create_device_06]: readme/aws_create_device_06.png
324
325 [create_policy_01]: readme/aws_create_policy_01.png
326 [create_policy_02]: readme/aws_create_policy_02.png
327 [create_policy_03]: readme/aws_create_policy_03.png
328 [create_policy_04]: readme/aws_create_policy_04.png
329
330 [create_certificate_01]: readme/aws_create_certificate_01.png
331 [create_certificate_02]: readme/aws_create_certificate_02.png
332 [create_certificate_03]: readme/aws_create_certificate_03.png
333 [create_certificate_04]: readme/aws_create_certificate_04.png
334 [create_certificate_05]: readme/aws_create_certificate_05.png
335
336 [active_certificate_01]: readme/aws_active_certificate_01.png
337 [active_certificate_02]: readme/aws_active_certificate_02.png
338 [active_certificate_03]: readme/aws_active_certificate_03.png
339 [active_certificate_04]: readme/aws_active_certificate_04.png
340 [active_certificate_05]: readme/aws_active_certificate_05.png
341 [active_certificate_06]: readme/aws_active_certificate_06.png
342
343 [copy_device_endpoint]: readme/aws_copy_device_endpoint.png
344
345 [view_device_messages_01]: readme/aws_view_device_messages_01.png
346 [view_device_messages_02]: readme/aws_view_device_messages_02.png
347 [view_device_messages_03]: readme/aws_view_device_messages_03.png
348
349 [comment]: # (Links)
350 [cloud]: https://console.aws.amazon.com/iot/home
351 [Reference_01]: https://github.com/aws/aws-iot-device-sdk-cpp
352 [Reference_02]: https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html