功能介绍
本模块提供 SDK 读写目录,打印 log,设备性能和版本信息初始化,证书读写,设备上线及时间同步。
证书分为初始证书和激活证书,初始证书在生产时烧录进设备,只能激活一次,激活后的激活证书供设备线上功能使用,用户可以通过本模块实现设备初始证书烧写、读取,激活。具体读写方式由用户来实现,SDK 在需要时自行调用。
上线回调会传入服务器时间信息用于同步设备时间,精度为毫秒。
流程指引
系统模块总流程
初始化系统参数、注册读写证书、设备上线回调 > 系统初始化 > 设置当前时区 > 系统去初始化。
上线流程
设备连接服务器成功 > 回调设备上线函数 > 设置系统时间。
接口参考
该功能模块提供以下接口:
iv_sys_init:系统初始化。
iv_sys_exit:系统去初始化。
iv_sys_read_certificate_cb:读证书数据回调。
iv_sys_write_certificate_cb:写证书数据回调。
iv_sys_get_encrypt_lib_path_cb:获取烧写的加密库的绝对路径。
iv_sys_online_cb:设备上线回调函数。
iv_sys_offline_cb:设备离线回调函数。
iv_sys_get_utc_ms:用户自定义获取系统 UTC 时间函数,精确到 ms。
iv_sys_set_timezone:设置系统时区函数。
iv_sys_get_tid:获取设备 Tid。
iv_sys_set_net_interface:设置当前使用的网卡名。
iv_sys_sync_net_time_cb:同步网络时间回调。
iv_sys_get_pid:获取设备所属 Pid。
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_read_certificate_cb
接口描述
读证书数据。用户需要实现读初始证书和激活证书功能,读取加密密钥库路径功能,SDK 需要时回调,注意应用层读取初始化证书和激活证书时返回的是证书内容,读取加密密钥库路径时返回库路径字符串内容。
int (* iv_sys_read_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t *pCertificateLen); |
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
eCertificateType | iv_sys_certificate_type_e | 证书类型。 | 输入 |
pCertificateBuf | char * | 证书数据内容。 | 输出 |
pCertificateLen | uint32_t * | 证书数据长度。 | 输出 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* |
iv_sys_write_certificate_cb
接口描述
写入证书数据。用户需要实现写初始证书、激活证书和加密密钥库功能,SDK 需要时回调。
int (* iv_sys_write_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t u32CertificateLen); |
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
eCertificateType | iv_sys_certificate_type_e | 证书类型。 | 输入 |
pCertificateBuf | char * | 证书数据内容。 | 输入 |
u32CertificateLen | uint32_t | 证书数据长度。 | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 成功。 |
IV_ERR_* |
iv_sys_online_cb
接口描述
设备上线回调,并会带入网络时间参数,用于同步时间,SDK 回调通知用户设备已经上线,用户根据携带的时间信息进行时间同步。
void (* iv_sys_online_cb)(uint64_t u64NetDateTime);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
u64NetDateTime | uint64_t | 网络时间,距1970年毫秒数。 | 输入 |
返回值
返回值 | 描述 |
void | 无返回值。 |
iv_sys_offline_cb
接口描述
IoT Video(Consumer Version) 设备失去与服务器的连接后,通过此回调通知上层。
【声明】
void (* iv_sys_offline_cb)(void);
参数说明
无
返回值
返回值 | 描述 |
void | 无返回值。 |
iv_sys_get_utc_ms
接口描述
用户自定义获取系统 UTC 时间函数,必须精确到毫秒。如果 time(NULL) 获取的是 UTC 时间,可以不用实现该回调。
uint64_t (* iv_sys_get_utc_ms)(void);
参数说明
无
返回值
返回值 | 描述 |
uint64_t | 距1970年毫秒数。 |
iv_sys_sync_net_time_cb
接口描述
1. 网络时间的同步接口,该接口会在上电之后首先进行时间同步并回调,以便于提早设备可用时间点。
2. 设备正常运行后每隔12小时会进行一次时间同步。由于设备的硬件时钟的差异,所以同步的时间和当前设备的时间可能不一致,需要用户根据实际需求决定是否要进行跳变的同步。
void (* iv_sys_sync_net_time_cb)(uint64_t net_time_ms);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
net_time_ms | uint64_t | 网络时间(utc+0 ms)。 | 输入 |
返回值
返回值 | 描述 |
void | 无返回值 |
iv_sys_set_timezone
接口描述
设置设备所运行的时区,如果设备时区设置发生变化,需要调用此函数刷新 SDK 时区。
void iv_sys_set_timezone(float fTimezone);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
fTimezone | float | 时区(取值为标准时区值,-11 - 14)。 | 输入 |
返回值
返回值 | 描述 |
void | 无返回值。 |
iv_sys_get_tid
接口描述
获取设备 Tid。
const char* iv_sys_get_tid(void);
参数说明
无
返回值
返回值 | 描述 |
const char* | 以'\\0'结尾的 tid 字符串。 |
iv_sys_set_net_interface
接口描述
设置设备当前选择使用的网络接口名。
int iv_sys_set_net_interface(char* net_name);
参数说明
参数名称 | 类型 | 描述 | 输入/输出 |
net_name | char* | 网络接口名(eg:"eth0") | 输入 |
返回值
返回值 | 描述 |
IV_ERR_NONE | 无错误。 |
IV_ERR_CM_PARAM_OUT_RANGE | 传入网口名过长(>31)。 |
iv_sys_get_pid
接口描述
获取设备所属的产品 ID。
const iv_sys_device_pid_st* iv_sys_get_pid(void);
参数说明
无
返回值
返回值 | 描述 |
iv_sys_device_pid_st | 包含物模型 Pid 和证书 Pid。 |
数据结构
SDK 系统模块提供以下数据结构:
iv_sys_init_parm_s:系统初始化参数结构体。
iv_sys_certificate_type_e:证书类型枚举。
iv_sys_device_ability_e:设备内存性能枚举。
iv_sys_firmware_version_s:固件版本结构体。
iv_sys_device_pid_st: 设备 Pid 结构体。
iv_sys_device_online_result_e:设备上线结果枚举。
iv_sys_device_bind_action_e:设备绑定通知枚举。
iv_sys_init_parm_s
接口描述
系统初始化参数结构体。
typedef struct iv_sys_init_parm_s{char s8PubStorePath[64];char s8PubCachePath[64];uint32_t u32DebugMode;uint32_t u32SupportAvChnMax;iv_sys_device_ability_e eDeviceAbility;iv_sys_firmware_version_s stFirmwareVersion;uint32_t need_sync_net_time;uint32_t net_chn_ring_buff_size;uint32_t (* iv_sys_read_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t *pCertificateLen);uint32_t (* iv_sys_write_certificate_cb)(iv_sys_certificate_type_e eCertificateType, char *pCertificateBuf, uint32_t u32CertificateLen);void (* iv_sys_online_cb)(uint64_t u64NetDateTime);void (* iv_sys_offline_cb)(void);uint64_t (* iv_sys_get_utc_ms)(void);void (*iv_sys_sync_net_time_cb)(uint64_t net_time_ms);}iv_sys_init_parm_s;
参数说明
成员名称 | 描述 | 取值 |
s8PubStorePath | 可读写目录,存储重要文件,断电不会丢失。 | 字符串,必须设置。 |
s8PubCachePath | 可读写目录(缓存目录),存储缓存文件,断电可以丢失。 | 字符串,必须设置。 |
u32DebugMode | 已废弃,更新为 iv_cm_set_log_level 接口进行控制。 | 0:关闭。 1:开启。 |
u32SupportAvChnMax | 支持音视频同时的最大通道数。 | 视设备的 CPU 及内存情况及用户需要而定。 |
eDeviceAbility | 设备性能。 | iv_sys_device_ability_e |
stFirmwareVersion | 设备固件版本号。 | iv_sys_firmware_version_s |
need_sync_net_time | 是否需要网络时间同步(设备不具备本地实时时钟系统)。 | 0:不需要。 1:需要。 |
net_chn_ring_buff_size | 网络传输缓冲区大小。 | 该值决定传输音视频数据时抗网络波动的能力。 建议为数据大小 × 缓存时间。不填缺省为512*1024。 |
iv_sys_read_certificate_cb | 读证书回调函数。 | 必须注册。 |
iv_sys_write_certificate_cb | 写证书回调函数。 | 必须注册。 |
iv_sys_online_cb | 设备上线回调函数。 | 必须注册。 |
iv_sys_offline_cb | 设备离线回调函数。 | - |
iv_sys_get_utc_ms | 用户自定义获取系统,UTC 时间。 | 当 time(NULL) 提供时间并未非 UTC0 时间时需要注册,用于提供 SDK 准确的 UTC0 时间。 |
iv_sys_sync_net_time_cb | 设备同步网络时间。 | - |
iv_sys_certificate_type_e
接口描述
证书类型枚举。
typedef enum{IV_SYS_CERTIFICATE_TYPE_INITIAL = 0,IV_SYS_CERTIFICATE_TYPE_ACTIVED = 1,IV_SYS_CERTIFICATE_TYPE_SECERT_KEY = 2,IV_SYS_CERTIFICATE_TYPE_BUTT}iv_sys_certificate_type_e;
参数说明
成员名称 | 描述 | 取值 |
IV_SYS_CERTIFICATE_TYPE_INITIAL | 初始证书 | - |
IV_SYS_CERTIFICATE_TYPE_ACTIVED | 激活证书 | - |
IV_SYS_CERTIFICATE_TYPE_SECERT_KEY | 证书密钥,一个 so 文件 | - |
iv_sys_device_ability_e
接口描述
设备性能枚举。
typedef enum{IV_SYS_DEVICE_ABILITY_POOR = 0,IV_SYS_DEVICE_ABILITY_ORDINARY = 1,IV_SYS_DEVICE_ABILITY_RICH = 2,IV_SYS_DEVICE_ABILITY_BUTT}iv_sys_device_ability_e;
参数说明
成员名称 | 描述 | 取值 |
IV_SYS_DEVICE_ABILITY_POOR | 内存较少 | - |
IV_SYS_DEVICE_ABILITY_ORDINARY | 内存一般 | - |
IV_SYS_DEVICE_ABILITY_RICH | 内存富余 | - |
iv_sys_firmware_version_s
接口描述
固件版本结构体。
typedef struct iv_sys_firmware_version_s{uint32_t revision:19;uint32_t minor:6;uint32_t major:6;uint32_t debug:1;} iv_sys_firmware_version_s;
参数说明
成员名称 | 描述 | 取值 |
revision | 流水号 | 19位 |
minor | 主版本号 | 6位 |
major | 次版本号 | 6位 |
debug | 测试版本标志。 0:调试固件。 1:正式固件。 | 1位 |
iv_sys_device_pid_st
设备 pid 结构体。
typedef struct iv_sys_device_pid_st{char dm_pid[33];char cert_pid[33];}iv_sys_device_pid_st;
参数说明
成员名称 | 描述 | 取值 |
dm_pid | 1. 物模型 PID。 2. 在调用 iv_dm_init 之后才可用,之前都是"0"。 | - |
cert_pid | 1. 证书 PID。 2. 在调用 iv_sys_init 之后才可用,之前都是"0"。 | - |
iv_sys_device_online_result_e
设备上线状态枚举。
说明:
该状态属于 SDK 通知状态不可查询。
typedef enum{IV_SYS_DEVICE_ONLINE_NONE = 0,IV_SYS_DEVICE_ONLINE = 1,IV_SYS_DEVICE_OFFLINE = 2,IV_SYS_DEVICE_TOKEN_FAIL = 3,IV_SYS_DEVICE_TID_INIT_FAIL = 4,IV_SYS_DEVICE_TID_VALIDATE_FAIL = 5,IV_SYS_DEVICE_KICK_OFF = 6,IV_SYS_DEVICE_DEV_DISABLE = 7,IV_SYS_DEVICE_PID_MISMATCH = 8,IV_SYS_DEVICE_CERTIFY_CHECK_OK = 9,IV_SYS_DEVICE_TID_CHECK_OK = 10,} iv_sys_device_online_result_e;
参数说明
成员名称 | 描述 | 取值 |
IV_SYS_DEVICE_ONLINE_NONE | 正常情况,无需处理该状态。 | 0 |
IV_SYS_DEVICE_ONLINE | 正常情况,设备已上线。 | 1 |
IV_SYS_DEVICE_OFFLINE | 正常情况,设备已离线。 | 2 |
IV_SYS_DEVICE_TOKEN_FAIL | 异常情况,设备 Token 校验失败,证书异常,设备环境异常。 | 3 |
IV_SYS_DEVICE_TID_INIT_FAIL | 异常情况,Tid 初始化失败,加密密钥库不匹配或初始化失败。 | 4 |
IV_SYS_DEVICE_TID_VALIDATE_FAIL | 异常情况,证书和加密密钥库不匹配。 | 5 |
IV_SYS_DEVICE_KICK_OFF | 异常情况,设备被踢飞。 | 6 |
IV_SYS_DEVICE_DEV_DISABLE | 正常情况,设备被禁用。 | 7 |
IV_SYS_DEVICE_PID_MISMATCH | 异常情况,物模型和证书不匹配,不属于同一产品。 | 8 |
IV_SYS_DEVICE_CERTIFY_CHECK_OK | 正常情况,证书校验成功。 | 9 |
IV_SYS_DEVICE_TID_CHECK_OK | 正常情况,Tid 校验成功。 | 10 |
iv_sys_device_bind_action_e
设备被绑定、解绑的操作类型枚举。
typedef enum iv_sys_device_bind_action{IV_SYS_DEIVCE_BIND_NONE = 0,IV_SYS_DEIVCE_BIND_OWNER = 1,IV_SYS_DEIVCE_UNBIND_OWNER = 2,} iv_sys_device_bind_action_e;
参数说明
成员名称 | 描述 | 取值 |
IV_SYS_DEIVCE_BIND_NONE | 设备处于无绑定动作发生的状态,无需处理该状态。 | 0 |
IV_SYS_DEIVCE_BIND_OWNER | 设备被主人绑定的操作。 | 1 |
IV_SYS_DEIVCE_UNBIND_OWNER | 设备被主人解绑的操作。 | 2 |
示例代码
1. 系统初始化,设置时区
iv_sys_set_net_interface("eth0");iv_err_code_e eErrCode = 0;iv_sys_init_parm_s stSysInitParameters;char s8FirmwareVersion[32] = {0};memset(&stSysInitParameters, 0, sizeof(iv_sys_init_parm_s));char app_version_file[256] = {0};FILE *fpFirmwareVersion = NULL;snprintf(app_version_file, sizeof(app_version_file), "%s/version", config_get_app_ver_file_path());/* 获取版本号 */fpFirmwareVersion = fopen(app_version_file, "r");if(fpFirmwareVersion){fread(s8FirmwareVersion, 32, 1, fpFirmwareVersion);fclose(fpFirmwareVersion);}else{GDB_ERR("open version file '%s' failed!\\n", app_version_file);strcpy(s8FirmwareVersion, "1.0.0");}char *pVersion = NULL;char s8RealVersion[4][32];int s32VersionType = 0;pVersion = strtok(s8FirmwareVersion, ".");while(pVersion){strcpy(s8RealVersion[s32VersionType], pVersion);GDB_INFO("version:%s\\n", s8RealVersion[s32VersionType]);s32VersionType++;pVersion = strtok(NULL, ".");}stSysInitParameters.stFirmwareVersion.major = atoi(s8RealVersion[0]);stSysInitParameters.stFirmwareVersion.minor = atoi(s8RealVersion[1]);stSysInitParameters.stFirmwareVersion.revision = atoi(s8RealVersion[2]);if(strcmp(s8RealVersion[3], "release") == 0){stSysInitParameters.stFirmwareVersion.debug = 0;}else if(strcmp(s8RealVersion[3], "debug") == 0){stSysInitParameters.stFirmwareVersion.debug = 1;}GDB_INFO("app version major:%d, minor:%d, revision:%d,debug:%d\\n", stSysInitParameters.stFirmwareVersion.major, stSysInitParameters.stFirmwareVersion.minor, stSysInitParameters.stFirmwareVersion.revision, stSysInitParameters.stFirmwareVersion.debug);strcpy(stSysInitParameters.s8PubStorePath, config_get_perm_rw_path());strcpy(stSysInitParameters.s8PubCachePath, config_get_temp_rw_path());stSysInitParameters.u32DebugMode = 1;stSysInitParameters.u32SupportAvChnMax = 4;stSysInitParameters.eDeviceAbility = IV_SYS_DEVICE_ABILITY_ORDINARY;stSysInitParameters.iv_sys_read_certificate_cb = sys_read_certificate;stSysInitParameters.iv_sys_write_certificate_cb = sys_write_certificate;stSysInitParameters.iv_sys_online_cb = sys_online;stSysInitParameters.iv_sys_offline_cb = sys_offline;stSysInitParameters.iv_sys_sync_net_time_cb = sys_sync_net_time;eErrCode = iv_sys_init(&stSysInitParameters);if(eErrCode < 0){GDB_ERR("fail:%d\\n", eErrCode);return eErrCode;}/*北京时间+8 时区*/iv_sys_set_timezone(8);
2. 系统退出
iv_sys_exit();