设备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 ¶ms); //发布自定义主题
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.环境说明
2.1.2 接入IoT示例
使用设备注册的三元组信息(DeviceAtuh device)作为MQTT连接参数,向IoT平台发起连接即可。 红圈内,就是设备注册后返回的三元组信息。
连接上后,一般都需要设置云端下行数据到设备的回调函数,例如:thing.property.get,thing.property.set,thing.service.调用的函数。在接收到下行数据时根据不同数据,触发不同的回调处理数据。
2.1.3 消息发布示例
发布消息需要准备TslRequest,TslBasic,可参考03.上下行参数说明,组合而成即可。消息发布也可以通过选择不同的函数,大多时候使用mqtt.PropertyPost可满足。
2.1.4 属性post(上行)、属性get(上行)示例
以color属性的上行post和上行get为例子,操作前需要先在IoT物联平台中添加相关的产品功能定义(此处为类型为text的color属性)。
2.1.5 属性set(下行)、属性get(下行)示例
以color属性的下行set和下行get为例子,操作前需要先在IoT物联平台中添加相关的产品功能定义(此处为类型为text的color属性)。 下行属性get、set消息在设备端中需要触发回调函数响应,用mqtt.SetPropertyGetCallback设置下行属性get回调,用mqtt.SetPropertyGetCallback设置下行属性set回调。
在希沃物联平台中选择在线调试,设置调试设备、调试类型、调试功能。
发送设置颜色属性指令:
发送获取颜色属性指令:
2.1.6 自定义主题示例
发布前需要先在IoT物联平台中添加产品的信息通信主题,例如:/user/${productKey}/${deviceId}/custom/test
。
调用自定义消息发布接口mqtt.PublishCustom,附加主题参数topic及消息内容参数params即可。
2.1.7 网关设备示例
2.1.7.1 添加网关子设备示例
调用mqtt.AddSubDevice接口进行网关子设备的添加,添加前需要知道子设备的三元信息。如果子设备未进行注册,则要先进行设备注册,可参考2.1.1 IoT注册。
2.1.7.2 网关子设备上/下线示例
调用mqtt.OnlineSubDevice接口对子设备进行上线操作,调用mqtt.OfflineSubDevice接口对子设备进行下线操作。子设备的上下线操作同样需要知道三元信息。
子设备上线:
子设备下线:
2.1.7.3 删除网关子设备示例
调用mqtt.DelSubDevice接口可以删除指定的子设备。