aws-iot-sdk-cpp/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 # AWS-IOT-SDK-CPP {#aws-aws-iot-sdk-cpp}
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 aws
158 ```
159 ```
160  user@Linux:~/aws$ ./setup.sh
161 ```
162  * For more setup.sh options.
163 ```
164  user@Linux:~/aws$ ./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:~/aws$ 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:~/aws$ 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:~/aws$ ./build.sh
232 ```
233  * All compiled SDK program can be found in the following directory, including example **pub-sub-sample**.
234 ```
235  user@Linux:~/aws$ 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.
253 ```
254  user@Linux:~/aws$ 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/create_device_01.png
319 [create_device_02]: readme/create_device_02.png
320 [create_device_03]: readme/create_device_03.png
321 [create_device_04]: readme/create_device_04.png
322 [create_device_05]: readme/create_device_05.png
323 [create_device_06]: readme/create_device_06.png
324 
325 [create_policy_01]: readme/create_policy_01.png
326 [create_policy_02]: readme/create_policy_02.png
327 [create_policy_03]: readme/create_policy_03.png
328 [create_policy_04]: readme/create_policy_04.png
329 
330 [create_certificate_01]: readme/create_certificate_01.png
331 [create_certificate_02]: readme/create_certificate_02.png
332 [create_certificate_03]: readme/create_certificate_03.png
333 [create_certificate_04]: readme/create_certificate_04.png
334 [create_certificate_05]: readme/create_certificate_05.png
335 
336 [active_certificate_01]: readme/active_certificate_01.png
337 [active_certificate_02]: readme/active_certificate_02.png
338 [active_certificate_03]: readme/active_certificate_03.png
339 [active_certificate_04]: readme/active_certificate_04.png
340 [active_certificate_05]: readme/active_certificate_05.png
341 [active_certificate_06]: readme/active_certificate_06.png
342 
343 [copy_device_endpoint]: readme/copy_device_endpoint.png
344 
345 [view_device_messages_01]: readme/view_device_messages_01.png
346 [view_device_messages_02]: readme/view_device_messages_02.png
347 [view_device_messages_03]: readme/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