1 How to build AWS IoT SDK for CPP {#aws}
3 @brief Tutorial to build the AWS IoT SDK for CPP.
5 # ioThinx-4530-aws-iot {#aws-iothinx-4530-aws-iot}
7 > **Table of Contents**
9 > [Cloud: Create device instance for connecting by SDK program](#aws-cloud-aws)
11 > [Host: Cross-compiling the SDK](#aws-host-x86_64-linux)
13 > [Target: Executing the SDK program](#aws-target-arm-linux)
15 ## Cloud (AWS) {#aws-cloud-aws}
17 > Create device instance for connecting by SDK program
19 ### Sign in to Cloud {#aws-sign-in-to-cloud}
21 * Sign in to [AWS IoT Cloud][cloud]. If you do not have an account, please register a new one.
23 ### Create Device {#aws-create-device}
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**.
27 ![create_device_01][create_device_01]
29 2. On the **Creating AWS IoT things** page, choose **Create a single thing**.
31 ![create_device_02][create_device_02]
33 3. On the **Add your device to the thing registry** page, fill in the necessary information then choose **Next**.
35 ![create_device_03][create_device_03]
36 ![create_device_04][create_device_04]
38 4. On the **Add a certificate for your thing** page, choose **Create thing without certificate**.
40 ![create_device_05][create_device_05]
42 5. Finish creating the device
44 ![create_device_06][create_device_06]
46 ### Create Policy {#aws-create-policy}
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**.
50 ![create_policy_01][create_policy_01]
52 2. On the **Create a policy** page, fill in the necessary information and select the **Allow** check box then choose **Create**.
54 ![create_policy_02][create_policy_02]
55 ![create_policy_03][create_policy_03]
57 4. Finish creating the policy
59 ![create_policy_04][create_policy_04]
61 ### Create Certificate {#aws-create-certificate}
63 > You will need this infomation in the section [Build the SDK](#aws-build-the-sdk)
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**.
67 ![create_certificate_01][create_certificate_01]
69 2. On the **Create a certificate** page, choose **Create certificate**.
71 ![create_certificate_02][create_certificate_02]
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**.
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**.
78 ![create_certificate_04][create_certificate_04]
80 4. Finish creating the certificate
82 ![create_certificate_05][create_certificate_05]
84 ### Active Certificate {#aws-active-certificate}
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**.
88 ![active_certificate_01][active_certificate_01]
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**.
92 ![active_certificate_02][active_certificate_02]
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**.
96 ![active_certificate_01][active_certificate_03]
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**.
100 ![active_certificate_02][active_certificate_04]
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**.
104 ![active_certificate_05][active_certificate_05]
106 6. Finish activating the certificate
108 ![active_certificate_06][active_certificate_06]
110 ### Copy Device Endpoint {#aws-copy-device-endpoint}
112 > **Device Endpoint** is the key to build connection between physical and virtual device on cloud
114 > You will need this infomation in the section [Build the SDK](#aws-build-the-sdk)
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.
118 ![copy_device_endpoint][copy_device_endpoint]
120 ### View Device Messages {#aws-view-device-messages}
122 > You can view the following device messages after section [Execute the SDK](#aws-execute-the-sdk)
124 1. In the left navigation pane, choose **Test**. On the **Subscribe** item, fill in the necessary information then choose **Subscribe to topic**.
126 ![view_device_messages_01][view_device_messages_01]
128 2. Device messages result
130 ![view_device_messages_02][view_device_messages_02]
131 ![view_device_messages_03][view_device_messages_03]
133 ## Host (x86_64-linux) {#aws-host-x86_64-linux}
135 > Cross-compiling the SDK
137 ### Setup the Environment {#aws-setup-the-environment}
139 1. Setup a network connection to allow host able to access the network.
141 2. Install GNU cross-toolchain provide by MOXA.
143 3. Install following package from package manager.
145 cmake git rsync tree vim
148 ### Build the SDK {#aws-build-the-sdk}
150 1. Clone repository of MOXA cloud connectivity tool from github.
152 user@Linux:~$ git clone https://github.com/MoxaCorp/ioThinx-4530-aws-iot.git
155 2. Setup dependencies and SDK to output directory.
157 user@Linux:~$ cd ioThinx-4530-aws-iot
160 user@Linux:~/ioThinx-4530-aws-iot$ ./setup.sh
162 * For more setup.sh options.
164 user@Linux:~/ioThinx-4530-aws-iot$ ./setup.sh --help
166 Usage: ./setup.sh [options]
169 -git Git repository of SDK.
170 Default: https://github.com/aws/aws-iot-device-sdk-cpp.git
175 --toolchain GNU cross-toolchain directory.
176 Default: /usr/local/arm-linux-gnueabihf
178 --help Display this help and exit.
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
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)]
188 user@Linux:~/ioThinx-4530-aws-iot$ tree output/sdk_aws/certs
190 ├── abd17825b2-certificate.pem.crt
191 ├── abd17825b2-private.pem.key
192 └── AmazonRootCA1.pem
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)]
197 user@Linux:~/ioThinx-4530-aws-iot$ vim output/sdk_aws/common/SampleConfig.json
201 "endpoint": "example.amazonaws.com",
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,
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
229 5. Build the whole SDK.
231 user@Linux:~/ioThinx-4530-aws-iot$ ./build.sh
233 * All compiled SDK program can be found in the following directory, including example **pub-sub-sample**.
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
240 │ ├── abd17825b2-certificate.pem.crt
241 │ ├── abd17825b2-private.pem.key
242 │ └── AmazonRootCA1.pem
244 │ ├── IntegrationTestConfig.json
245 │ └── SampleConfig.json
248 ├── shadow-delta-sample
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.
254 user@Linux:~/ioThinx-4530-aws-iot$ tree sample
258 │ │ ├── abd17825b2-certificate.pem.crt
259 │ │ ├── abd17825b2-private.pem.key
260 │ │ ├── AmazonRootCA1.pem
262 │ │ └── SampleConfig.json
263 │ └── moxa_sample_mqtt
265 ├── moxa_sample_mqtt.cpp
266 └── moxa_sample_mqtt.hpp
268 * The compiled MOXA program **moxa_sample_mqtt** will be generated after the whole SDK is built.
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.
276 ## Target (arm-linux) {#aws-target-arm-linux}
278 > Executing the SDK program
280 ### Setup the Environment {#aws-setup-the-environment-1}
282 1. Setup a network connection to allow target able to access the network.
284 2. Install following package from package manager.
289 3. Copy compiled SDK program from host to target.
294 │ ├── abd17825b2-certificate.pem.crt
295 │ ├── abd17825b2-private.pem.key
296 │ └── AmazonRootCA1.pem
298 │ └── SampleConfig.json
302 ### Execute the SDK {#aws-execute-the-sdk}
304 1. Execute SDK program that cross-compiled by host.
306 moxa@Moxa:~$ sudo ./pub-sub-sample
309 2. [View device messages on cloud](#aws-view-device-messages).
311 ## Reference {#aws-reference}
313 [1] [https://github.com/aws/aws-iot-device-sdk-cpp][Reference_01]
315 [2] [https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html][Reference_02]
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
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
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
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
343 [copy_device_endpoint]: readme/aws_copy_device_endpoint.png
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
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