功能介绍
本模块提供设备上下线通知，时间同步和认证方式获取等功能，是 IoT Video 的必选模块，需要第一个初始化。
使用流程
模块初始化 > 上线通知 > 时间同步（可选） > 下线通知 > 模块去初始化。
接口列表
该功能模块提供以下接口：
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);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
pstInitParm | iv_sys_init_parm_s | 初始化参数。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败，对应相应错误码。 |
iv_sys_exit
功能描述
系统资源去初始，SDK 退出时调用。
函数原型
int iv_sys_exit(void);
参数说明
无
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败，对应相应错误码。 |
iv_sys_get_certificate_type
功能描述
获取系统的认证方式。
函数原型
iv_sys_certificate_type_e iv_sys_get_certificate_type(void);
参数说明
无
返回值
返回值 | 描述 |
IV_SYS_CERTIFICATE_TYPE_CERT | 证书认证。 |
IV_SYS_CERTIFICATE_TYPE_KEY | 密钥认证。 |
IV_SYS_CERTIFICATE_TYPE_BUTT | 错误。 |
iv_sys_get_time
功能描述
设备获取 ntp 时间，单位 ms。
函数原型
int iv_sys_get_time(uint64_t *Param);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
Param | uint64_t | ntp 时间，单位 ms。 | 输出 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_SYS_NTP_NOT_AVAILABLE | NTP 时间不可用，ntp 时间错误，或 ntp 时间不精确。 |
IV_ERR_* | 失败，对应相应错误码。 |
iv_sys_set_log_level
功能描述
设置系统打印日志等级。
函数原型
void iv_sys_set_log_level(iv_sys_log_level_type_e level);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
level | iv_sys_log_level_type_e | 日志的打印等级。 | 输入 |
返回值
无
iv_sys_set_upload_level
功能描述
设置日志上传等级。
函数原型
void iv_sys_set_upload_level(iv_sys_log_level_type_e level);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
level | iv_sys_log_level_type_e | 日志的打印等级。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败，对应相应错误码。 |
注意：
设置等级越低，上传的日志越多占用的带宽越大，使用前需要注意，有些版本由于资源或者其他原因，会关闭该功能，此时设置该等级会返回错误。
iv_sys_dyn_reg_device
功能描述
动态注册设备
函数原型
int iv_sys_dyn_reg_device(iv_sys_device_info *psys_devInfo, char *dev_psk, int dev_psk_len);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
psys_devInfo | iv_sys_device_info | 设备信息。 | 输入 |
dev_psk | char * | 设备密钥，最大长度128。 | 输出 |
dev_psk_len | int | 设备密钥长度。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* | 失败，对应相应错误码。 |
使用说明
视频流设备：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_ERR_NONE | 成功。 |
IV_ERR_* | 失败，对应相应错误码。 |
注意：
该接口会使设备主动离线，且不会触发重新连接，针对低功耗待机等特殊场景使用。
iv_sys_online_cb
功能描述
设备上线回调，通知用户设备已经上线，并会带入网络时间参数，该回调中不要做耗时太长的操作。
网络异常时该时间参数不保证可靠，用户如需对设备进行校时，建议使用 iv_sys_get_time 接口。
函数原型
void (*iv_sys_online_cb)(uint64_t u64NetDateTime);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
u64NetDateTime | uint64_t | 网络时间，距1970年毫秒数。 | 输入 |
返回值
返回值 | 描述 |
void | 无 |
iv_sys_offline_cb
功能描述
设备失去与 IoT Video 服务器的连接后，通过此回调通知用户，该回调中不要做耗时太长的操作。
函数原型
void (*iv_sys_offline_cb)(iv_sys_offline_status_type_e status);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
status | iv_sys_offline_status_type_e | 离线时的状态 | 输入 |
返回值
返回值 | 描述 |
void | 无 |
iv_func_module_status_cb
功能描述
功能模块在后台服务开启状态的回调通知。
函数原型
void (*iv_func_module_status_cb)(uint32_t module_status);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
module_status | uint32_t | 功能模块状态 | 输入 |
返回值
返回值 | 描述 |
void | 无 |
使用说明
该接口将通知各功能模块是否在后台开启服务，使用功能模块状态参数通知。
按位表示，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;
参数说明
成员名称 | 描述 | 取值 |
sys_cache_path | 可读写目录（缓存目录），存储缓存文件，断电可以丢失。 | 字符串，可选。 |
sys_store_path | 可读写目录（缓存目录），存储重要文件，断电不会丢失。 | 字符串，可选。 |
dev_info_path | device_info.json 的位置，最大长度128。 | 字符串，可选。 |
device_info | 设备信息结构体。 | 结构体，可选。 |
command_timeout | 连接超时时间，单位 ms。 | 最小值5 * 1000ms。 |
keep_alive_ms | 后台确认掉线的超时时间，设置的越长，后台判断离线的间隔就越长，最大690 * 1000ms。 | 推荐 240 * 1000ms，必选。 |
mqtt_ping_interval_ms | 设备发送 MQTT Ping 包时间间隔，设置的越小，发包就越频繁，复杂网络环境越不容易出现 mqtt 离线，必须小于 keep_alive_ms。 | 可选。 |
auto_connect_enable | 自动连接使能，设备断线重连时，若失败则等待时间会翻倍，最大时间间隔60s。 | 使能：1 关闭：0 |
mqtt_recv_buf_max_size | mqtt 物模型接收 buf 大小，默认2048字节。 | 可选。 |
mqtt_write_buf_max_size | mqtt 物模型发送 buf 大小，默认2048字节。 | 可选。 |
max_channel_num | 设备支持的最大通道数量，IPC 设备配置为0，NVR 或者多摄像头设备根据实际摄像头数量配置。 | 最大值为64。 |
comm_use_http | 内部通信是否使用 HTTP 方式（默认使用 HTTPS 方式）。 | 可选， 0：使用 HTTPS 方式。 1：使用 HTTP 方式。 |
iv_sys_online_cb | 设备上线通知。 | 必选参数。 |
iv_sys_offline_cb | 设备离线通知。 | 必选参数。 |
iv_func_module_status_cb | 功能模块状态（暂未使用）。 | 可选参数。 |
使用说明
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;
参数说明
成员名称 | 描述 | 取值 |
IV_SYS_CERTIFICATE_TYPE_CERT | 证书认证。 | 0 |
IV_SYS_CERTIFICATE_TYPE_KEY | 密钥认证。 | 1 |
IV_SYS_CERTIFICATE_TYPE_BUTT | 无效认证。 | 2 |
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;
参数说明
成员名称 | 描述 | 取值 |
IV_SYS_RECONNECT_STATUS | 重连状态，表示系统与后台连接断开，并进行重连状态。 | 0 |
IV_SYS_DISCONNECT_STATUS | 离线状态，表示系统与后台连接断开，不会再重连。 | 1 |
IV_SYS_INVALID_STATUS | 无效状态。 | 2 |
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;
参数说明
成员名称 | 描述 | 取值 |
IV_eLOG_DISABLE | 关闭日志输出。 | 0 |
IV_eLOG_ERROR | 只输出错误日志。 | 1 |
IV_eLOG_WARN | 输出告警和错误日志。 | 2 |
IV_eLOG_INFO | 输出告警、错误和信息日志。 | 3 |
IV_eLOG_DEBUG | 输出告警、错误、信息和调试日志。 | 4 |
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;
参数说明
成员名称 | 描述 | 取值 |
dev_cert_file | 设备证书位置，最大长度128。 | 字符串 |
dev_pkey_file | 设备私钥位置，最大长度128。 | 字符串 |
说明：
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;
参数说明
成员名称 | 描述 | 取值 |
product_id | 产品 ID，最大长度10。 | 字符串，必选。 |
device_name | 设备名称，最大长度48。 | 字符串，必选。 |
device_cert | 设备证书认证配置。 | 结构体，可选。 |
device_key | 设备密钥认证时的密钥。 | 字符串， 可选。 |
说明：
证书认证还是密钥认证可根据接
iv_sys_get_certificate_type 判断，两种认证方式是互斥，SDK 只能固定支持一种。示例代码
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 0iv_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;#elsestSysInitParameters.dev_info_path = "./device_info.json";#endifstSysInitParameters.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;}
2. 系统模块退出
int sys_exit(void)