设备SDK使用说明(CPP)

C++接口,主要适用于PC、Linux、ARM等平台;安卓平台也适用。

1 接口说明

1.1 关键数据结构定义

/**
* @brief 设备认证信息
*/
struct DeviceAuth
{
    std::string productKey;     ///产品key
    std::string deviceId;       ///设备ID
    std::string deviceSecret;   ///设备密钥
};

/**
* @brief 连接配置信息
*
*/
struct IoTConfig
{
    std::string     host;       ///broker地址
    std::string     version;    ///本地固件版本

    DeviceAuth      device;     ///设备认证信息
    OnConnectState  callback;   ///连接状态回调
};

/**
* @brief 基础信息
*
*/
struct TslBasic
{
    std::string traceId;        ///请求唯一ID
    std::string version;        ///协议版本
    std::string deviceId;       ///设备ID(请求时,如果是网关的子设备则需要填写)
};

/**
* @brief 请求参数
*
*/
struct TslRequest
{
    std::string method;         ///服务名
    std::string params;         ///参数 JSON Object
};

/**
* @brief 回应
*
*/
struct TslResponse
{
    std::string code    = "170000";  ///回应码,000000表示成功,17属于SDK段错误码
    std::string message = "null";    ///回应码描述
    std::string data    = "null";    ///响应 JSON Object
};

1.2 初始化

//构造及析构
IoTMqtt(const IoTConfig &config);
~IoTMqtt();

1.3 MQTT连接及认证

//MQTT连接及认证
//开始连接,失败会自动重连(min, max之间的间隔,第一次重连间隔为min,以后为min*2,直到max)
void Connect(int minRetryInterval = 2, int maxRetryInterval = 60);
bool IsConnected();

1.4 运维相关

//上报日志到grail
void Postlog2Grail(const GrailLog &log);

//设置日志回调
static void SetLogCallback(const MLogCallBack &callback);

1.5 下行

/************************************************************************/
/* 下行(云端 -> 设备)                                                   */
/************************************************************************/
void SetPropertySetCallback(const OnTslRequest &callback);  //设置设置属性回调
void SetPropertyGetCallback(const OnTslRequest &callback);  //设置获取属性回调
void SetServiceCallback(const OnTslRequest &callback);      //设置服务调用回调
bool SubscribeCustom(const std::string &topic, const OnCustomTopic &callback);  //订阅自定义主题

1.6 上行

/************************************************************************/
/* 上行(设备 -> 云端)                                                   */
/************************************************************************/
bool PropertyPost(const TslBasic &basic, const TslRequest &req);                    //属性上报
bool EventPost(const TslBasic &basic, const TslRequest &req);                       //事件上报
bool PropertyGet(const TslBasic &basic, const TslRequest &req, TslResponse &res);   //上行属性获取
bool ServiceCall(const TslBasic &basic, const TslRequest &req, TslResponse &res);   //上行服务调用
bool PublishCustom(const std::string &topic, const std::string &traceId, const std::string &params); //发布自定义主题

1.7 网关类设备

/************************************************************************/
/* 网关类设备                                                            */
/************************************************************************/
bool GetSubDevice(const TslBasic &basic, std::list<DeviceAuth> &devs); //获取网关下挂子设备
bool AddSubDevice(const TslBasic &basic, const DeviceAuth &dev);       //添加网关子设备
bool DelSubDevice(const TslBasic &basic, const DeviceAuth &dev);       //删除网关子设备

bool OnlineSubDevice(const TslBasic &basic, const DeviceAuth &dev);    //上线子设备(包括认证)
bool OfflineSubDevice(const TslBasic &basic, const DeviceAuth &dev);   //下线子设备

2 编程示例

#include <iostream>
#include <functional>
#include <stdio.h>
#include "../src/mqtt/iot_http.h"
#include "../src/mqtt/iot_mqtt.h"

#ifdef WIN32
#include <Windows.h>
#else
#include <unistd.h>
#endif

using namespace std;

void OnTslRequestCallback(const std::string &topic, const TslBasic &basic, const TslRequest &req, TslResponse &res)
{
    std::cout << "[mqtt]topic:" << topic << " traceid:" << basic.traceId << " method:" << req.method << " params:" << req.params << " version:" << basic.version << endl;
    //处理req返回res
}

void MyLogCallBack(const char *file, int line, const char *func, int severity, const char *content)
{
    std::cout << "[" << func << ":" << line << "]" << content << endl;
}

int main()
{
    //log
    IoTMqtt::SetLogCallback(MyLogCallBack);

    //注册
    IoTHttp http("http://iot.test.seewo.com/iot-platform-register-service/register");
    http.AddIdentifier("uid", { "xxx-1234","xxxx-2345" });
    ProductAuth product;
    product.productKey = "1_29232629e9a";
    product.productSecret = "95580bf558e94d84";
    DeviceAuth device;
    auto regRet = http.DeviceRegister(product, device);
    if (!regRet)
    {
        cerr << "register failed" << endl;
    }
    std::cout << "register successed:" << device.deviceId << endl;

    //认证
    IoTConfig config;
    config.host = "ssl://iot-broker.test.seewo.com:8883";
    config.device = { "1_29232629e9a","292485855732375552","b56ac88cabdc0f0d" };
    config.callback = nullptr;
    config.version = "1.0.0";

    IoTMqtt mqtt(config);
    auto conRet = mqtt.Connect();
    if (!conRet)
    {
        std::cout << "mqtt connect failed" << endl;
        return 2;
    }

    std::cout << "mqtt connect successed 1" << endl;
    mqtt.SetPropertyGetCallback(OnTslRequestCallback);
    mqtt.SetPropertySetCallback(OnTslRequestCallback);
    mqtt.SetServiceCallback(OnTslRequestCallback);

    std::cout << "mqtt connect successed 2" << endl;

    //发布
    TslRequest req;
    req.method = "thing.property.post";
    req.params = " {\"color\": \"red\",\"electricity\" : 30}";

    TslBasic basic;
    basic.version = "1.0.0";
    basic.traceId = "123456789";

    while (true)
    {
        auto postRet = mqtt.PropertyPost(basic, req);
        if (!postRet)
        {
            std::cout << "mqtt publish failed" << endl;
        }
        else
        {
            std::cout << "mqtt publish successed" << endl;
        }

#ifdef WIN32
        Sleep(3000);
#else
        sleep(3);
#endif
    }

    return 0;
}

2.1 示例详解

2.1.1 IoT注册示例

确定平台注册的地址,调用http.AddIdentifier添加设备的特有信息(此信息可以不止一种,一般也不止一种),通过http.DeviceRegister进行设备的注册(注册时根据所有的信息综合判断),返回设备的三元信息。 注册平台的地址可参考:03.用户指南 -> 04.相关文档 01.环境说明

img

2.1.2 接入IoT示例

使用设备注册的三元组信息(DeviceAtuh device)作为MQTT连接参数,向IoT平台发起连接即可。 红圈内,就是设备注册后返回的三元组信息。

img

连接上后,一般都需要设置云端下行数据到设备的回调函数,例如:thing.property.get,thing.property.set,thing.service.调用的函数。在接收到下行数据时根据不同数据,触发不同的回调处理数据。

img

2.1.3 消息发布示例

发布消息需要准备TslRequest,TslBasic,可参考03.上下行参数说明,组合而成即可。消息发布也可以通过选择不同的函数,大多时候使用mqtt.PropertyPost可满足。

img

2.1.4 属性post(上行)、属性get(上行)示例

以color属性的上行post和上行get为例子,操作前需要先在IoT物联平台中添加相关的产品功能定义(此处为类型为text的color属性)。

img

2.1.5 属性set(下行)、属性get(下行)示例

以color属性的下行set和下行get为例子,操作前需要先在IoT物联平台中添加相关的产品功能定义(此处为类型为text的color属性)。 下行属性get、set消息在设备端中需要触发回调函数响应,用mqtt.SetPropertyGetCallback设置下行属性get回调,用mqtt.SetPropertyGetCallback设置下行属性set回调。

img

在希沃物联平台中选择在线调试,设置调试设备、调试类型、调试功能。

发送设置颜色属性指令:

img

发送获取颜色属性指令:

img

2.1.6 自定义主题示例

发布前需要先在IoT物联平台中添加产品的信息通信主题,例如:/user/${productKey}/${deviceId}/custom/test。 调用自定义消息发布接口mqtt.PublishCustom,附加主题参数topic及消息内容参数params即可。

img

2.1.7 网关设备示例

2.1.7.1 添加网关子设备示例

调用mqtt.AddSubDevice接口进行网关子设备的添加,添加前需要知道子设备的三元信息。如果子设备未进行注册,则要先进行设备注册,可参考2.1.1 IoT注册

img

2.1.7.2 网关子设备上/下线示例

调用mqtt.OnlineSubDevice接口对子设备进行上线操作,调用mqtt.OfflineSubDevice接口对子设备进行下线操作。子设备的上下线操作同样需要知道三元信息。

子设备上线:

img

子设备下线:

img

2.1.7.3 删除网关子设备示例

调用mqtt.DelSubDevice接口可以删除指定的子设备。

img