LinkVisual设备端SDK提供了网络摄像机(IPC)接入阿里云视频边缘智能服务的基础API,主要包括实时视频直播相关的接口、设备本地文件点播相关的接口、报警事件上报和图片上传的接口以及其他IPC控制相关的接口等,为物联网设备提供的视频直播、视频点播、图片上传的功能。

LinkVisual设备端SDK说明

LinkVisual设备端SDK的资源占用、平台支持和运行依赖如下所示。

  • 资源占用情况
    • RAM:1 MB的码流,预计占用500 KB的RAM内存。
    • ROM:占用2 MB的ROM内存。
  • 平台支持

    目前只能在支持C++11标准的Linux平台中使用。

  • 运行依赖

    依赖阿里云生活物联网平台SDK。生活物联网平台SDK提供了物联网通道能力,开发者需要同时获取LinkVisual SDK和生活物联网平台SDK来完成设备的接入。

    生活物联网平台SDK主要提供物联网控制通道能力,包括长连接、消息通知、事件上报等,LinkVisual SDK主要提供音视频流通道能力。LinkVisual响应生活物联网平台SDK的控制消息,进行流媒体业务处理。

SDK Demo

  1. 准备开发环境。
    生活物联网平台提供在x86 64位Ubuntu 16.04系统上编译的LinkVisual SDK和Demo供快速体验。在其他Linux版本上尚未验证过,推荐安装与阿里云一致的发行版以免有兼容性方面的问题。使用如下命令安装一些必备的软件。
    $ sudo apt-get install -y build-essential make git gcc g++ cmake
  2. 下载LinkVisual SDK Demo。
    LinkVisual SDK Demo
    说明 下载本LinkVisual SDK Demo将默认您同意本软件许可协议
  3. 编译运行。
    1. 确认内容。
      请将下载的后文件解压得到link_visual_ipc_v1.0.0文件夹,确认文件夹下的文件目录结构如下。
      ---- CMakeLists.txt
      |
      ---- samples
      |
      ---- sdk

      切换到link_visual_ipc_v1.0.0文件夹下,执行如下命令。

      $ mkdir -p build;建立一个build文件夹,用于归类编译产物
      $ cd build
      $ cmake ..;使用上层目录的CmakeLists.txt进行cmake
      $ make;编译
      $ make install;安装运行相关文件
    2. 创建产品和设备。
      请根据物联网平台接入指引来创建产品,并获取设备的证书信息(ProductKey、DeviceName、DeviceSecret)。
    3. 运行Demo。
      link_visual_ipc_v1.0.0文件夹下的build目录下,生成了对应的可执行程序。进入可执行程序目录下,运行如下的命令,其中your_productnameyour_devicenameyour_devicesecret需要替换为自己的设备证书信息。
      ./link_visual_demo -p your_productname -n your_devicename -s your_devicesecret

SDK获取

LinkVisual设备端SDK以静态库的形式提供,支持通过编译SDK接入不同芯片的设备。请发送邮件到申请。

请按如下模板发送邮件至ray.wl@antfin.com联系我们获取LinkVisual设备端SDK。

  • 邮件主题:获取固件升级SDK和操作说明文档
  • 邮件内容:
    公司名称:
    公司地址:
    联系人:
    联系电话:
    应用场景描述:

收到邮件后,我们会及时联系您,将已编译好的对应不同芯片设备的SDK提供给您。

API列表

  • SDK生命周期
    功能说明 对应接口
    SDK初始化 lv_init
    SDK停止 lv_destroy
  • Link Kit消息注入
    功能说明 对应接口
    Link Kit的MQTT消息注入 lv_linkkit_adapter
  • 直播及点播服务
    功能说明 对应接口
    通知直播、点播服务已开启 lv_start_push_streaming_cb
    通知直播、点播服务已结束 lv_stop_push_streaming_cb
    推送视音频配置参数 lv_stream_send_config
    推送视频数据 lv_stream_send_video
    推送音频数据 lv_stream_send_audio
    推流过程中命令控制(暂停等) lv_on_push_streaming_cmd_cb
    点播的文件列表查询 lv_query_storage_record_cb
    强制关闭一路链接 lv_stream_force_stop
    录像文件播放结束 lv_post_file_close
  • 图片服务
    功能说明 对应接口
    图片上传 lv_post_alarm_image
    通知上传图片 lv_trigger_pic_capture_cb
  • 语音对讲服务
    功能说明 对应接口
    通知开启服务 lv_start_voice_intercom_cb
    通知结束服务 lv_stop_voice_intercom_cb
    开启服务 lv_voice_intercom_start_service
    停止服务 lv_voice_intercom_stop_service
    发送音频 lv_voice_intercom_send_audio
    接收音频 lv_voice_intercom_receive_data_cb
    接收音频参数配置 lv_voice_intercom_receive_metadata_cb

对接指南

请开发者根据SDK Demo中的编译说明步骤,完成demo的编译和运行后,在进行实际API的对接。

  • 功能说明

    获取到LinkVisual SDK后,开始进入对接阶段。下文内容列出了当前SDK能够支持的所有功能,开发者根据自身产品定义自行检查。

    • 配网功能(一键配网、零配等)
    • OTA功能
    • Link Kit的MQTT消息收发
    • Link Kit自定义物模型
    • 直播功能
    • 卡录像点播功能
    • PTZ功能
    • 图片上报功能(抓图功能和移动侦测报警功能)
    • 语音对讲功能
  • SDK变更

    已对接过V1.1.x之前版本的开发者,请阅读V1.1.x版本变更说明。

    1. 在Link Kit增加了LinkVisual的自定义消息ITE_LINK_VISUAL,具体的使用方式请参见linkkit_adapter.cpp中的实现。
    2. lv_voice_intercom_send_audio增加了@param [IN] timestamp: 音频帧时间戳参数,音频帧时间戳单位为毫秒(ms)。
    3. linkkit_adapter_tsl_service改为lv_linkkit_adapter接口,并增加一个枚举量入参,LV_LINKKIT_ADAPTER_TYPE_TSL_SERVICE为原物模型属性,新增LV_LINKKIT_ADAPTER_TYPE_LINK_VISUAL用于处理LinkVisual自定义消息,具体请参见linkkit_adapter.cpp中的实现。
    4. 视频流现支持H265(含加密)。
    5. 删除Demo对库iniparser的依赖,不影响SDK的集成。
    6. lv_on_push_streaming_cmd_cb的时间戳参数由double改为unsigned int,单位为毫秒(ms)。
    7. 其他SDK内部的优化。
  • SDK内容

    将获取到的SDK解压后,可以看到以下内容。

    • version.txt:版本说明
    • CMakeLists.txt:基于cmake的编译的基础示例
    • LinkVisual:内含sdk和samples,分别包含库和头文件、示例代码
    • third_party:LinkVisual依赖的一些库信息
  • LinkVisual依赖库
    • cJSON,为LinkVisual提供JSON解析的支持,使用版本为V1.7.7。
    • linkkit-sdk-c,为阿里云提供的物联网接入sdk,LinkVisual使用版本v2.3.0。更多信息请访问官方网址官方文档
  • 编译说明
    • 环境配置

      编译依赖cmake等相关软件,此处以Ubuntu 16.04系统下安装为例。

      $ sudo apt-get install -y build-essential make git gcc g++ cmake tree
    • cJSON编译

      third_party目录中解压cJSON-1.7.7,并进入解压后的文件夹。

      $ cd third_party
      $ tar -vxf cJSON-1.7.7.tar.gz;解压代码压缩包
      $ cd cJSON-1.7.7

      修改Makefile,在文件最开始加入工具链的声明,准备交叉编译。

      说明 请替换为实际对应的交叉编译工具链。
      CC        =   arm-linux-gcc
      LD        =   arm-linux-ld
      AR       =   arm-linux-ar

      编译并确认是否生成了libcjson.a以及头文件cJSON.h是否存在。

      $ make
      
      $ ls lib*.a;确认libcjson.a已生成
      $ ls *.h
    • linkkit-sdk-c编译

      third_party目录里解压linkkit-sdk-c,并进入解压后的文件夹。

      $ cd third_party
      $ tar -vxf linkkit-sdk-c.tar.gz;解压代码压缩包
      $ cd linkkit-sdk-c

      修改src/board/config.ubuntu.x86文件,在文件最后添加CROSS_PREFIX :=<交叉编译工具链路径前缀>,准备交叉编译。

      说明 请将<交叉编译工具链路径前缀>替换为实际对应的交叉编译工具链。
      CROSS_PREFIX :=arm-linux-

      选择Ubuntu编译,并确认生成库libiot_tls.a/libiot_sdk.a/libiot_hal.a

      $ make reconfig;这里选择ubuntu对应的数字
      
      $ make;
      
      $ ls output/lib/*.a;这里只需要有libiot_tls.a/libiot_sdk.a/libiot_hal.a
      
      $ tree include;这里可以看到很多头文件,如iot_import.h等,全部都需要
    • 整体编译

      重新回到SDK解压后的文件夹根目录,准备开始整体编译。

      修改CMakeLists.txt文件中的TOOLCHAINS_PREFIX设置,第二个参数设置为交叉编译工具链前缀。

      说明 请替换为实际对应的交叉编译工具链。
      set(TOOLCHAINS_PREFIX "arm-linux-" CACHE STRING "set the toolchain")

      开始编译。

      $ mkdir -p build;建立一个build文件夹,用于归类编译产物
      $ cd build
      $ cmake ..;使用上层目录的CmakeLists.txt进行cmake
      $ make;编译
      $ make install;安装运行相关文件

      自行编译时,请参考链接顺序link_visual_ipc iot_sdk cjson iot_hal iot_tls pthread rt。编译的CFLAGS,请添加-std=c++11

    • 运行设备demo

      build文件夹拷贝至板子上,并进入build文件后执行以下命令,其中your_productnameyour_devicenameyour_devicesecret需要替换为自己的设备证书信息。

      $ ./link_visual_demo -p your_productname -n your_devicename -s your_devicesecret
  • 生活物联网平台SDK对接

    当前LinkVisual主要依赖于Link Kit的MQTT功能,针对此功能,LinkVisual提供了该功能的使用要求,详情请见sample/linkkit_adapter.cpp中。其他如配网、OTA等功能,需要开发者根据文档开发。详情请参见SDK功能说明

    • 配网功能

      Link Kit提供配网功能和设备绑定功能,配网方式包括一键配网等,开发者根据自身需求选择对接。配网功能请参见配网功能说明

    • OTA功能

      Link Kit提供OTA功能。OTA功能对于设备后续版本的迭代更新有着至关重要的功能,要求开发者必须完成OTA功能的对接。当前LinkVisual要求使用更高级版接口的OTA功能。详情请参见OTA功能

    • Link Kit高级版接口

      LinkVisual使用了Link Kit高级版接口,此处列出LinkVisual使用到的一些接口。

      • Link Kit生命周期
        IOT_Linkkit_Open;打开一个linkkit句柄
        IOT_Linkkit_Connect;连接服务器
        IOT_Linkkit_Yield;用于维持心跳,建议其参数值为200ms,不建议自行修改,会导致MQTT消息往外抛出变慢。
        IOT_Linkkit_Close;关闭linkkit连接和句柄
      • Link Kit消息订阅
        IOT_RegisterCallback;用于订阅linkkit消息
        
        LinkVisual要求必须要订阅的有:
        ITE_SERVICE_REQUEST:物模型的服务类消息,消息回调中部分消息需要使用lv_linkkit_adapter交由LinkVisual处理。
        ITE_LINK_VISUAL:LinkVisual自定义消息,消息回调中所有消息需要使用lv_linkkit_adapter交由LinkVisual处理。
        具体参考LinkVisual SDK中的linkkit_adapter.cpp
      • Link Kit其他配置
        IOT_SetLogLevel;用于设置Linkkit的打印级别,初始对接阶段建议设置为DEBUG。
        CONFIG_MQTT_TX_MAXLEN;定义在iot_import_config.h,影响MQTT发送的最大值。
        LinkVisual定义的卡录像列表查询功能中,由于需要查询的数量不同,导致最终查询的字符串长度可能超过默认MQTT的长度设置,
        需要根据实际长度定义最大值。
    • Link Kit功能验收

      对接LinkVisual功能前,要求Link Kit以下功能已经是可用状态。

      • IOT_Linkkit_Connect连接成功。
      • IOT_RegisterCallback注册了ITE_SERVICE_REQUEST/ITE_LINK_VISUAL回调。

      以下Link Kit功能可在对接LinkVisual过程中完成

      • 配网功能。
      • OTA功能。
  • LinkVisual SDK对接
    • SDK中的LinkVisual/sdk/link_visual_ipc.hLinkVisual/sdk/link_visual_def.h是SDK的头文件。
    • SDK中的LinkVisual/samples/demo.cpp主要说明了LinkVisual SDK的对接示例,文档中的示例代码主要来自于demo.cpplinkkit_adapter.cpp

    LinkVisual以非源码形式提供功能,在对接过程中出现问题时,LinkVisual相当于黑盒子,不利于问题的排查。因此我们对问题排查提出了一定的要求,以提高问题排查的效率,如下所示。

    • 日志:提供所有问题的日志。日志中要求包含lv_init函数打印的SDK版本信息,要求lv_init中的log_level为DEBUG级别,要求问题发生的前后日志尽可能的详细。
    • core:发生崩溃性问题时,除日志外,要求提供core文件的堆栈信息。
    • tcpdump:部分问题可能要求提供tcpdump进行网络数据抓包。

    LinkVisual SDK对接相关的API列表请参见API列表