海萤物联网教程：Go SDK
文章目录
- 海萤物联网教程：Go SDK
-
- 简介
- 特点
- 开源
- 安装
- 背景知识
- API
-
- 默认参数
- 绑定管道
- 注册服务
- 调用目的节点服务
- 请求和应答数据格式
- 完整示例
-
- ntp服务器开源地址
- ntp服务介绍
-
- 读取时间服务1
- 读取时间服务2.返回的是结构体
- 开放服务示例
- 读取时间服务1
- 读取时间服务2
海萤物联网教程：Go SDK
本文博客链接:http://blog.csdn.net/jdh99,作者:jdh,转载请注明.
欢迎前往社区交流：海萤物联网社区
在线文档地址
简介
此SDK适用于Go 1.12.5版本及以上版本。使用此SDK可以让节点连接海萤物联网，与其他节点通信。节点可以是终端设备，也可以是个人电脑上的程序，可以使用此SDK与其他节点通信，并可以以服务的形式开放自己的能力。
Go SDK是海萤物联网的SDK之一，主要有如下功能：
- 连接海萤物联网
- 与其他节点通信
- 以服务的形式开放节点自身的能力
特点
基于此SDK可以极大降低物联网的开发门槛，可以实现：
- 一行代码连接网络
- 一行代码开放服务
- 一行代码通信
开源
- github上的项目地址
- gitee上的项目地址
安装
推荐使用go mod：github.com/jdhxyy/dcom
安装好后在项目中即可导入使用：
import "https://github.com/jdhxyy/tziot"
导入其他相关的包：
import "https://github.com/jdhxyy/dcom"
背景知识
-
海萤物联网教程：IA地址格式及地址申请方法
-
海萤物联网教程：物联网RPC框架Go DCOM
API
// BindPipeNet 绑定网络管道.绑定成功后返回管道号
func BindPipeNet(ia uint64, pwd string, ip string, port int) (pipe uint64, err error)
// BindPipe 绑定管道.绑定成功后返回管道号
func BindPipe(ia uint64, send SendFunc, isAllowSend IsAllowSendFunc) (pipe uint64)
// PipeReceive 管道接收.pipe是发送方的管道号
// 如果是用户自己绑定管道,则在管道中接收到数据需回调本函数
func PipeReceive(pipe uint64, data []uint8)
// IsConn 是否连接核心网
func IsConn() bool
// Call RPC同步调用
// timeout是超时时间,单位:ms.为0表示不需要应答
// 返回值是应答字节流和错误码.错误码非0表示调用失败
func Call(pipe uint64, dstIA uint64, rid int, timeout int, req []uint8) ([]uint8, int)
// Register 注册服务回调函数
func Register(rid int, callback dcom.CallbackFunc)
// ConfigCoreParam 配置核心网参数
func ConfigCoreParam(ia uint64, ip string, port int)
// ConfigDComParam 配置dcom参数
// retryNum: 重发次数
// retryInterval: 重发间隔.单位:ms
func ConfigDComParam(retryNum, retryInterval int)
- 数据结构
// SendFunc 发送函数.dstPipe:目标管道号
type SendFunc func(dstPipe uint64, data []uint8)
// IsAllowSendFunc 是否允许发送
type IsAllowSendFunc func() bool
// dcom中定义
// CallbackFunc 注册DCOM服务回调函数
// 返回值是应答和错误码.错误码为0表示回调成功,否则是错误码
type CallbackFunc func(pipe uint64, srcIA uint64, req []uint8) ([]uint8, int)
默认参数
当前默认的参数：
| 参数 | 值 |
|---|---|
| DCOM重发次数 | 5 |
| DCOM重发间隔 | 500ms |
调用ConfigDComParam函数可以修改DCOM参数。
ConfigCoreParam函数可以修改海萤物联网平台默认地址，使用默认值即可，不需要调用函数修改。
绑定管道
tziot包中封装了dcom包，在绑定管道时会初始化DCOM。
tziot中调用BindPipe函数可以绑定自定义管道，如果使用自定义管道，则需应用中调用PipeReceive函数将接收到的数据发送给tziot包。
绑定网络管道是绑定管道的一个特例，如果节点可以直接连接互联网（比如使用以太网或者wifi），则调用BindPipeNet函数即可，不需要使用BindPipe函数和PipeReceive函数。
- 示例：绑定网络管道，节点地址是0x2140000000000101，本地端口号是12021
pipe, err := BindPipeNet(0x2140000000000101, pwd, "0.0.0.0", 12021)
返回的是管道号pipe。后续使用Call函数与其他节点通信，需要使用此管道号。
绑定管道后sdk会自动连接海萤物联网，可以调用IsConn函数查看连接是否成功。
注册服务
节点可以通过注册服务开放自身的能力。
// Register 注册服务回调函数
func Register(rid int, callback dcom.CallbackFunc)
注册函数中，每个服务号（rid），都可以绑定一个服务。
- 示例：假设节点2140::101是智能插座，提供控制和读取开关状态两个服务：
tziot.Register(1, controlService)
tziot.Register(2, getStateService)
// controlService 控制开关服务
// 返回值是应答和错误码.错误码为0表示回调成功,否则是错误码
func controlService(pipe uint64, srcIA uint64, req []uint8) ([]uint8, int) {
if req[0] == 0 {
off()
} else {
on()
}
return nil, dcom.SystemOK
}
// getStateService 读取开关状态服务
// 返回值是应答和错误码.错误码为0表示回调成功,否则是错误码
func getStateService(pipe uint64, srcIA uint64, req []uint8) ([]uint8, int) {
return []uint8{state()}, dcom.SystemOK
}
调用目的节点服务
// Call RPC同步调用
// timeout是超时时间,单位:ms.为0表示不需要应答
// 返回值是应答字节流和错误码.错误码非0表示调用失败
func Call(pipe uint64, dstIA uint64, rid int, timeout int, req []uint8) ([]uint8, int)
同步调用会在获取到结果之前阻塞。节点可以通过同步调用，调用目标节点的函数或者服务。timeout字段是超时时间，单位是毫秒。如果目标节点超时未回复，则会调用失败。如果超时时间填0，则表示不需要目标节点回复。
- 示例：2141::102节点控制智能插座2141::101开关状态为开
resp, errCode := tziot.Call(1, 0x2140000000000101, 3000, []uint8{1})
- 示例：2141::102节点读取智能插座2141::101开关状态
resp, errCode := tziot.Call(2, 0x2140000000000101, 3000, nil)
if errCode == dcom.SystemOK {
fmt.println("开关状态:", resp[0])
}
请求和应答数据格式
建议使用结构体来通信。详情可参考： 海萤物联网教程：物联网RPC框架Go DCOM 中的数据格式章节。
完整示例
示例以与海萤物联网中的ntp服务通信为例。
ntp服务器开源地址
- github上的ntp服务项目地址
- gitee上的ntp服务项目地址
ntp服务介绍
海萤物联网ntp服务上线
ntp服务器地址：
0x2141000000000404
当前提供两个服务：
| 服务号 | 服务 |
|---|---|
| 1 | 读取时间1 |
| 2 | 读取时间2.返回的是结构体 |
读取时间服务1
- CON请求：空或者带符号的1个字节。
当CON请求为空时，则默认为读取的是北京时间（时区8）。
也可以带1个字节表示时区号。这个字节是有符号的int8。
小技巧，可以使用0x100减去正值即负值。比如8对应的无符号数是0x100-8=248。
- ACK应答：当前时间的字符串
当前时间字符串的格式：2006-01-02 15:04:05 -0700 MST
读取时间服务2.返回的是结构体
-
CON请求：格式与读取时间服务1一致
-
ACK应答：
struct {
// 时区
uint8 TimeZone
uint16 Year
uint8 Month
uint8 Day
uint8 Hour
uint8 Minute
uint8 Second
// 星期
uint8 Weekday
}
开放服务示例
// Copyright 2021-2021 The jdh99 Authors. All rights reserved.
// 网络校时服务
// Authors: jdh99 读取时间服务1
节点2141::401读取ntp服务器的服务1，并打印时间字符串。
package main
import (
"fmt"
"github.com/jdhxyy/tziot"
)
func main() {
pipe, _ := tziot.BindPipeNet(0x2141000000000401, "abc123", "192.168.1.119", 12021)
for tziot.IsConn() == false{}
resp, err := tziot.Call(pipe, 0x2141000000000004, 1, 3000, []uint8{8})
fmt.Println("err:", err, "time:", string(resp))
}
输出结果：
err: 0 time: 2021-04-01 09:05:33 +0800 CST
读取时间服务2
ntp服务器的2号是结构体形式的时间。
package main
import (
"fmt"
"github.com/jdhxyy/dcom"
"github.com/jdhxyy/tziot"
)
// ACK格式
type AckRidGetTime struct {
// 时区
TimeZone uint8
Year uint16
Month uint8
Day uint8
Hour uint8
Minute uint8
Second uint8
// 星期
Weekday uint8
}
func main() {
pipe, _ := tziot.BindPipeNet(0x2141000000000401, "abc123", "192.168.1.119", 12021)
for tziot.IsConn() == false{}
resp, _ := tziot.Call(pipe, 0x2141000000000004, 2, 3000, []uint8{8})
var ack AckRidGetTime
_ = dcom.BytesToStruct(resp, &ack)
fmt.Println(ack)
}
输出结果：
{8 2021 4 1 9 7 20 4}