aliyun-iot-sdk-c/README.md
Go to the documentation of this file.
1 How to build Aliyun IoT SDK for C {#aliyun}
2 ----
3 @brief Tutorial to build the Aliyun IoT SDK for C.
4 
5 # ALIYUN-IOT-SDK-C {#aliyun-aliyun-iot-sdk-c}
6 
7 > **Table of Contents**
8 >
9 > [Cloud: Create device instance for connecting by SDK program](#aliyun-cloud-aliyun)
10 >
11 > [Host: Cross-compiling the SDK](#aliyun-host-x86_64-linux)
12 >
13 > [Target: Executing the SDK program](#aliyun-target-arm-linux)
14 
15 ## Cloud (Aliyun) {#aliyun-cloud-aliyun}
16 
17 > Create device instance for connecting by SDK program
18 
19 ### Sign in to Cloud {#aliyun-sign-in-to-cloud}
20 
21 * Sign in to [Aliyun IoT Cloud][cloud]. If you do not have an account, please register a new one.
22 
23 ### Create Product {#aliyun-create-product}
24 
25 1. In the left navigation pane, expand **Devices** and then choose **Product**.
26 
27  ![create_product_01][create_product_01]
28 
29 2. On the **Products** page, choose **Create Product** and fill in the necessary information then choose **OK**.
30 
31  ![create_product_02][create_product_02]
32 
33 3. Finish creating the Product.
34 
35  ![create_product_03][create_product_03]
36 
37 ### Create Device {#aliyun-create-device}
38 
39 1. In the left navigation pane, expand **Devices** and then choose **Device**.
40 
41  ![create_device_01][create_device_01]
42 
43 2. On the **Devices** page, choose **Add Device** and fill in the necessary information then choose **OK**.
44 
45  ![create_device_02][create_device_02]
46 
47 3. Finish creating the Device.
48 
49  ![create_device_03][create_device_03]
50 
51 ### Create Topic {#aliyun-create-topic}
52 
53 1. In the left navigation pane, expand **Devices** and then choose **Product**. On the **Products** page, search for the **[Product you create before]** then choose **View**.
54 
55  ![create_topic_01][create_topic_01]
56 
57 2. On the **Product Details** page, choose **Notifications** > **Create Topic Category**.
58 
59  ![create_topic_02][create_topic_02]
60 
61 3. On the **Create Topic Category** page, fill in the necessary information then choose **OK**.
62 
63  ![create_topic_03][create_topic_03]
64 
65 4. Finish creating the Topic.
66 
67  ![create_topic_04][create_topic_04]
68 
69 ### Copy Device Identification {#aliyun-copy-device-identification}
70 
71 > **Device Identification** is the key to build connection between physical and virtual device on cloud
72 >
73 > You will need this infomation in the section [Build the SDK](#aliyun-build-the-sdk)
74 
75 1. In the left navigation pane, expand **Devices** and then choose **Device**. On the **Devices** page, search for the **[Device you create before]** then choose **View**.
76 
77  ![copy_device_identification_01][copy_device_identification_01]
78 
79 2. On the **Device Information** tab, you can find and copy the device identification **ProductKey**, **DeviceName** and **DeviceSecret**.
80 
81  ![copy_device_identification_02][copy_device_identification_02]
82 
83 ### View Device Log {#aliyun-view-device-log}
84 
85 > You can view the following device log after section [Execute the SDK](#aliyun-execute-the-sdk)
86 
87 1. In the left navigation pane, expand **Devices** and then choose **Product**. On the **Products** page, search for the **[Product you create before]** then choose **View**.
88 
89  ![view_device_log_01][view_device_log_01]
90 
91 2. On the **Device Log** tab, you can view all device log in subtabs of **Device Actitivity Analysis**, **Upstream Analysis** and **Downstream Analysis**.
92 
93  ![view_device_log_02][view_device_log_02]
94  ![view_device_log_03][view_device_log_03]
95  ![view_device_log_04][view_device_log_04]
96 
97 ## Host (x86_64-linux) {#aliyun-host-x86_64-linux}
98 
99 > Cross-compiling the SDK
100 
101 ### Setup the Environment {#aliyun-setup-the-environment}
102 
103 1. Setup a network connection to allow host able to access the network.
104 
105 2. Install GNU cross-toolchain provide by MOXA.
106 
107 3. Install following package from package manager.
108 ```
109  cmake git rsync tree vim
110 ```
111 
112 ### Build the SDK {#aliyun-build-the-sdk}
113 
114 1. Clone repository of MOXA cloud connectivity tool from github.
115 ```
116  user@Linux:~$ git clone https://github.com/MoxaCorp/ioThinx-4530-aliyun-iot.git
117 ```
118 
119 2. Setup dependencies and SDK to output directory.
120 ```
121  user@Linux:~$ cd aliyun
122 ```
123 ```
124  user@Linux:~/aliyun$ ./setup.sh
125 ```
126  * For more setup.sh options.
127 ```
128  user@Linux:~/aliyun$ ./setup.sh --help
129 
130  Usage: ./setup.sh [options]
131 
132  Options:
133  -git Git repository of SDK.
134  Default: https://github.com/aliyun/iotkit-embedded.git
135 
136  -ver Version of SDK.
137  Default: RELEASED_V2.03
138 
139  --toolchain GNU cross-toolchain directory.
140  Default: /usr/local/arm-linux-gnueabihf
141 
142  --help Display this help and exit.
143 
144  Examples:
145  Default ./setup.sh
146  Specify ./setup.sh -git https://github.com/aliyun/iotkit-embedded.git -ver RELEASED_V2.03
147  ./setup.sh --toolchain /usr/local/arm-linux-gnueabihf
148 ```
149 
150 3. Add the device identification **ProductKey**, **DeviceName** and **DeviceSecret** to SDK sample code such as example **mqtt-example.c**. [[Copy Device Identification](#aliyun-copy-device-identification)]
151 ```
152  user@Linux:~/aliyun$ vim output/sdk_aliyun/sample/mqtt/mqtt-example.c
153 ```
154 ```
155  #define PRODUCT_KEY "a14qsGgMTtk"
156  #define DEVICE_NAME "Example_Device"
157  #define DEVICE_SECRET "CTA83oLWKq2n0YgvveFZusvVqeA0EVTq"
158 ```
159 
160 4. Build the whole SDK.
161 ```
162  user@Linux:~/aliyun$ ./build.sh
163 ```
164  * All compiled SDK program can be found in the following directory, including example **mqtt-example**.
165 ```
166  user@Linux:~/aliyun$ tree output/sdk_aliyun/output/release/bin
167  output/sdk_aliyun/output/release/bin
168  ├── coap-example
169  ├── http-example
170  ├── mqtt-example
171  ├── mqtt_multi_thread-example
172  ├── mqtt_rrpc-example
173  ├── ota_mqtt-example
174  ├── sdk-testsuites
175  └── shadow-example
176 ```
177 
178 * You can also reference to the MOXA sample code with ioThinx I/O library **moxa_sample_mqtt.c** in the following directory.
179 ```
180  user@Linux:~/aliyun$ tree sample
181  sample
182  ├── binary
183  │   └── moxa_sample_mqtt
184  └── source
185  └── moxa_sample_mqtt.c
186 ```
187  * The compiled MOXA program **moxa_sample_mqtt** will be generated after the whole SDK is built.
188 
189 * Note
190 ```
191  In general, the setup.sh only needs to be executed once.
192  The build.sh needs to be executed after any code change of the SDK.
193 ```
194 
195 ## Target (arm-linux) {#aliyun-target-arm-linux}
196 
197 > Executing the SDK program
198 
199 ### Setup the Environment {#aliyun-setup-the-environment-1}
200 
201 1. Setup a network connection to allow target able to access the network.
202 
203 2. Install following package from package manager.
204 ```
205  tree
206 ```
207 
208 3. Copy compiled SDK program from host to target.
209 ```
210  moxa@Moxa:~$ tree
211  .
212  └── mqtt-example
213 ```
214 
215 ### Execute the SDK {#aliyun-execute-the-sdk}
216 
217 1. Execute SDK program that cross-compiled by host.
218 ```
219  moxa@Moxa:~$ sudo ./mqtt-example
220 ```
221 
222 2. [View device log on cloud](#aliyun-view-device-log).
223 
224 ## Reference {#aliyun-reference}
225 
226 [1] [https://github.com/aliyun/iotkit-embedded][Reference_01]
227 
228 [2] [https://www.alibabacloud.com/help/product/30520.htm][Reference_02]
229 
230 [comment]: # (Images)
231 [create_product_01]: readme/create_product_01.png
232 [create_product_02]: readme/create_product_02.png
233 [create_product_03]: readme/create_product_03.png
234 
235 [create_device_01]: readme/create_device_01.png
236 [create_device_02]: readme/create_device_02.png
237 [create_device_03]: readme/create_device_03.png
238 
239 [create_topic_01]: readme/create_topic_01.png
240 [create_topic_02]: readme/create_topic_02.png
241 [create_topic_03]: readme/create_topic_03.png
242 [create_topic_04]: readme/create_topic_04.png
243 
244 [copy_device_identification_01]: readme/copy_device_identification_01.png
245 [copy_device_identification_02]: readme/copy_device_identification_02.png
246 
247 [view_device_log_01]: readme/view_device_log_01.png
248 [view_device_log_02]: readme/view_device_log_02.png
249 [view_device_log_03]: readme/view_device_log_03.png
250 [view_device_log_04]: readme/view_device_log_04.png
251 
252 [comment]: # (Links)
253 [cloud]: https://iot.console.aliyun.com
254 [Reference_01]: https://github.com/aliyun/iotkit-embedded
255 [Reference_02]: https://www.alibabacloud.com/help/product/30520.htm