Alink协议是针对物联网开发领域设计的一种数据交换规范,数据格式是JSON,用于设备端和物联网平台的双向通信。本文介绍Alink协议涉及的API。

说明

JSON报文中,消息ID的取值范围是0~4294967295,ID是String类型的数字,如"12345"。

IOT_Linkkit_Open

  • 接口原型

    int IOT_Linkkit_Open(iotx_linkkit_dev_type_t dev_type, iotx_linkkit_dev_meta_info_t *meta_info);
  • 接口说明

    初始化设备资源,在对设备进行操作之前,必须先调用此接口,调用成功后会返回设备ID。

    当使用其他接口时需要以设备ID作为入参,对指定的设备进行操作。

  • 参数说明

    参数

    数据类型

    方向

    说明

    dev_type

    iotx_linkkit_dev_type_t

    输入

    需要创建资源的设备类型。

    meta_info

    iotx_linkkit_dev_meta_info_t

    输入

    设备证书。

  • 参数附加说明

    typedef enum {
        IOTX_LINKKIT_DEV_TYPE_MASTER,
        IOTX_LINKKIT_DEV_TYPE_SLAVE,
        IOTX_LINKKIT_DEV_TYPE_MAX
    } iotx_linkkit_dev_type_t;

    参数

    说明

    IOTX_LINKKIT_DEV_TYPE_MASTER

    创建的设备为主设备,仅能创建一次。

    IOTX_LINKKIT_DEV_TYPE_SLAVE

    创建的设备为子设备。

    IOTX_LINKKIT_DEV_TYPE_MAX

    设备类型最大枚举值。

    typedef struct {
        char product_key[PRODUCT_KEY_MAXLEN];
        char product_secret[PRODUCT_SECRET_MAXLEN];
        char device_name[DEVICE_NAME_MAXLEN];
        char device_secret[DEVICE_SECRET_MAXLEN];
    } iotx_linkkit_dev_meta_info_t;

    参数

    说明

    product_key

    产品标识,最大长度为20字节。

    product_secret

    产品密钥,最大长度为64字节。

    device_name

    设备名称,最大长度为32字节。

    device_secret

    设备密钥,最大长度为64字节。

  • 返回值说明

    说明

    >= 0

    创建设备成功。

    < 0

    创建设备失败。

IOT_Linkkit_Connect

  • 接口原型

    int IOT_Linkkit_Connect(int devid);
  • 接口说明

    • 对于主设备来说,将会建立设备与云端的通信。

    • 对于子设备来说,将向云端注册该子设备(如果需要的话)并添加主、子设备的拓扑关系。

  • 参数说明

    参数

    数据类型

    方向

    说明

    devid

    int

    输入

    设备ID。

  • 返回值说明

    说明

    0

    成功。

    < 0

    失败。

IOT_Linkkit_Yield

  • 接口原型

    void IOT_Linkkit_Yield(int timeout_ms);
  • 接口说明

    若SDK占有独立线程,则该函数只将接收到的网络报文分发到用户的回调函数中,否则表示将CPU交给SDK让其接收网络报文并将消息分发到用户的回调函数中。

  • 参数说明

    参数

    数据类型

    方向

    说明

    timeout_ms

    int

    输入

    单线程模式下,每次尝试接收网络报文的超时时间。

  • 返回值说明

    无返回值。

IOT_Linkkit_Close

  • 接口原型

    int IOT_Linkkit_Close(int devid);
  • 接口说明

    • 若设备ID为主设备,则关闭网络连接并释放Linkkit所有占用资源。

    • 若设备ID为子设备,则子设备与云平台断开连接。

  • 参数说明

    参数

    数据类型

    方向

    说明

    devid

    int

    输入

    设备ID。

  • 返回值说明

    说明

    0

    成功。

    < 0

    失败。

IOT_Linkkit_TriggerEvent

  • 接口原型

    int IOT_Linkkit_TriggerEvent(int devid, char *eventid, int eventid_len, char *payload, int payload_len);
  • 接口说明

    向云端上报设备事件。

  • 参数说明

    参数

    数据类型

    方向

    说明

    devid

    int

    输入

    设备ID。

    eventid

    char *

    输入

    TSL中定义的事件ID。

    eventid_len

    int

    输入

    事件ID的长度。

    payload

    char *

    输入

    事件Payload。

    payload_len

    int

    输入

    事件Payload的长度。

  • 返回值说明

    说明

    >= 1

    消息ID

    < 0

    失败

IOT_Linkkit_Report

  • 接口原型

    int IOT_Linkkit_Report(int devid,
                            iotx_linkkit_msg_type_t msg_type,
                            unsigned char *payload,
                            int payload_len);
  • 接口说明

    向云端发送消息,包括属性上报、设备标签信息更新上报、设备标签信息删除上报、透传数据上报、子设备登录、子设备登出。

  • 参数说明

    参数

    数据类型

    方向

    说明

    devid

    int

    输入

    设备ID。

    msg_type

    iotx_linkkit_msg_type_t

    输入

    需要上报的消息类型。

    payload

    unsigned char *

    输入

    消息Payload。

    payload_len

    int

    输入

    消息Payload的长度。

  • 参数附加说明

    typedef enum {
        ITM_MSG_POST_PROPERTY,
        ITM_MSG_DEVICEINFO_UPDATE,
        ITM_MSG_DEVICEINFO_DELETE,
        ITM_MSG_POST_RAW_DATA,
        ITM_MSG_LOGIN,
        ITM_MSG_LOGOUT,
        ...
        ...
    
        IOTX_LINKKIT_MSG_MAX
    } iotx_linkkit_msg_type_t;

    参数

    说明

    ITM_MSG_POST_PROPERTY

    设备属性数据上报。

    ITM_MSG_DEVICEINFO_UPDATE

    设备标签更新信息上报。

    ITM_MSG_DEVICEINFO_DELETE

    设备标签删除信息上报。

    ITM_MSG_POST_RAW_DATA

    设备透传数据上报。

    ITM_MSG_LOGIN

    子设备登录。

    ITM_MSG_LOGOUT

    子设备退出。

    ITM_MSG_DELETE_TOPO

    删除子设备和网关之间的拓扑关系。

    ITM_MSG_REPORT_SUBDEV_FIRMWARE_VERSION

    上报子设备的固件版本号,用于子设备OTA升级功能。

    ITM_MSG_PROPERTY_DESIRED_GET

    获取云端缓存的属性值下发,用于高级版设备影子。

    ITM_MSG_PROPERTY_DESIRED_DELETE

    主动删除云端缓存的属性值,用于高级版设备影子。

  • 返回值说明

    说明

    0

    成功。

    >= 1

    消息ID。

    < 0

    失败。

IOT_Linkkit_Query

  • 接口原型

    int IOT_Linkkit_Query(int devid,
                            iotx_linkkit_msg_type_t msg_type,
                            unsigned char *payload,
                            int payload_len);
  • 接口说明

    向云端查询数据,包括查询时间戳、设备的拓扑关系列表、COTA升级的固件数据、COTA升级的Config文件数据、是否有可用的新固件、是否有可用的Config文件。

  • 参数说明

    参数

    数据类型

    方向

    说明

    devid

    int

    输入

    设备ID。

    msg_type

    iotx_linkkit_msg_type_t

    输入

    需要上报的消息类型。

    payload

    unsigned char *

    输入

    消息Payload。

    payload_len

    int

    输入

    消息Payload的长度。

  • 参数附加说明

    typedef enum {
        ...
        ...
        ITM_MSG_QUERY_TIMESTAMP,
        ITM_MSG_QUERY_TOPOLIST,
        ITM_MSG_QUERY_FOTA_DATA,
        ITM_MSG_QUERY_COTA_DATA,
        ITM_MSG_REQUEST_COTA,
        ITM_MSG_REQUEST_FOTA_IMAGE,
    
        IOTX_LINKKIT_MSG_MAX
    } iotx_linkkit_msg_type_t;

    参数

    说明

    ITM_MSG_QUERY_TIMESTAMP

    查询时间戳。

    ITM_MSG_QUERY_TOPOLIST

    查询设备的拓扑关系列表。

    ITM_MSG_QUERY_FOTA_DATA

    查询FOTA升级的固件数据。

    ITM_MSG_QUERY_COTA_DATA

    查询COTA升级的远程配置数据。

    ITM_MSG_REQUEST_FOTA_IMAGE

    查询是否有可用的新固件。

    ITM_MSG_REQUEST_COTA

    查询是否有可用的远程配置数据。

  • 返回值说明

    说明

    0

    成功。

    >= 1

    消息ID。

    < 0

    失败。

IOT_RegisterCallback

  • 接口原型

    define IOT_RegisterCallback(evt, cb)           iotx_register_for_##evt(cb);
  • 接口说明

    该接口用于注册事件的回调函数,当Linkkit SDK产生事件时,会调用对应的回调函数。

  • 参数说明

    参数

    数据类型

    方向

    说明

    evt

    iotx_ioctl_event_t

    输入

    事件名称。

    cb

    根据evt的不同而不同

    输入

    回调函数。

  • 事件清单

    typedef enum {
        ...
        ITE_CONNECT_SUCC,
        ...
        ITE_DISCONNECTED,
        ITE_RAWDATA_ARRIVED,
        ITE_SERVICE_REQUEST,
        ITE_PROPERTY_SET,
        ITE_PROPERTY_GET,
        ITE_REPORT_REPLY,
        ITE_TRIGGER_EVENT_REPLY,
        ITE_TIMESTAMP_REPLY,
        ITE_TOPOLIST_REPLY,
        ITE_PERMIT_JOIN,
        ITE_INITIALIZE_COMPLETED,
        ITE_FOTA,
        ITE_COTA
    } iotx_ioctl_event_t;
  • 事件列表

    事件

    回调函数原型

    事件触发条件说明

    ITE_CONNECT_SUCC

    int callback(void);

    与云端连接成功时。

    ITE_DISCONNECTED

    int callback(void);

    与云端连接断开时。

    ITE_RAWDATA_ARRIVED

    int callback(const int devid, const unsigned char *payload, const int payload_len);

    Linkkit收到raw data数据时。

    ITE_SERVICE_REQUEST

    int callback(const int devid, const char serviceid, const int serviceid_len, const char request, const int request_len, char **response, int *response_len);

    Linkkit收到服务(同步/异步)调用请求时。

    ITE_PROPERTY_SET

    int callback(const int devid, const char *request, const int request_len);

    Linkkit收到属性设置请求时。

    ITE_PROPERTY_GET

    int callback(const int devid, const char *request, const int request_len, char response, int response_len);

    Linkkit收到属性获取请求时。

    ITE_REPORT_REPLY

    int callback(const int devid, const int msgid, const int code, const char *reply, const int reply_len);

    Linkkit收到上报消息的应答时。

    ITE_TRIGGER_EVENT_REPLY

    int callback(const int devid, const int msgid, const int code, const char eventid, const int eventid_len, const char message, const int message_len);

    Linkkit收到事件上报消息的应答时。

    ITE_TIMESTAMP_REPLY

    int callback(const char *timestamp);

    当Linkkit收到查询时间戳请求的应答时。

    ITE_TOPOLIST_REPLY

    int callback(const int devid, const int msgid, const int code, const char * payload, const int payload_len);

    Linkkit收到查询拓扑关系请求的应答时。

    ITE_PERMIT_JOIN

    int callback(const char * product_key, const int time);

    Linkkit收到允许子设备入网的请求时。

    ITE_INITIALIZE_COMPLETED

    int callback(const int devid);

    设备初始化完成时。

    ITE_FOTA

    int callback(int type, const char *version);

    Linkkit收到可用固件的通知时。

    ITE_COTA

    int callback(int type, const char config_id, int config_size, const char get_type, const char sign, const char sign_method, const char *url);

    Linkkit收到可用远程配置文件的通知时。

  • 返回值说明

    无返回值。

IOT_Ioctl

  • 接口原型

    int IOT_Ioctl(int option, void *data);
  • 接口说明

    用于配置SDK的一些全局选项, 在使用Linkkit高级版时, 需要在IOT_Linkkit_Connect前使用。

  • 参数说明

    参数

    数据类型

    方向

    说明

    option

    int

    输入

    需要进行的操作。

    data

    void *

    输入/输出

    option需要的输入或输出参数。

  • 参数附加说明

    option选项如下:

    typedef enum {
        IOTX_IOCTL_SET_REGION,
        IOTX_IOCTL_GET_REGION,
        IOTX_IOCTL_SET_MQTT_DOMAIN,
        IOTX_IOCTL_SET_HTTP_DOMAIN,
        IOTX_IOCTL_SET_DYNAMIC_REGISTER,
        IOTX_IOCTL_GET_DYNAMIC_REGISTER,
        IOTX_IOCTL_RECV_PROP_REPLY,
        IOTX_IOCTL_RECV_EVENT_REPLY,
        IOTX_IOCTL_SEND_PROP_SET_REPLY,
        IOTX_IOCTL_SET_SUBDEV_SIGN,
        IOTX_IOCTL_GET_SUBDEV_LOGIN
    } iotx_ioctl_option_t;

    参数

    说明

    IOTX_IOCTL_SET_REGION

    设置登录服务器区域。data的数据类型为int *,取值见iot_export.h中的iotx_cloud_region_types_t枚举量。

    IOTX_IOCTL_GET_REGION

    获取当前登录服务器区域。data的数据类型为int *

    IOTX_IOCTL_SET_MQTT_DOMAIN

    IOTX_IOCTL_SET_REGION没有需要的服务器区域时,设置登录MQTT服务器的区域。data的数据类型为char *

    IOTX_IOCTL_SET_HTTP_DOMAIN

    IOTX_IOCTL_SET_REGION没有需要的服务器区域时, 设置登录HTTP服务器的区域,data的数据类型为char *

    IOTX_IOCTL_SET_DYNAMIC_REGISTER

    设置是否需要使用一型一密。data的数据类型为int *

    • 当data的值为1时,使用一型一密。

    • 当data的值为0时,不使用一型一密。

    IOTX_IOCTL_GET_DYNAMIC_REGISTER

    获取当前是否使用一型一密。

    IOTX_IOCTL_RECV_PROP_REPLY

    废弃,与IOTX_IOCTL_RECV_EVENT_REPLY功能相同。

    IOTX_IOCTL_RECV_EVENT_REPLY

    控制当用户上报属性和事件时,是否需要云端的应答消息。data的数据类型为int *

    • 当data的值为1时,需要云端返回应答消息。

    • 当data的值为0时,不需要云端返回应答消息。

    IOTX_IOCTL_SEND_PROP_SET_REPLY

    控制当SDK收到云端的设置属性的消息时,是否需要向云端发送应答消息,data的数据类型为int *

    • 当data的值为1时,SDK需要向云端发送设置属性的应答消息。

    • 当data的值为0时,SDK不需要向云端发送设置属性的应答消息。

    IOTX_IOCTL_SET_SUBDEV_SIGN

    预留。

    IOTX_IOCTL_GET_SUBDEV_LOGIN

    预留。

    IOTX_IOCTL_QUERY_DEVID

    获取ProductKey、DeviceName对应的子设备的Devid。输入为指向iotx_linkkit_dev_meta_info_t类型数据的指针。输出为Devid,如果子设备不存在则返回-1。

    linkkit_example_gateway.c为例,下面代码即可获取子设备数组中subdevArr[2]对应的devid。

    int subdev_id = 0;
    subdev_id = IOT_Ioctl(IOTX_IOCTL_QUERY_DEVID, (void *)&subdevArr[2]);
  • 返回值说明

    说明

    >= 0

    成功。

    < 0

    失败。