azure-iot-sdk-c/README.md
Go to the documentation of this file.
1 How to build Azure IoT SDK for C {#azure}
2 ----
3 @brief Tutorial to build the Azure IoT SDK for C.
4 
5 # AZURE-IOT-SDK-C {#azure-azure-iot-sdk-c}
6 
7 > **Table of Contents**
8 >
9 > [Cloud: Create device instance for connecting by SDK program](#azure-cloud-azure)
10 >
11 > [Host: Cross-compiling the SDK](#azure-host-x86_64-linux)
12 >
13 > [Target: Executing the SDK program](#azure-target-arm-linux)
14 
15 ## Cloud (Azure) {#azure-cloud-azure}
16 
17 > Create device instance for connecting by SDK program
18 
19 ### Sign in to Cloud {#azure-sign-in-to-cloud}
20 
21 * Sign in to [Azure IoT Cloud][cloud]. If you do not have an account, please register a new one.
22 
23 ### Create IoT Hub {#azure-create-iot-hub}
24 
25 1. In the left navigation pane, choose **Create a resource** > **Internet of Things** > **IoT Hub**.
26 
27  ![create_iot_hub_01][create_iot_hub_01]
28 
29 2. On the **Basics** tab, fill in the necessary information then choose **Next: Size and scale »**.
30 
31  ![create_iot_hub_02][create_iot_hub_02]
32 
33 3. On the **Size and scale** tab, fill in the necessary information then choose **Review + create**.
34 
35  ![create_iot_hub_03][create_iot_hub_03]
36 
37 4. On the **Review + create** tab, review the information you fill before then choose **Create**.
38 
39  ![create_iot_hub_04][create_iot_hub_04]
40 
41 5. Creating the IoT Hub will takes a few minutes.
42 
43  ![create_iot_hub_05][create_iot_hub_05]
44 
45 6. Finish creating the IoT Hub.
46 
47  ![create_iot_hub_06][create_iot_hub_06]
48 
49 ### Create Device {#azure-create-device}
50 
51 1. In the left navigation pane, choose **All resources**, then search and choose the **[IoT Hub you create before]**.
52 
53  ![create_device_01][create_device_01]
54 
55 2. On the **Explorers** item, choose **IoT devices** > **Add**.
56 
57  ![create_device_02][create_device_02]
58 
59 3. On the **Create a device** page, fill in the necessary information then choose **Save**.
60 
61  ![create_device_03][create_device_03]
62 
63 4. Finish creating the Device.
64 
65  ![create_device_04][create_device_04]
66 
67 ### Copy Device Connection String {#azure-copy-device-connection-string}
68 
69 > **Device Connection String** is the key to build connection between physical and virtual device on cloud
70 >
71 > You will need this infomation in the section [Build the SDK](#azure-build-the-sdk)
72 
73 1. In the left navigation pane, choose **All resources**, then search and choose the **[IoT Hub you create before]**.
74 
75  ![copy_device_connection_string_01][copy_device_connection_string_01]
76 
77 2. On the **Explorers** item, choose **IoT devices** > **[Device you create before]**.
78 
79  ![copy_device_connection_string_02][copy_device_connection_string_02]
80 
81 3. Finish copying the **Connection String (primary key)** of Device.
82 
83  ![copy_device_connection_string_03][copy_device_connection_string_03]
84 
85 ### View Device Messages {#azure-view-device-messages}
86 
87 > You can view the following device messages after section [Execute the SDK](#azure-execute-the-sdk)
88 
89 1. On the right side of the search bar above, choose >_ to open **Cloud Shell**.
90 
91  ![view_device_messages_01][view_device_messages_01]
92 
93 2. Add extension **azure-cli-iot-ext** to Azure CLI.
94 ```
95  user@Azure:~$ az extension add --name azure-cli-iot-ext
96 ```
97 
98 2. Monitor device telemetry and messages that sent to IoT Hub.
99 ```
100  user@Azure:~$ az iot hub monitor-events -n Example-IoT-Hub
101 ```
102  ![view_device_messages_02][view_device_messages_02]
103 
104 ## Host (x86_64-linux) {#azure-host-x86_64-linux}
105 
106 > Cross-compiling the SDK
107 
108 ### Setup the Environment {#azure-setup-the-environment}
109 
110 1. Setup a network connection to allow host able to access the network.
111 
112 2. Install GNU cross-toolchain provide by MOXA.
113 
114 3. Install following package from package manager.
115 ```
116  cmake git rsync tree vim
117 ```
118 
119 ### Build the SDK {#azure-build-the-sdk}
120 
121 1. Clone repository of MOXA cloud connectivity tool from github.
122 ```
123  user@Linux:~$ git clone https://github.com/MoxaCorp/ioThinx-4530-azure-iot.git
124 ```
125 
126 2. Setup dependencies and SDK to output directory.
127 ```
128  user@Linux:~$ cd azure
129 ```
130 ```
131  user@Linux:~/azure$ ./setup.sh
132 ```
133  * For more setup.sh options.
134 ```
135  user@Linux:~/azure$ ./setup.sh --help
136 
137  Usage: ./setup.sh [options]
138 
139  Options:
140  -git Git repository of SDK.
141  Default: https://github.com/Azure/azure-iot-sdk-c.git
142 
143  -ver Version of SDK.
144  Default: 2018-10-03
145 
146  --toolchain GNU cross-toolchain directory.
147  Default: /usr/local/arm-linux-gnueabihf
148 
149  --help Display this help and exit.
150 
151  Examples:
152  Default ./setup.sh
153  Specify ./setup.sh -git https://github.com/Azure/azure-iot-sdk-c.git -ver 2018-10-03
154  ./setup.sh --toolchain /usr/local/arm-linux-gnueabihf
155 ```
156 
157 3. Add the **Connection String (primary key)** of Device to SDK sample code such as example **simplesample_amqp.c**. [[Copy Connection String](#azure-copy-device-connection-string)]
158 ```
159  user@Linux:~/azure$ vim output/sdk_azure/serializer/samples/simplesample_amqp/simplesample_amqp.c
160 ```
161 ```
162  /*String containing Hostname, Device Id & Device Key in the format: */
163  /* "HostName=<host_name>;DeviceId=<device_id>;SharedAccessKey=<device_key>" */
164  static const char* connectionString = "HostName=Example-IoT-Hub.azure-devices.net;DeviceId=Example-Device;SharedAccessKey=hQUkHWv6Gq+1r2yQU5vLzQ86KUjyIquow+XuuDG1DqM=";
165 ```
166 
167 4. Build the whole SDK.
168 ```
169  user@Linux:~/azure$ ./build.sh
170 ```
171  * All compiled SDK program can be found in the following directory, including example **simplesample_amqp**.
172 ```
173  user@Linux:~/azure$ tree output/sdk_azure/cmake/iotsdk_linux/serializer/samples
174  output/sdk_azure/cmake/iotsdk_linux/serializer/samples
175  ├── devicemethod_simplesample
176  │   └── devicemethod_simplesample
177  ├── devicetwin_simplesample
178  │   └── devicetwin_simplesample
179  ├── remote_monitoring
180  │   └── remote_monitoring
181  ├── simplesample_amqp
182  │   └── simplesample_amqp
183  ├── simplesample_http
184  │   └── simplesample_http
185  ├── simplesample_mqtt
186  │   └── simplesample_mqtt
187  └── temp_sensor_anomaly
188  └── temp_sensor_anomaly
189 ```
190 
191 * You can also reference to the MOXA sample code with ioThinx I/O library **moxa_sample_mqtt.c** in the following directory.
192 ```
193  user@Linux:~/azure$ tree sample
194  sample
195  ├── binary
196  │   └── moxa_sample_mqtt
197  └── source
198  └── moxa_sample_mqtt.c
199 ```
200  * The compiled MOXA program **moxa_sample_mqtt** will be generated after the whole SDK is built.
201 
202 * Note
203 ```
204  In general, the setup.sh only needs to be executed once.
205  The build.sh needs to be executed after any code change of the SDK.
206 ```
207 
208 ## Target (arm-linux) {#azure-target-arm-linux}
209 
210 > Executing the SDK program
211 
212 ### Setup the Environment {#azure-setup-the-environment-1}
213 
214 1. Setup a network connection to allow target able to access the network.
215 
216 2. Install following package from package manager.
217 ```
218  tree
219 ```
220 
221 3. Copy compiled SDK program from host to target.
222 ```
223  moxa@Moxa:~$ tree
224  .
225  └── simplesample_amqp
226 ```
227 
228 ### Execute the SDK {#azure-execute-the-sdk}
229 
230 1. Execute SDK program that cross-compiled by host.
231 ```
232  moxa@Moxa:~$ sudo ./simplesample_amqp
233 ```
234 
235 2. [View device messages on cloud](#azure-view-device-messages).
236 
237 ## Reference {#azure-reference}
238 
239 [1] [https://github.com/Azure/azure-iot-sdk-c][Reference_01]
240 
241 [2] [https://docs.microsoft.com/en-us/azure/iot-hub][Reference_02]
242 
243 [comment]: # (Images)
244 [create_iot_hub_01]: readme/create_iot_hub_01.png
245 [create_iot_hub_02]: readme/create_iot_hub_02.png
246 [create_iot_hub_03]: readme/create_iot_hub_03.png
247 [create_iot_hub_04]: readme/create_iot_hub_04.png
248 [create_iot_hub_05]: readme/create_iot_hub_05.png
249 [create_iot_hub_06]: readme/create_iot_hub_06.png
250 
251 [create_device_01]: readme/create_device_01.png
252 [create_device_02]: readme/create_device_02.png
253 [create_device_03]: readme/create_device_03.png
254 [create_device_04]: readme/create_device_04.png
255 
256 [copy_device_connection_string_01]: readme/copy_device_connection_string_01.png
257 [copy_device_connection_string_02]: readme/copy_device_connection_string_02.png
258 [copy_device_connection_string_03]: readme/copy_device_connection_string_03.png
259 
260 [view_device_messages_01]: readme/view_device_messages_01.png
261 [view_device_messages_02]: readme/view_device_messages_02.png
262 
263 [comment]: # (Links)
264 [cloud]: https://portal.azure.com
265 [Reference_01]: https://github.com/Azure/azure-iot-sdk-c
266 [Reference_02]: https://docs.microsoft.com/en-us/azure/iot-hub