网关API使用说明

更新时间:2018-07-04 14:11:45

结构体

linkkit_event_t

typedef struct {
    int event_type; /* see LINKKIT_EVENT_XXX for more details */

    union {
        struct {
            char *productKey;
            char *deviceName;
        } subdev_deleted;

        struct {
            char *productKey;
            int   timeoutSec;
        } subdev_permited;

        struct {
            char *subdevList;
        } subdev_setup;

        struct {
            char *productKey;
            char *deviceName;
        } reset_success;
    } event_data;
} linkkit_event_t;

linkkit_event_t用于表示网关SDK内部事件,包括以下成员:

  • event_type:事件类型,支持的事件类型如下表所示:
事件类型
说明
LINKKIT_EVENT_CLOUD_DISCONNECTED
设备断开阿里IoT云
LINKKIT_EVENT_CLOUD_CONNECTED
设备连接上阿里IoT云。在连上IoT云时,应该post设备的所有属性,确保云端的影子设备与设备端同步
LINKKIT_EVENT_SUBDEV_DELETED
云端删除子设备,删除的子设备由event_data的subdev_deleted指定
LINKKIT_EVENT_SUBDEV_PERMITED
允许zigbee子设备接入网关。允许接入网关的子设备由event_data的subdev_permited指定,如果product Key为NULL,则允许所有子设备接入,如果productKey不为NULL,则只允许productKey为对应值的子设备接入。timeoutSec为允许子设备接入的时间窗口。如果timeoutSec为0,则禁止子设备接入。
LINKKIT_EVENT_SUBDEV_SETUP
ZigBee网关置换专用,用户在APP端触发网关置换请求,云端通过属性设置接口设置ZigBee网络参数到新的网关,再从云端同步被置换网关子设备信息到新的网关,subdevList json字符串格式:[{"productKey":"","deviceName":""},...]
LINKKIT_EVENT_RESET_SUCCESS
设备复位成功,复位成功的设备由event_data的reset_success指定
  • event_data:event_type指定的事件对应的事件数据。

linkkit_cbs_t

typedef struct {
    int (*get_property)(char *in, char *out, int out_len, void *ctx);
    int (*set_property)(char *in, void *ctx);
    int (*call_service)(char *identifier, char *in, char *out, int out_len, void *ctx);

    int (*down_rawdata)(const void *in, int in_len, void *out, int out_len, void *ctx);
    int (*post_rawdata_reply)(const void *data, int len, void *ctx);
} linkkit_cbs_t;

linkkit_cbs_t用于linkkit_gateway_start()linkkit_gateway_subdev_create(),定义了设备支持的一组操作,包含以下回调函数:

  • get_property: 云端用于获取设备或网关的各种属性,in为输入参数,为json数组,out为输出参数,是以'\0'结尾的json对象,out_len为out字符串的长度,out_len的大小与LINKKIT_OPT_MAX_MSG_SIZE指定的最大消息大小相同。ctx为用户私有数据。如果用户需要获取灯的WorkMode和Brightness两个属性,且WorkMode为1,Brightness为70%,则get_property的in参数为["WorkMode", "Brightness"],out为:{ "WorkMode": 1, "Brightness": 70}

  • set_property: 云端用于设置网关或子设备的各种属性,in为输入参数,为json对象,ctx为用户私有数据。如果用户想要设置的灯的WorkMode属性为2,Brightness属性为85,则in为{"WorkMode": 2,"Brightness": 85}

  • call_service: 云端调用子设备服务,identifier为服务名称,in为服务的输入参数,为json对象,out为服务的输出参数,是以'\0'结尾的json对象,out_len为out字符串的长度,ctx为用户私有数据。如果云端想调用灯的SetLightSwitch这个服务,则identifier为SetLightSwitch,in参数为{"LightSwitch": 1},out参数为{"Brightness":75}

  • down_rawdata: 云端用于向IoT设备下发裸数据,in为云端下发数据,in_len为in的字节长度,out为网关SDK内部分配的存储空间,用于填充用户的返回数据,out_len为out的字节长度,ctx为用户私有数据,回调的返回值为out的实际长度;

  • post_rawdata_reply: 云端返回用户调用linkkit_gateway_post_rawdata后的响应数据,data为数据,len为data的长度;

注意:linkkit_cbs_t中的down_rawdatapost_rawdata_reply两个回调功能暂不开放。

获取默认参数

linkkit_params_t *linkkit_gateway_get_default_params(void);

获取默认参数,在调用linkkit_gateway_init()时作为参数传入,用于初始化网关SDK。

修改默认参数

int linkkit_gateway_set_option(linkkit_params_t *params, int option, void *value, int value_len);

linkkit_gateway_get_default_params()返回的默认参数进行修改,支持的option包括如下:

enum {
    LINKKIT_OPT_MAX_MSG_SIZE       = 1,
    LINKKIT_OPT_MAX_MSG_QUEUE_SIZE = 2,
    LINKKIT_OPT_THREAD_POOL_SIZE   = 3,
    LINKKIT_OPT_THREAD_STACK_SIZE  = 4,
    LINKKIT_OPT_LOG_LEVEL          = 5
};

option的值类型和取值范围如下表所示:

option
说明
值类型
默认值
取值范围
LINKKIT_OPT_MAX_MSG_SIZE
设置最大消息长度
int
20480
512 - 51200
LINKKIT_OPT_MAX_MSG_QUEUE_SIZE
设置消息队列长度
int
16
2 - 32
LINKKIT_OPT_THREAD_POOL_SIZE
用于处理消息的线程池线程数,用户注册的回调会在线程池中调用
int
4
1 - 16
LINKKIT_OPT_THREAD_STACK_SIZE
线程池的线程栈栈大小
int
8192
1024-8388608
LINKKIT_OPT_LOG_LEVEL
日志打印等级,支持的日志等级包括:
  • 0 - Emergency;
  • 1 - Critical;
  • 2 - Error;
  • 3 - Warnning;
  • 4 - Info;
  • 5 - Debug
int
4
0-5

注册事件回调

int linkkit_gateway_set_event_callback(linkkit_params_t *params, int (*event_cb)(linkkit_event_t *ev, void *ctx), void *ctx);

该函数用于注册用户事件回调,包括以下参数:

  • params:linkkit_gateway_get_default_params()返回的默认参数;

  • event_cb:事件回调,linkkit内部事件会通过event_cb回调给用户;

  • ctx:用户私有数据,在linkkit在调用event_cb时会传该event_cb;

event_cb包含以下参数:

  • ev:事件结构体,详见linkkit_event_t;

  • ctx:用户私有数据;

网关SDK初始化

int linkkit_gateway_init(linkkit_params_t *initParams);

用于分配和初始化linkkit的内部资源。

网关SDK反初始化

int linkkit_gateway_exit(void);

用于销毁和回收内部资源。在调用linkkit_gateway_exit()前,应该先销毁网关设备和所有子设备;

启动网关设备

int linkkit_gateway_start(linkkit_cbs_t *cbs, void *ctx);

用于创建网关设备,注册网关相关回调函数,同时启动linkkit服务,与云端建立。该函数有两个输入参数,cbs为设备操作相关的一组函数指针,ctx为用户私有数据。

linkkit_gateway_start()创建网关设备成功则返回大于0的设备id,创建失败则返回小于0的错误码。

停止网关设备

int linkkit_gateway_stop(int devid);

断开与云端的连接,停止网关SDK服务。

网关绑定子设备

int linkkit_gateway_subdev_register(char *productKey, char *deviceName, char *deviceSecret);

将productKey、deviceName和deviceSecret指定的子设备绑定到网关,将子设备添加到网关的拓扑中。

网关解绑子设备

int linkkit_gateway_subdev_unregister(char *productKey, char *deviceName);

解除网关与productKey、deviceName指定的子设备之间的绑定,删除网关与子设备的拓扑关系;

创建子设备

int linkkit_gateway_subdev_create(char *productKey, char *deviceName, linkkit_cbs_t *cbs, void *ctx);

创建子设备,注册子设备相关的回调和用户数据。linkkit_gateway_subdev_create()调用成功会返回子设备的devid(设备id),devid为大于0的整数,小于0为错误码。

删除子设备

int linkkit_gateway_subdev_destroy(int devid);

删除子设备,释放子设备相关的资源。

子设备login

int linkkit_gateway_subdev_login(int devid);

子设备登录,返回值等于0代表login成功,云端设备控制台会显示设备在线,小于0代表login失败。

子设备logout

int linkkit_gateway_subdev_logout(int devid);

子设备登出,等于0代表子设备logout成功,云端控制台显示设备离线,小于0代表logout失败。

事件上报

同步接口

int linkkit_gateway_trigger_event_json_sync(int devid, char *identifer, char *event, int timeout);

用于上报网关或子设备的事件到云端,包括以下参数:

  • devid: 设备ID;

  • identifer: 输入参数,事件标识,由TSL文档定义;

  • event: 输入参数,待上报事件对应的数据,使用json格式表示,形如{"errorCode": 1},以'\0'结尾;

  • timeout:同步等待云端响应的超时时间,以毫秒为单位,为0则不等待云端响应;

异步接口

int linkkit_gateway_trigger_event_json(int devid, char *identifier, char *json, int timeout_ms, void (*func)(int retval, void *ctx), void *ctx);

用于上报网关或子设备的事件到云端,包括以下参数:

  • devid: 设备ID;

  • identifer: 输入参数,事件标识,由TSL文档定义;

  • event: 输入参数,待上报事件对应的数据,使用json格式表示,形如{"errorCode": 1},以'\0'结尾;

  • timeout:同步等待云端响应的超时时间,以毫秒为单位,为0则不等待云端响应;

  • cb:接口调用失败或成功时调用的回调函数,retval = 0表示超时,retval < 0表示云端响应错误,retval = 1表示成功;

  • ctx:传递给cb的用户私有数据;

属性上报

同步接口

int linkkit_gateway_post_property_json_sync(int devid,char *property, int timeout);

用于网关或子设备主动上报属性到云端,该接口包括以下参数:

  • devid: 设备ID;

  • property: 输入参数,属性值,使用json格式表示,形如{"WorkMode": 1, "LightSwitch": 0},以'\0'结尾;

  • timeout:同步等待云端响应的超时时间,以毫秒为单位,为0则不等待云端响应。

异步接口

int linkkit_gateway_post_property_json(int devid, char *json, int timeout_ms, void (*func)(int retval, void *ctx), void *ctx);

用于网关或子设备主动上报属性到云端,该接口包括以下参数:

  • devid: 设备ID;

  • property: 输入参数,属性值,使用json格式表示,形如{"WorkMode": 1, "LightSwitch": 0},以'\0'结尾;

  • timeout:云端响应的超时时间,以毫秒为单位,为0则不等待云端响应;

  • cb:接口调用失败或成功时调用的回调函数,retval = 0表示超时,retval < 0表示云端响应错误,retval = 1表示成功;

  • ctx:传递给cb的用户私有数据;

上传raw data

int linkkit_gateway_post_rawdata(int devid, void *data, int len);

用户上传网关或子设备的裸数据,其中:

  • devid:设备ID。该接口既可以用于网关,也可以用于子设备向云端发送事件;

  • data:裸数据;

  • len:裸数据长度;

扩展信息上报

typedef struct {
    char *attrKey;    /* the key of extend info. */
    char *attrValue;  /* the value of extend info. */
} linkkit_extinfo_t;

int linkkit_gateway_post_extinfos(int devid, linkkit_extinfo_t *extinfos, int nb_extinfos, int timeout_ms);

扩展信息上报:

  • devid:设备ID;

  • extinfos:扩展信息数组;

  • nb_extinfos:extinfos的数量;

  • timeout_ms:同步等待云端响应的超时时间,以毫秒为单位,为0则不等待云端响应。

删除扩展信息

int linkkit_gateway_delete_extinfos(int devid, linkkit_extinfo_t *extinfos, int nb_extinfos, int timeout_ms);

删除扩展信息:

  • devid: 设备ID;

  • extinfos:扩展信息数组,忽略linkkit_extinfo_t中的attrValue;

  • nb_extinfos:extinfos的数量;

  • timeout_ms:同步等待云端响应的超时时间,以毫秒为单位,为0则不等待云端响应。

获取设备信息

设备信息用于表示设备的当前状态,设备信息用linkkit_devinfo_t表示。linkkit_devinfo_t的声明如下所示:

enum {
    LINKKIT_STATE_ENABLED  = 0, /* device is enabled by cloud  */
    LINKKIT_STATE_DISABLED,     /* device is disabled by cloud */
    LINKKIT_STATE_REMOVED,      /* device is deleted by cloud  */
};

typedef struct {
    char *productKey;   /* device's product key */
    char *deviceName;   /* device's device name */

    int   devtype;      /* Device Type: 0 - gateway, 1 - subdev */
    int   login;        /* Login State: 0 - logout,  1 - login  */
    int   state;        /* Device State: see LINKKIT_STATE_xxx  */
    int   online;       /* 0 - offline, 1 - online              */
} linkkit_devinfo_t;

linkkit_devinfo_t包括以下成员:

  • productKey:设备标识三元组中的productKey;

  • deviceName:设备标识三元组中的deviceName;

  • d​evtype:设备类型,0为网关,1为子设备;

  • login:设备是否已经登录,0为未登录,1为已经登录;

  • state:设备状态,当前包括以下三个状态:

    • LINKKIT_STATE_ENABLED:设备未被禁用;
    • LINKKIT_STATE_DISABLED:设备被禁用;
    • LINKKIT_STATE_REMOVED:设备已被云端删除;
  • online:设备是否在线,0为不在线,1为在线。

获取单个设备信息

以下接口用户获取单个设备信息:

int linkkit_gateway_get_devinfo(int devid, linkkit_devinfo_t *devinfo);

该接口对应的参数如下所示:

  • devid:设备ID;

  • devinfo:设备信息结构体,详见linkkit_devinfo_t;

以下接口用于获取多个设备信息:

int linkkit_gateway_get_num_devices(void);
int linkkit_gateway_get_devinfos(linkkit_devinfo_t *devinfos, int nb_devinfos);

其中linkkit_get_num_devices()用于获取已经注册到SDK中的总设备个数,linkkit_gateway_get_devinfos()用户获取设备信息列表。linkkit_gateway_get_devinfos()包含两个参数,其中devinfos为linkkit_devinfo_t数组,用于保存获取到的设备信息列表,nb_devinfos代表devinfos数组的长度,linkkit_gateway_get_devinfos()返回值为实际返回的设备信息个数。

设备复位

设备复位接口如下所示:

int linkkit_gateway_reset(int devid);

其中输入参数devid可以为网关的devid,也可以为设备devid。如果linkkit_gateway_reset()的输入参数为网关的devid,该接口将删除网关和子设备的绑定关系,同时也会在云端删除该网关的所有用户数据。如果linkkit_gateway_reset()的输入参数为子设备的devid,则会解除该子设备和网关的绑定关系,同时删除云端中与该子设备相关的用户数据。

linkkit_gateway_reset()返回值如下所示:

  • 等于0:接口调用成功;

  • 等于1:接口由于网络超时或断网等原因调用出错,网关SDK会在内部重新进行reset,直到reset成功为止,reset成功时会通过LINKKIT_EVENT_RESET_SUCCESS事件通知用户;

  • 小于0:接口调用失败。

设备升级

网关SDK的OTA服务仅限于将云端的升级包下载到本地,并对升级包进行校验,并不会对设备进行升级,具体的升级操作需要用户完成。

FOTA服务初始化

FOTA服务使用以下接口进行初始化:

int linkkit_ota_service_init(const linkkit_ota_params *ota_params);

其中ota_params为linkkit_ota_service_init()的初始化参数,该参数声明如下所示:

typedef struct {
    int   (*get_firmware_version)(const char *productKey, const char *deviceName, char *version, int buff_len);
    void *(*start)(const char *productKey, const char *deviceName, const char *new_version, int file_size);
    int   (*write)(void *handle, unsigned char *data, int data_len);
    int   (*stop) (void *handle, int err);
} linkkit_ota_params;

linkkit_ota_params中各成员说明如下:

  • get_firmware_version: 用于获取指定productKey和deviceName对应的设备的当前版本号,设备上线时会调用该接口告知云端当前设备的版本号。get_firmware_version回调的参数说明如下:

    • productKey: 待升级设备对应的productKey;
    • deviceName: 待升级设备对应的deviceName;
    • version: 用于保存用户返回的版本号;
    • buff_len: version对应的buffer的字节大小;
  • start: 云端触发升级时首先会调用该回调,用于通知用户productKey和deviceName对应的设备有新的设备升级请求。该回调的返回值为用户分配的,用于保存此次升级上下文的私有数据。start回调的参数说明如下:

    • productKey: 待升级设备对应的productKey;
    • deviceName: 待升级设备对应的deviceName;
    • new_version: 新固件升级包的版本号;
    • file_size: 固件的字节大小。
  • write: 云端下发的升级包会分成多个片段,该回调用于保存云端下发的固件升级包片段。write回调的参数说明如下:

    • handle: 由start回调返回的用于保存该次升级的上下文信息;
    • data: 云端下发的固件升级包片段;
    • data_len: 升级包片段的长度;
  • stop: 升级包下发完成。stop回调的参数说明如下:

    • handle: 由start回调返回的用于保存该次升级的上下文信息;
    • err: 用于标识升级包下载是否出错,支持的错误码如下所示。
错误码 说明
OTA_UPGRADE_ERROR_NONE 没有错误
OTA_UPGRADE_ERROR_CONNECT 连接服务器失败
OTA_UPGRADE_ERROR_DOWNLOAD 下载失败
OTA_UPGRADE_ERROR_WRITE 写数据失败
OTA_UPGRADE_ERROR_CHECKSUM 升级包校验出错
OTA_UPGRADE_ERROR_CANCEL 升级被取消

注意:只有在调用linkkit_gateway_init()之后才能够调用linkkit_ota_service_init()初始化FOTA服务。

FOTA服务反初始化

FOTA服务使用以下接口进行初始化:

int linkkit_ota_service_deinit(void);

调用该接口后,网关SDK不会对云端的升级请求进行响应和处理。

主动上报设备版本号

用户可以调用以下接口主动上报设备的版本号:

int linkkit_ota_report_version(const char *productKey, const char *deviceName, const char *version);

其中productKey和deviceName为设备的标识信息,version为设备的当前版本号。

results matching ""

    No results matching ""