鴻蒙OpenHarmony【集成三方SDK】 （基于Hi3861開發板）

OpenHarmony致力于打造一套更加開放完善的IoT生態系統，為此OpenHarmony規劃了一組目錄，用于將各廠商的SDK集成到OpenHarmony中。本文檔基于Hi3861開發板，向平臺開發者介紹將SDK集成到OpenHarmony的方法。

規劃目錄結構

三方SDK通常由靜態庫和適配代碼構成。SDK的業務邏輯通過硬件模組工具鏈編譯得到靜態庫libs，每款模組都有其對應的libs。SDK的南向API與OpenHarmony 的API存在使用差異，該差異可通過adapter適配代碼屏蔽，不同模組可共用一套adapter。

基于以上特征，在OpenHarmony目錄結構中，可以對三方SDK目錄做如下劃分。

• 適配代碼adapter，放置到domains/iot/link/ 目錄下，與模組解耦。
• 業務庫libs，放置到device/hisilicon/hispark_pegasus/sdk_liteos/3rd_sdk/ 目錄下，與模組綁定。

平臺開發者在適配前，務必先依次完成以下步驟，下面以demolink SDK舉例，進行介紹。

1. 創建廠商目錄，domains/iot/link/demolink/、device/hisilicon/hispark_pegasus/sdk_liteos/3rd_sdk/demolink/ ，用于廠商隔離。
2. 創建domains/iot/link/demolink/BUILD.gn ，用于構建適配代碼。
3. 創建device/hisilicon/hispark_pegasus/sdk_liteos/3rd_sdk/demolink/libs/ 目錄，用于存放業務庫libs。

鴻蒙開發指導文檔：[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md]

.
├── domains
│   └── iot
│       └── link
│           ├── demolink
│           │   └── BUILD.gn
│           ├── libbuild
│           │   └── BUILD.gn
│           └── BUILD.gn
└── device
     └── hisilicon
         └── hispark_pegasus
             └── sdk_liteos
                 └── 3rd_sdk
                     └── demolink
                         └── libs
HarmonyOS與OpenHarmony鴻蒙文檔籽料：mau123789是v直接拿

構建業務libs

平臺SDK業務一般以靜態庫的形式提供，平臺廠商在獲取到OpenHarmony代碼后，需要根據對應的硬件模組vendor，編譯業務libs，并將編譯結果放置在device/hisilicon/hispark_pegasus/sdk_liteos/3rd_sdk/demolink/libs/ 目錄下。下面介紹業務libs的構建方法。

OpenHarmony已規劃用于編譯業務libs的目錄domains/iot/link/libbuild/ ，該目錄中包含domains/iot/link/libbuild/BUILD.gn和domains/iot/link/BUILD.gn文件，目錄結構如下。

.
└── domains
    └── iot
        └── link
            ├── demolink
            │   └── BUILD.gn
            ├── libbuild
            │   └── BUILD.gn
            └── BUILD.gn

平臺開發者在構建libs前，務必先完成如下步驟。

1. 在domains/iot/link/libbuild/ 目錄下放置業務源碼文件，包括.c和.h文件。

   .
   └── domains
       └── iot
           └── link
               ├── demolink
               │   ├── demosdk_adapter.c
               │   ├── demosdk_adapter.h
               │   └── BUILD.gn
               ├── libbuild
               │   ├── demosdk.c
               │   ├── demosdk.h
               │   └── BUILD.gn
               └── BUILD.gn
   

2. 適配domains/iot/link/libbuild/BUILD.gn，在編譯完成后還原該文件。
   在BUILD.gn中，sources為需要參與構建的源文件，include_dirs為依賴的頭文件路徑，構建的目標結果是生成靜態庫libdemosdk.a。

   static_library("demosdk") {
       sources = [
           "demosdk.c"
       ]
       include_dirs = [
           "http://domains/iot/link/libbuild",
           "http://domains/iot/link/demolink"
       ]
   }
   

3. 適配domains/iot/link/BUILD.gn，在編譯完成后還原該文件。
   此BUILD.gn文件用于指定構建條目，需要在features中填入所有需參與編譯的靜態庫條目，使domains/iot/link/libbuild/BUILD.gn參與到構建中來。

   import("http://build/lite/config/subsystem/lite_subsystem.gni")
   import("http://build/lite/config/component/lite_component.gni")
   lite_subsystem("iot") {
       subsystem_components = [
           ":link"
       ]
   }
   lite_component("link") {
       features = [
           "libbuild:demosdk"
       ]
   }
   

完成以上3點后，需在代碼根目錄下執行命令“hb build -T //domains/iot/link:iot”，等待執行完成，檢查out/hispark_pegasus/wifiiot_hispark_pegasus/libs/目錄下是否生成了目標庫文件。

將庫文件拷貝到device/hisilicon/hispark_pegasus/sdk_liteos/3rd_sdk/demolink/libs/ 目錄下，并將domains/iot/link/libbuild/ 目錄中的.c和.h文件清除。

編寫適配代碼

代碼編寫

平臺SDK中使用的API通常與OpenHarmony API存在差異，無法直接使用，需要一層適配代碼adapter進行中間轉換。本節以domains/iot/link/demolink/demosdk_adapter.c中的任務創建接口DemoSdkCreateTask舉例，向開發者演示如何在OpenHarmony上編寫適配代碼。

1. 查看待適配接口DemoSdkCreateTask的描述、參數、返回值。

   struct TaskPara {
       char *name;
       void *(*func)(char* arg);
       void *arg;
       unsigned char prio;
       unsigned int size;
   };
   
   /*
    * IoT OS 創建線程接口
    * 返回值: 返回0 成功, 其他 失敗
    */
   int DemoSdkCreateTask(unsigned int *handle, const struct TaskPara *para);
   

2. 查看OpenHarmony API接口文檔，選取一個功能類似的接口，并比對參數及用法上的差異。例如本文選取osThreadNew ，通過和DemoSdkCreateTask接口比對，可以發現兩接口依賴的參數基本一致，只是參數所歸屬的結構體不同。

   typedef struct {
       const char                   *name;   ///< name of the thread
       uint32_t                 attr_bits;   ///< attribute bits
       void                      *cb_mem;    ///< memory for control block
       uint32_t                   cb_size;   ///< size of provided memory for control block
       void                   *stack_mem;    ///< memory for stack
       uint32_t                stack_size;   ///< size of stack
       osPriority_t              priority;   ///< initial thread priority (default: osPriorityNormal)
       TZ_ModuleId_t            tz_module;   ///< TrustZone module identifier
       uint32_t                  reserved;   ///< reserved (must be 0)
   } osThreadAttr_t;
   
   /// Create a thread and add it to Active Threads.
   /// param[in]     func          thread function.
   /// param[in]     argument      pointer that is passed to the thread function as start argument.
   /// param[in]     attr          thread attributes; NULL: default values.
   /// return thread ID for reference by other functions or NULL in case of error.
   osThreadId_t osThreadNew (osThreadFunc_t func, void *argument, const osThreadAttr_t *attr);
   

3. 完成代碼差異轉換。

   int DemoSdkCreateTask(unsigned int *handle, const struct TaskPara *para)
   {
       osThreadAttr_t attr = {0};
       osThreadId_t threadId;
       if (handle == 0 || para == 0) {
           return DEMOSDK_ERR;
       }
       if (para- >func == 0) {
           return DEMOSDK_ERR;
       }
       if (para- >name == 0) {
           return DEMOSDK_ERR;
       }
       attr.name = para- >name;
       attr.priority = para- >prio;
       attr.stack_size = para- >size;
       threadId = osThreadNew((osThreadFunc_t)para- >func, para- >arg, &attr);
       if (threadId == 0) {
           printf("osThreadNew failn");
           return DEMOSDK_ERR;
       }
       *(unsigned int *)handle = (unsigned int)threadId;
       return DEMOSDK_OK;
   }
   

腳本編寫

開發者在完成代碼適配后，還需要在adapter同級目錄下新建BUILD.gn文件。該文件可在整包構建時，將適配代碼編譯成靜態庫，并鏈接到bin包中去。在domains/iot/link/demolink/BUILD.gn中，sources中為需要參與構建的源文件，include_dirs中為依賴的頭文件路徑，構建目標結果是生產靜態庫libdemolinkadapter.a。

import("http://build/lite/config/component/lite_component.gni")
static_library("demolinkadapter") {
    sources = [
        "demosdk_adapter.c"
    ]
    include_dirs = [
        "http://kernel/liteos-m/kal/cmsis",
        "http://domains/iot/link/demolink"
    ]
}

修改domains/iot/link/BUILD.gn文件，使domain/iot/hilink/BUILD.gn參與到構建系統中。

import("http://build/lite/config/subsystem/lite_subsystem.gni")
import("http://build/lite/config/component/lite_component.gni")
lite_subsystem("iot") {
    subsystem_components = [
        ":link"
    ]
}
lite_component("link") {
    features = [
        "demolink:demolinkadapter"
    ]
}

編寫業務代碼

業務libs庫和適配代碼準備就緒后，還需要編寫業務入口函數，調起三方SDK的業務入口。

下面以demolink舉例，介紹如何在applications/sample/wifi-iot/app/路徑下編寫代碼，調起demosdk的入口函數。

1. 目錄創建
   開發者編寫業務時，務必先在applications/sample/wifi-iot/app/ 路徑下新建一個目錄（或一套目錄結構），用于存放業務源碼文件。
   例如：在app下新增業務目錄demolink，并在其中創建業務入口代碼helloworld.c和編譯構建文件BUILD.gn，如下。

   .
   └── applications
       └── sample
           └── wifi-iot
               └── app
                   │── demolink
                   │    │── helloworld.c
                   │    └── BUILD.gn
                   └── BUILD.gn
   

2. 編寫業務代碼。
   在helloworld.c文件中編寫業務入口函數DemoSdkMain，并調起demolink的業務DemoSdkEntry，最后通過SYS_RUN()調用入口函數完成業務啟動。

   #include "hos_init.h"
   #include "demosdk.h"
   
   void DemoSdkMain(void)
   {
       DemoSdkEntry();
   }
   
   SYS_RUN(DemoSdkMain);
   

3. 編寫構建腳本
   新增applications/sample/wifi-iot/app/demolink/BUILD.gn文件，指定源碼和頭文件路徑，編譯輸出靜態庫文件libexample_demolink.a。

   static_library("example_demolink") {
       sources = [
           "helloworld.c"
       ]
       include_dirs = [
           "http://utils/native/lite/include",
           "http://domains/iot/link/libbuild"
       ]
   }
   

   修改applications/sample/wifi-iot/app/BUILD.gn，使demolink參與編譯。

   import("http://build/lite/config/component/lite_component.gni")
   lite_component("app") {
       features = [
           "demolink:example_demolink"
       ]
   }
   

運行

在代碼根目錄下，執行命令“hb build”編譯輸出版本包。最后啟動運行，運行結果如圖所示，與demolink預期相符。

ready to OS start
sdk ver:Hi3861V100R001C00SPC024 2020-08-05 16:30:00
formatting spiffs...
FileSystem mount ok.
wifi init success!
it is demosdk entry.
it is demo biz: hello world.
it is demo biz: hello world.

審核編輯 黃宇