物联网智能视频服务(消费版) 系统模块

二、使用流程

模块初始化 > 上线通知 > 时间同步（可选） > 下线通知 > 模块去初始化。


三、接口列表

该功能模块提供以下接口：

·iv_sys_init：系统模块初始化。

·iv_sys_exit：系统模块去初始化。

·iv_sys_get_certificate_type：获取系统认证方式。

·iv_sys_get_time：获取 ntp 时间。

·iv_sys_set_log_level：设置系统打印日志。

·iv_sys_set_upload_level：设置日志上传等级。

·iv_sys_dyn_reg_device：设备动态注册。

·iv_sys_active_offline：设备主动离线接口。

用户需注册以下回调函数：

·(*iv_sys_online_cb)() ：设备上线通知回调。

·(*iv_sys_offline_cb)() ：设备离线通知回调。

·(*iv_func_module_status_cb)() ：功能模块状态回调。

五、iv_sys_init

功能描述

系统资源的初始化。包括连接参数设置、上下线回调注册等，SDK 开始时调用。

函数原型

int iv_sys_init(const iv_sys_init_parm_s *pstInitParm);

参数说明

返回值

六、iv_sys_exit

功能描述

系统资源去初始，SDK 退出时调用。

函数原型

int iv_sys_exit(void);

参数说明

无

返回值

七、iv_sys_get_certificate_type

功能描述

获取系统的认证方式。

函数原型

iv_sys_certificate_type_e iv_sys_get_certificate_type(void);

参数说明

无

返回值

八、iv_sys_get_time

功能描述

设备获取 ntp 时间，单位 ms。

函数原型

int iv_sys_get_time(uint64_t *Param);

参数说明

返回值

九、iv_sys_set_log_level

功能描述

设置系统打印日志等级。

函数原型

void iv_sys_set_log_level(iv_sys_log_level_type_e level);

参数说明

返回值

无

十、iv_sys_set_upload_level

功能描述

设置日志上传等级。

函数原型

void iv_sys_set_upload_level(iv_sys_log_level_type_e level);

参数说明

返回值

注意：设置等级越低，上传的日志越多占用的带宽越大，使用前需要注意，有些版本由于资源或者其他原因，会关闭该功能，此时设置该等级会返回错误。

十一、iv_sys_dyn_reg_device

功能描述

动态注册设备

函数原型

int iv_sys_dyn_reg_device(iv_sys_device_info *psys_devInfo, char *dev_psk, int dev_psk_len);

参数说明

返回值

使用说明

·视频流设备：SDK 提供两种设备认证方式，一机一密和动态注册。

·一机一密：控制台生成三元组信息：产品 ID（ProductId）、设备名（DeviceName）、设备密钥（DeviceSecret），在设备生产的特定环节，烧录到非易失介质中，设备 SDK 运行时读取存放的设备信息，进行设备认证。

·动态注册：控制台生成产品 ID（ProductId）、产品密钥（ProductSecret），在生产过程中同一产品下的所有设备在生产过程可以烧录统一的产品信息，即产品 ID（ProductId）、产品密钥（ProductSecret）。设备出厂后，第一次上电时通过动态注册的方式获取设备名和设备密钥。此接口使用psys_devInfo 传入需注册的设备信息：设备名称、产品 ID、产品密钥，其中设备名称最大长度不超过48个字符，支持数字和字母的组合，且必须保证同一产品下设备名的唯一性（例如取名为 IMEI 或者 MAC 地址）。调用成功后返回的 dev_psk 需保存在非易失存储介质中供后期使用。此接口仅在第一次上电时调用，已注册设备重复注册无效！

·图片流设备：接口使用 psys_devInfo 传入需注册的设备信息，设备名称、产品 ID、产品密钥必须传入，其中设备名称最大长度不超过48个字符，支持数字和字母的组合，且同一产品下应保证设备名的唯一性。

十二、iv_sys_active_offline

功能描述

设备主动断开与后台的连接。

函数原型

int iv_sys_active_offline(void);

参数说明

无

返回值

注意：该接口会使设备主动离线，且不会触发重新连接，针对低功耗待机等特殊场景使用。

十三、iv_sys_online_cb

功能描述

设备上线回调，通知用户设备已经上线，并会带入网络时间参数，该回调中不要做耗时太长的操作。
网络异常时该时间参数不保证可靠，用户如需对设备进行校时，建议使用 iv_sys_get_time 接口。

函数原型

void (*iv_sys_online_cb)(uint64_t u64NetDateTime);

参数说明

返回值

十四、iv_sys_offline_cb

功能描述

设备失去与 IoT Video 服务器的连接后，通过此回调通知用户，该回调中不要做耗时太长的操作。

函数原型

void (*iv_sys_offline_cb)(iv_sys_offline_status_type_e status);

参数说明

返回值

十五、iv_func_module_status_cb

功能描述

功能模块在后台服务开启状态的回调通知。

函数原型

void (*iv_func_module_status_cb)(uint32_t module_status);

参数说明

返回值

使用说明

该接口将通知各功能模块是否在后台开启服务，使用功能模块状态参数通知。
按位表示，0：未开启；1：开启；bit 0：云存模块；bit 1：Ai模块。

十六、数据接口列表

该模块提供以下数据结构：

·iv_sys_init_parm_s：初始化参数。

·iv_sys_certificate_type_e：认证方式枚举。

·iv_sys_log_level_type_e：日志打印等级枚举。

·iv_sys_offline_status_type_e：离线状态枚举。

·iv_sys_cert_info：证书认证参数。

·iv_sys_device_info：设备三元组信息。

十八、iv_sys_init_parm_s

功能描述

系统模块初始化参数。

结构原型

typedef struct iv_sys_init_parm_s { char sys_cache_path[IV_SYS_FILE_PATH_MAX_LEN]; char sys_store_path[IV_SYS_FILE_PATH_MAX_LEN]; char *dev_info_path; iv_sys_device_info *device_info; uint32_t command_timeout; uint32_t keep_alive_ms; uint32_t mqtt_ping_interval_ms; uint8_t auto_connect_enable; uint32_t mqtt_recv_buf_max_size; uint32_t mqtt_write_buf_max_size; uint32_t max_channel_num; uint32_t comm_use_http; void (*iv_sys_online_cb)(uint64_t u64NetDateTime); void (*iv_sys_offline_cb)(iv_sys_offline_status_type_e status); void (*iv_func_module_status_cb)(uint32_t module_status);} iv_sys_init_parm_s;

参数说明

使用说明

1. dev_info_path 和 device_info 都是用于配置设备的三元组信息，前者指定device_info.json 位置，SDK会从device_info.json中读取设备三元组信息；后者是直接设置设备的三元组信息。这两个参数为互斥关系，同时设置后者生效。

2. 当设备初始化完成后，开始连接后台，当连接成功会触发 iv_sys_online_cb 通知，并传入当前 ntp 时间，网络状况较差时该时间不保证准确；当连接失败时会触发 iv_sys_offline_cb(IV_SYS_DISCONNECT_STATUS)， 此时 SDK 内部不会再进行重连，需要外部重新去初始化再进行初始化连接。

3. 当设备处于工作状态时，如果 MQTT 后台断开连接，SDK 会在大于一个 keep_alive_ms 时间后（约1.5倍的 keep_alive_ms）感知自己离线。

4. 当auto_connect_enable=1时，设备自主感知离线后会触发 iv_sys_offline_cb(IV_SYS_RECONNECT_STATUS) 通知用户处于重连状态，设备端会自动重连后台，当自动重连成功后会触发 iv_sys_online_cb；当自动重连失败后会触发 iv_sys_offline_cb(IV_SYS_DISCONNECT_STATUS) 通知用户连接失败，需要用户重新去初始化和初始化 IoT Video SDK。
当auto_connect_enable=0时, 设备自主感知离线后会触发 iv_sys_offline_cb(IV_SYS_DISCONNECT_STATUS) 通知用户连接失败，需要用户重新去初始化和初始化 IoT Video SDK。

十九、iv_sys_certificate_type_e

功能描述

认证方式类型枚举。

结构原型

typedef enum{ IV_SYS_CERTIFICATE_TYPE_CERT = 0, IV_SYS_CERTIFICATE_TYPE_KEY = 1, IV_SYS_CERTIFICATE_TYPE_BUTT} iv_sys_certificate_type_e;

参数说明

20、iv_sys_offline_status_type_e

功能描述

系统离线状态。

结构原型

typedef enum{ IV_SYS_RECONNECT_STATUS = 0, IV_SYS_DISCONNECT_STATUS = 1, IV_SYS_INVALID_STATUS} iv_sys_offline_status_type_e;

参数说明

21、iv_sys_log_level_type_e

功能描述

日志打印等级枚举。

结构原型

typedef enum{ IV_eLOG_DISABLE = 0, IV_eLOG_ERROR = 1, IV_eLOG_WARN = 2, IV_eLOG_INFO = 3, IV_eLOG_DEBUG = 4} iv_sys_log_level_type_e;

参数说明

22、iv_sys_cert_info

功能描述

证书认证信息。

结构原型

typedef struct { char dev_cert_file[IV_SYS_FILE_PATH_MAX_LEN]; char dev_pkey_file[IV_SYS_FILE_PATH_MAX_LEN];} iv_sys_cert_info;

参数说明

注意：说明：

注意：证书认证的详细介绍参考 设备身份认证。

23、iv_sys_device_info

功能描述

设备三元组信息描述结构体。

结构原型

typedef struct { char *product_id; char *device_name; union { iv_sys_cert_info *device_cert; char *device_key; };} iv_sys_device_info;

参数说明

注意：说明：

注意：证书认证还是密钥认证可根据接口 iv_sys_get_certificate_type 判断，两种认证方式是互斥，SDK 只能固定支持一种。

25、1. 系统模块初始化

int sys_init(void){ int eErrCode = 0; iv_sys_init_parm_s stSysInitParameters; memset(&stSysInitParameters, 0, sizeof(iv_sys_init_parm_s)); // strcpy(stSysInitParameters.sys_cache_path, "/tmp/video_cache"); // strcpy(stSysInitParameters.sys_store_path, "/tmp/video_storage");#if 0 iv_sys_device_info dev_info = {0}; dev_info.product_id = "xxxxx"; dev_info.device_name = "xxxx"; dev_info.device_key = "xxxx=="; stSysInitParameters.device_info = &dev_info;#else stSysInitParameters.dev_info_path = "./device_info.json";#endif stSysInitParameters.iv_sys_online_cb = device_online; stSysInitParameters.iv_sys_offline_cb = device_offline; stSysInitParameters.connect_timeout = 10 * 1000; stSysInitParameters.keep_alive_ms = 60 * 1000; stSysInitParameters.mqtt_ping_interval_ms = 20 * 1000; stSysInitParameters.auto_connect_enable = 1; eErrCode = iv_sys_init(&stSysInitParameters); if (eErrCode < 0) { Log_e("iv_sys_init error:%d", eErrCode); } iv_sys_certificate_type_e cert_type = iv_sys_get_certificate_type(); Log_i("certificate type:%s", (IV_SYS_CERTIFICATE_TYPE_CERT == cert_type) ? "cert" : "key"); iv_sys_set_log_level(IV_eLOG_DEBUG); return eErrCode;}

26、2. 系统模块退出

int sys_exit(void)