1# Third-Party SDK Integration<a name="EN-US_TOPIC_0000001051612018"></a> 2 3- [Planning a Directory Structure](#section1736472718351) 4- [Building the Service libs](#section442815485351) 5- [Compiling Adaptation Code](#section3984721113613) 6- [Compiling Code](#section830417531286) 7- [Compiling a Script](#section13500201173710) 8- [Compiling Service Code](#section8754114803918) 9- [Runtime](#section7737749184012) 10- [End](#section153301392411) 11 12To build a more open and complete Internet of Things \(IoT\) ecosystem, OpenHarmony has opened up a group of directories to integrate SDKs provided by different vendors. This guide describes how to integrate SDKs into OpenHarmony based on the Hi3861 board. 13 14## Planning a Directory Structure<a name="section1736472718351"></a> 15 16A third-party SDK consists of a static library and the adaption code. The SDK service logic is compiled to obtain the static library **libs** through the hardware module tool chain. Each module has its corresponding **libs**. The southbound APIs of the SDK are different from the APIs of OpenHarmony. The difference can be shielded by using the adaptation code **adapter**. Different modules can share the same **adapter**. 17 18Based on the preceding features, third-party SDK directories can be divided as follows in the OpenHarmony directory structure: 19 20- domains/iot/link/: The **adapter** is stored in this directory and is decoupled from the module. 21- device/hisilicon/hispark\_pegasus/sdk\_liteos/3rd\_sdk/: The service library **libs** is stored in this directory and is bound to the module. 22 23You must perform the following steps before adaptation. The following uses the demolink SDK as an example. 24 251. Create vendor directories, **domains/iot/link/demolink/** and **device/hisilicon/hispark\_pegasus/sdk\_liteos/3rd\_sdk/demolink/**, to isolate different vendors. 262. Create the **domains/iot/link/demolink/BUILD.gn** file to build the adaptation code. 273. Create the **device/hisilicon/hispark\_pegasus/sdk\_liteos/3rd\_sdk/demolink/libs/** directory to store the service library **libs**. 28 29``` 30. 31├── domains 32│ └── iot 33│ └── link 34│ ├── demolink 35│ │ └── BUILD.gn 36│ ├── libbuild 37│ │ └── BUILD.gn 38│ └── BUILD.gn 39└── device 40 └── hisilicon 41 └── hispark_pegasus 42 └── sdk_liteos 43 └── 3rd_sdk 44 └── demolink 45 └── libs 46``` 47 48## Building the Service **libs**<a name="section442815485351"></a> 49 50Generally, the platform SDK service is provided as a static library. After obtaining the OpenHarmony code, the platform vendor needs to compile the service library **libs** based on the corresponding hardware module vendor and save the compilation result to the **device/hisilicon/hispark\_pegasus/sdk\_liteos/3rd\_sdk/demolink/libs/** directory. The following describes how to build the service library **libs**. 51 52OpenHarmony has planned the **domains/iot/link/libbuild/** directory for compiling the service library **libs**. This directory contains the **domains/iot/link/libbuild/BUILD.gn** and **domains/iot/link/BUILD.gn** files. The directory structure is as follows: 53 54``` 55. 56└── domains 57 └── iot 58 └── link 59 ├── demolink 60 │ └── BUILD.gn 61 ├── libbuild 62 │ └── BUILD.gn 63 └── BUILD.gn 64``` 65 66Before building **libs**, you must perform the following steps: 67 681. Place the service source code files \(including **.c** and **.h** files\) in the **domains/iot/link/libbuild/** directory. 69 70 ``` 71 . 72 └── domains 73 └── iot 74 └── link 75 ├── demolink 76 │ ├── demosdk_adapter.c 77 │ ├── demosdk_adapter.h 78 │ └── BUILD.gn 79 ├── libbuild 80 │ ├── demosdk.c 81 │ ├── demosdk.h 82 │ └── BUILD.gn 83 └── BUILD.gn 84 ``` 85 862. Adapt to the **domains/iot/link/libbuild/BUILD.gn** file and restore the file after the compilation is complete. 87 88 In the **BUILD.gn** file, **sources** specifies the source file to build and **include\_dirs** specifies the path of the dependent header file so that the target build result is the static library **libdemosdk.a**. 89 90 ``` 91 static_library("demosdk") { 92 sources = [ 93 "demosdk.c" 94 ] 95 include_dirs = [ 96 "//domains/iot/link/libbuild", 97 "//domains/iot/link/demolink" 98 ] 99 } 100 ``` 101 1023. Adapt to the **domains/iot/link/BUILD.gn** file and restore the file after the compilation is complete. 103 104 The **BUILD.gn** file is used to specify build entries. You need to enter all static library entries to be compiled in **features** so that the **domains/iot/link/libbuild/BUILD.gn** file is used in the build. 105 106 ``` 107 import("//build/lite/config/subsystem/lite_subsystem.gni") 108 import("//build/lite/config/component/lite_component.gni") 109 lite_subsystem("iot") { 110 subsystem_components = [ 111 ":link" 112 ] 113 } 114 lite_component("link") { 115 features = [ 116 "libbuild:demosdk" 117 ] 118 } 119 ``` 120 121 122After the preceding operations are complete, run the **hb build -T //domains/iot/link:iot** command in the root directory of the code and then check whether the target library file is generated in the **out/hispark\_pegasus/wifiiot\_hispark\_pegasus/libs/** directory. 123 124 125 126Copy the library file to the **device/hisilicon/hispark\_pegasus/sdk\_liteos/3rd\_sdk/demolink/libs/** directory and delete the **.c** and **.h** files from the **domains/iot/link/libbuild/** directory. 127 128## Compiling Adaptation Code<a name="section3984721113613"></a> 129 130## Compiling Code<a name="section830417531286"></a> 131 132The APIs used in the platform SDK are different from the OpenHarmony APIs and cannot be directly used. Therefore, the adaptation code **adapter** is required for intermediate conversion. This section uses **DemoSdkCreateTask** in **domains/iot/link/demolink/demosdk\_adapter.c** as an example to describe how to compile adaptation code on OpenHarmony. 133 1341. Check the description, parameters, and return values of the **DemoSdkCreateTask** API to adapt. 135 136 ``` 137 struct TaskPara { 138 char *name; 139 void *(*func)(char* arg); 140 void *arg; 141 unsigned char prio; 142 unsigned int size; 143 }; 144 145 /* 146 * Create a thread for the IoT OS. 147 * Returns 0 if the operation is successful; returns a non-zero value otherwise. 148 */ 149 int DemoSdkCreateTask(unsigned int *handle, const struct TaskPara *para); 150 ``` 151 1522. Check the OpenHarmony API document, select an API with similar features, and compare the parameters and usage. This guide uses **osThreadNew** as an example. By comparing this API with **DemoSdkCreateTask**, you can find that the parameters on which the two APIs depend are basically the same, but the structures to which the parameters belong are different. 153 154 ``` 155 typedef struct { 156 const char *name; ///< name of the thread 157 uint32_t attr_bits; ///< attribute bits 158 void *cb_mem; ///< memory for control block 159 uint32_t cb_size; ///< size of provided memory for control block 160 void *stack_mem; ///< memory for stack 161 uint32_t stack_size; ///< size of stack 162 osPriority_t priority; ///< initial thread priority (default: osPriorityNormal) 163 TZ_ModuleId_t tz_module; ///< TrustZone module identifier 164 uint32_t reserved; ///< reserved (must be 0) 165 } osThreadAttr_t; 166 167 /// Create a thread and add it to Active Threads. 168 /// \param[in] func thread function. 169 /// \param[in] argument pointer that is passed to the thread function as start argument. 170 /// \param[in] attr thread attributes; NULL: default values. 171 /// \return thread ID for reference by other functions or NULL in case of error. 172 osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr); 173 ``` 174 1753. Perform code adaptation to shield the difference. 176 177 ``` 178 int DemoSdkCreateTask(unsigned int *handle, const struct TaskPara *para) 179 { 180 osThreadAttr_t attr = {0}; 181 osThreadId_t threadId; 182 if (handle == 0 || para == 0) { 183 return DEMOSDK_ERR; 184 } 185 if (para->func == 0) { 186 return DEMOSDK_ERR; 187 } 188 if (para->name == 0) { 189 return DEMOSDK_ERR; 190 } 191 attr.name = para->name; 192 attr.priority = para->prio; 193 attr.stack_size = para->size; 194 threadId = osThreadNew((osThreadFunc_t)para->func, para->arg, &attr); 195 if (threadId == 0) { 196 printf("osThreadNew fail\n"); 197 return DEMOSDK_ERR; 198 } 199 *(unsigned int *)handle = (unsigned int)threadId; 200 return DEMOSDK_OK; 201 } 202 ``` 203 204 205## Compiling a Script<a name="section13500201173710"></a> 206 207After completing code adaptation, create the **BUILD.gn** file in the directory where the **adapter** is located. This file can be used to compile the adaptation code into a static library and link the static library to the **bin** package during the entire package build. In the **domains/iot/link/demolink/BUILD.gn** file, **sources** specifies the source files to be used in the build and **include\_dirs** specifies the path of the dependent header file so that the target build result is the static library **libdemolinkadapter.a**. 208 209``` 210import("//build/lite/config/component/lite_component.gni") 211static_library("demolinkadapter") { 212 sources = [ 213 "demosdk_adapter.c" 214 ] 215 include_dirs = [ 216 "//kernel/liteos-m/kal/cmsis", 217 "//domains/iot/link/demolink" 218 ] 219} 220``` 221 222Modify the **domains/iot/link/BUILD.gn** file so that the **domain/iot/hilink/BUILD.gn** file is used in the build. 223 224``` 225import("//build/lite/config/subsystem/lite_subsystem.gni") 226import("//build/lite/config/component/lite_component.gni") 227lite_subsystem("iot") { 228 subsystem_components = [ 229 ":link" 230 ] 231} 232lite_component("link") { 233 features = [ 234 "demolink:demolinkadapter" 235 ] 236} 237``` 238 239## Compiling Service Code<a name="section8754114803918"></a> 240 241After the service library **libs** and adaptation code are ready, compile the service entry function to call the service entry of the third-party SDK. 242 243The following uses **demolink** as an example to describe how to compile code in **applications/sample/wifi-iot/app/** to call the **demosdk** entry function. 244 2451. Create a directory. 246 247 Before compiling a service, you must create a directory \(or a directory structure\) in **applications/sample/wifi-iot/app/** to store service source code files. 248 249 For example, add the service directory **demolink** to the app, and create the service entry code **helloworld.c** and compile the **BUILD.gn** file. 250 251 ``` 252 . 253 └── applications 254 └── sample 255 └── wifi-iot 256 └── app 257 │── demolink 258 │ │── helloworld.c 259 │ └── BUILD.gn 260 └── BUILD.gn 261 ``` 262 2632. Compile service code. 264 265 Compile the service entry function **DemoSdkMain** in the **helloworld.c** file, call the service entry **DemoSdkEntry** of **demolink**, and call the entry function through **SYS\_RUN\(\)** to start the service. 266 267 ``` 268 #include "hos_init.h" 269 #include "demosdk.h" 270 271 void DemoSdkMain(void) 272 { 273 DemoSdkEntry(); 274 } 275 276 SYS_RUN(DemoSdkMain); 277 ``` 278 2793. Compile build scripts. 280 281 Add the **applications/sample/wifi-iot/app/demolink/BUILD.gn** file, specify the paths of the source code and header file, and compile the static library file **libexample\_demolink.a**. 282 283 ``` 284 static_library("example_demolink") { 285 sources = [ 286 "helloworld.c" 287 ] 288 include_dirs = [ 289 "//utils/native/lite/include", 290 "//domains/iot/link/libbuild" 291 ] 292 } 293 ``` 294 295 Modify the **applications/sample/wifi-iot/app/BUILD.gn** file so that **demolink** is used in compilation. 296 297 ``` 298 import("//build/lite/config/component/lite_component.gni") 299 lite_component("app") { 300 features = [ 301 "demolink:example_demolink" 302 ] 303 } 304 ``` 305 306 307## Runtime<a name="section7737749184012"></a> 308 309Run the **hb build** command in the root directory of the code to compile and output the version package. Start **demolink**. The following shows the running result, which is consistent with the expected result of **demolink**. 310 311``` 312ready to OS start 313sdk ver:Hi3861V100R001C00SPC024 2020-08-05 16:30:00 314formatting spiffs... 315FileSystem mount ok. 316wifi init success! 317it is demosdk entry. 318it is demo biz: hello world. 319it is demo biz: hello world. 320``` 321 322## End<a name="section153301392411"></a> 323 324The third-party SDK integration is complete. 325 326
