移植示例说明

本文介绍在移植C Link SDK过程中,需要实现的系统依赖接口及说明。

前提条件

已获取SDK,具体操作,请参见获取SDK

整体框架

整体框架

C Link SDK支持在不同操作系统或硬件平台上运行,是因为C Link SDK与操作系统或目标硬件的所有操作,均被抽象为系统依赖接口。因此,在开发产品时,您不仅需要调用SDK的API实现产品业务逻辑,还需要编写代码,实现SDK的系统依赖接口。

说明
  • C Link SDK自版本v4.1.0开始,已在SDK内部实现连接安全传输(TLS),移植网络接口仅需实现TCP传输。

  • 如果用户从老版本SDK升级至新版本,需关闭aiot_port/*_port.c中的TLS开关(CORE_SYSDEP_MBEDTLS_ENABLED)

系统依赖接口说明

  • 系统依赖接口将C Link SDK与具体的操作系统解耦,不同的系统仅需实现对应的系统依赖接口。

  • 系统依赖接口的原型定义:aiot_sysdep_portfile_t,用户需定义全局变量g_aiot_sysdep_portfile,该变量为目标系统接口实现,完成移植。

  • 通用接口与互斥锁接口比较简单,其使用方法未在本文中说明。但在移植过程中,所有接口均需实现,不能为NULL,否则会报错。

系统依赖接口列表

类型

名称

说明

通用接口

core_sysdep_malloc

申请内存。

core_sysdep_free

释放内存。

core_sysdep_time

获取当前的时间戳,Link SDK用于差值计算。

core_sysdep_sleep

睡眠指定的毫秒数。

core_sysdep_rand

随机数生成方法。

网络接口

core_sysdep_network_init

创建1个网络会话。

core_sysdep_network_setopt

配置1个网络会话的连接参数。

core_sysdep_network_establish

建立1个网络会话,作为MQTT、HTTP等协议的底层承载。

core_sysdep_network_recv

从指定的网络会话上读取。

core_sysdep_network_send

在指定的网络会话上发送。

core_sysdep_network_deinit

销毁1个网络会话。

互斥锁接口

core_sysdep_mutex_init

创建互斥锁。

core_sysdep_mutex_lock

申请互斥锁。

core_sysdep_mutex_unlock

释放互斥锁。

core_sysdep_mutex_deinit

销毁互斥锁。

配置网络接口

移植C Link SDK时,您需配置core_sysdep_network_setopt的以下参数类型。

  • 配置以下参数类型,选择要连接的网络类型:兼容TCP和UDP的网络连接(Socket类型)。

    类型

    说明

    CORE_SYSDEP_SOCKET_TCP_CLIENT

    TCP客户端,MQTT、HTTP、HTTP2、WebSocket等功能均使用该类型的连接。如果您需要使用以上功能,需要实现网络接口的该参数类型。

    CORE_SYSDEP_SOCKET_UDP_CLIENT

    UDP客户端,如果您需使用CoAP连接,需实现网络接口的该参数类型。

  • 保存以下参数类型的设置,用于后续建立连接使用。

    类型

    说明

    CORE_SYSDEP_NETWORK_SOCKET_TYPE

    需要建立的Socket类型。

    数据类型:(core_sysdep_socket_type_t *)

    CORE_SYSDEP_NETWORK_HOST

    用于建立网络连接的域名地址或IP地址,内存与上层模块共用。

    数据类型:(char *)

    CORE_SYSDEP_NETWORK_BACKUP_IP

    当建联DNS解析失败时,使用此备用IP重试,可忽略。

    CORE_SYSDEP_NETWORK_PORT

    用于建立网络连接的端口号。

    数据类型:(uint16_t *)

    CORE_SYSDEP_NETWORK_CONNECT_TIMEOUT_MS

    建立网络连接的超时时间。

    数据类型:(uint32_t *)

    CORE_SYSDEP_NETWORK_MAX

    SDK未使用此接口类型,无需实现该接口类型,可忽略。

移植样例

移植样例以POSIX接口为例,定制下载SDK时,设备OS选择(POSIX Compliant)。在下载的C Link SDK文件中,找到样例文件portfile/aiot_port/posix_port.c,查看基于POSIX接口实现的移植样例。

移植验证

在您参考上文移植LinkSDK完成以后,可通过以下步骤快速验证移植的接口功能是否正常。

  1. 打开./LinkSDK/demos/sysdep_api_test_demo.c文件,实现如下功能

    1. 实现任务创建函数。

      验证将会使用的并发能力,需要在目标系统(移植后的环境)中创建任务。

    2. 设置堆的最大空间。

      允许SDK使用的最大堆的大小,验证堆的使用是否正常。

    POSIX接口示例代码:

    /*>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> TODO START >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>*/
    /*
     * TODO: task_start功能实现,创建任务,并执行任务,待任务结束后自行退出
     * @param[in] entry  任务函数入口
     * @param[in] argv   任务函数参数
     */
    #include<pthread.h>
    void task_start(TASK_FUNC entry,void* argv)
    {
        pthread_t id;
        pthread_create(&id, NULL, (void*(*)(void *))entry, argv);
    }
    /*TODO: 堆的最大空间,单位字节 */
    #define HEAP_MAX    ( 20 * 1024 )
    /*<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< TODO END <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<*/
  2. 编译并运行移植测试demo:sysdep_api_test_demo.c

  3. 查看运行结果。

    • 运行成功

      出现以下日志内容,表示移植的Link SDK接口功能正常。

      Line[804]: TOTAL TEST START
      Line[806]: TEST [1/5] [RANDOM_TEST ] .....................................[START]
      Line[812]: TEST [1/5] [RANDOM_TEST ] .....................................[SUCCESS]
      Line[806]: TEST [2/5] [HEAP_TEST   ] .....................................[START]
      Line[812]: TEST [2/5] [HEAP_TEST   ] .....................................[SUCCESS]
      Line[806]: TEST [3/5] [TIME_TEST   ] .....................................[START]
      Line[519]: sleep 30000 ms test
      Line[499]: sleep_test_task_1 enter wanna sleep: 10000ms
      Line[499]: sleep_test_task_2 enter wanna sleep: 10000ms
      Line[595]: sleep 10000ms start:[1642324352748] stop:[1642324362748] expected 
      Line[812]: TEST [3/5] [TIME_TEST   ] .....................................[SUCCESS]
      Line[806]: TEST [4/5] [NETWORK_TEST] .....................................[START]
      Line[372]: [NETWORK_TEST.RECV] test success
      Line[812]: TEST [4/5] [NETWORK_TEST] .....................................[SUCCESS]
      Line[806]: TEST [5/5] [MUTEX_TEST  ] .....................................[START]
      Line[692]: mutex lock task1, unlock task2 3000 ms
      Line[703]: task1 value [30 --> 30], task2 value [30 --> 60] 
      Line[715]: unlock task1, lock task2 3000 ms
      Line[725]: task1 value [30 --> 60], task2 value [60 --> 60] 
      Line[736]: unlock task1, lock task2 3000 ms
      Line[742]: task1 value [60 --> 90], task2 value [60 --> 90]
      Line[812]: TEST [5/5] [MUTEX_TEST  ] .....................................[SUCCESS]
      Line[816]: TOTAL TEST SUCCESS
    • 运行失败

      如果无法运行到最后,或运行到最后出现错误信息,请根据下表进行定位处理。

      错误码

      说明

      相关接口

      TEST_ERR_RANDOM

      随机数生成函数测试异常

      core_sysdep_rand

      TEST_ERR_MALLOC

      内存申请测试异常

      core_sysdep_malloc

      TEST_ERR_HEAP

      内存申请及释放功能测试异常

      core_sysdep_malloc

      core_sysdep_free

      TEST_ERR_SLEEP

      睡眠或者系统时间测试异常

      core_sysdep_time

      core_sysdep_sleep

      TEST_ERR_MUTEX

      互斥锁功能测试异常

      core_sysdep_mutex_init

      core_sysdep_mutex_lock

      core_sysdep_mutex_unlock

      core_sysdep_mutex_deinit

      TEST_ERR_NETWORK

      网络功能测试异常

      core_sysdep_network_init

      core_sysdep_network_setopt

      core_sysdep_network_establish

      core_sysdep_network_recv

      core_sysdep_network_send

      core_sysdep_network_deinit

      TEST_ERR_GENERIC

      未知错误