README.md · ultimate_smile/moqbus-iot

# Moqbus 概览

moqbus是一个开源的轻量级物联网通讯中间件。

对于传统设备智能化和中小型基于物联网的项目，moqbus提供了一套集成的快速构建物联网平台的解决方案。

Moqbus是物联网架构中连接传感器和应用程序的中介，传感器将采集的数据发送给moqubus，应用程序从moqbus获取数据，并可以通过moqbus向传感器设备发送指令进行反控。应用程序包括web app、手机／平板app、微信小程序等人机交互程序，不需要过多考虑传感设备连接的复杂性，就可以轻松创建高效的物联网系统。

## 优势

* 开放源码： 基于 LGPL-3.0 许可证开源，你可以为你的项目搭建自主可控的物联网平台。

* 硬件兼容性：moqbus不预设硬件传输的数据格式。无论是传统的modbus、json还是自定义的格式，都可以接入。

* 动态脚本解码器：平台内置的虚拟机容器可以动态执行脚本，对网关数据进行解析，可以处理比较复杂的逻辑。

* 低耦合：内核与插件分离的架构设计，允许你在不修改内核代码的情况下，通过外挂插件来扩展功能。

* 开发接口：moqbus专注于接入管理和数据解析，通过向上层提供丰富的开发接口，以支持各种基于物联网的应用系统的开发。

## 功能

以下是moqbus不完全功能列表。

### 连接

支持TCP连接。硬件设备（或通过网关）与moqbus建立TCP长连接。设备无需实现复杂的应用层协议。

### 转发

moqbus使用Mqtt服务器发布来自设备的上行数据，通过TCP下发来自用户的控制指令。

### 解析

接收到来自设备的上行数据后，调用动态脚本解码器对数据进行解析，并将结果通过mqtt转发。上层应用可以按需订阅。

### 存储

moqbus使用 Mongodb 存储了所有设备上报的时序数据，上层应用可以通过接口查询。
所有的上行/下行原始数据也被作为通讯日志存储，以便于调试和追踪设备状况。

### 管理

管理控制台提供了设备的创建、配置、状态监控、数据展现、调试等功能。

# 快速体验

本章节将指导您从 moqbus cloud 开始，快速体验moqbus物联网平台。

## 注册与登录

暂时放下【安装与部署】的琐碎工作，先使用 moqbus cloud 来快速体验一下吧。

* 访问moqbus cloud平台，[注册moqbus帐号][id_reg]。    
   * 注册成功后，使用用户名／密码 [登录moqbus平台][id_login]

[id_reg]: http://cloud.moqbus.com/app/reg.html
[id_login]: http://cloud.moqbus.com/app/login.html

## 创建设备

* 在“设备管理”中，点击表头右侧“+”号按钮，添加设备； 
   * 设备添加成功后，在设备列表页面，可以看到刚才添加的设备；

![设备列表](_media/device_list.png)

* 在列表中，点击“设备编号”链接，可以查看设备的编号和通讯密码。

![设备编号](_media/device_sec.png)

* 添加传感器
    我们还需要给这个设备添加一个传感器，作为数据归集的载体。
    
   传感器管理请参考 [Moqbus物联网平台使用手册（V1.0）][id_manual2] 【3.3 传感器管理】 。

[id_manual2]:https://zhuanlan.zhihu.com/p/559475438

![传感器添加](_media/sensor_add.png)

## 模拟设备连接

设备创建完成后，就可以配置硬件连接到平台了... 不过那样的话可能要费半天功夫，就达不到快速体验的效果了。

为了快速让你了解平台的全貌，接下来我们将使用一个设备模拟器来连接平台。

* 下载设备模拟器  [devmock.zip][id_download_devmock]；
    
[id_download_devmock]: http://doc.moqbus.com/download/devmock.zip
    
   * 解压缩zip, 打开命令行，进入解压后的目录。
    
> cd [下载目录]/devmock

* 运行模拟器, 与平台建立TCP连接
            
> java -jar devmock.jar console d test.moqbus.com 2883 -noreg
>             
> INPUT DATA TO SERVER>

* 向平台发送登录报文

登录报文格式为
> REG:[设备编号],[通讯密码];

具体到本例中为：
   > REG:FD063D44,F37D6D3455;

转换为二进制序列：
   > 52 45 47 3A 46 44 30 36 33 44 34 34 2C 46 33 37 44 36 44 33 34 35 35 3B

发送登录报文，在设备模拟器的窗口输入报文二进制序列并按回车键：     
   > INPUT DATA TO SERVER>52 45 47 3A 46 44 30 36 33 44 34 34 2C 46 33 37 44 36 44 33 34 35 35 3B

* 查看设备状态

平台接收到登录报文后，将根据报文中的信息验证设备身份。

如果验证成功，设备状态将显示为“在线”（绿色圆点）：
	
   ![设备在线](_media/device_online2.png?)

## 与设备交互

设备与平台建立连接并成功登录后，就可以互相发送数据了。

接下来我们将假设这个模拟设备是一个温湿度传感器，来演示从平台下发问询指令，以及设备收到问询指令后进行应答。

* 温湿度传感器的通讯协议

| 问询：  | 地址码  | 功能码  | 起始地址    | 数据长度    | 校验码低位 | 校验码高位  |
		|:-------|:-------|:-------|:-----------|:----------|:----------|:----------|
		|        | 0x01   | 0x03   | 0x00 0x00  | 0x00 0x02 | 0xC4     | 0x0B       |

| 应答：  | 地址码  | 功能码  | 有效字数  | 湿度值     | 湿度值     | 校验码低位 | 校验码高位  |
		|:-------|:-------|:-------|:--------|:-----------|:----------|:----------|:----------|
		|        | 0x01   | 0x03   | 0x04    | 0x02 0x92  | 0xFF 0x9B | 0x5A     | 0x3D       |

* 平台下发问询指令
 
>    01 03 00 00 00 02 C4 0B

在“实时控制”页面，输入命令，点击“发送”执行下发问询指令：

![下发指令](_media/down_cmd.png)

* 设备接收问询指令

在设备模拟器的窗口，可以看到设备已经接收到了问询指令：

![接收指令](_media/receive_cmd.jpg)

* 设备上报温湿度数据

>  01 03 04 02 92 FF 9B 5A 3D
   
   在设备模拟器的窗口输入应答数据并按回车键：

![上报数据](_media/up_dat.jpg)

* 平台接收温湿度数据
  
   在“实时控制”页面，可以看到从设备上报的温湿度数据：

![接收数据](_media/receive_dat.png)

## 解析数据

上一节中我们完成了一次设备和平台之间“问询-应答”的交互。但是，设备上报到平台的数据是原始的二进制序列，这个不是我们想要的数据格式。
 
   我们需要按照传感器的通讯协议，把它转化为可读的形式，提供给上层应用。

* 认识解码器

从硬件设备上报过来的数据，有的是二进制序列，有的是按一定规则组织的ASCII字符串，或者是json格式字符串。

我们需要设置一个转换规则，将这些数据重新组织成便于上层应用使用的结构化的数据格式。 以上述温湿度传感器为例，我们需要将二进制序列中的温度和湿度字段提取出来。

在moqbus中，我们使用一个可编程的脚本函数进行动态解析并将数据组织成json格式输出。这个脚本函数就是解码器。

* 温度值和湿度值的解码规则

> 温度： 当温度低于 0℃时以补码形式上传。FF9B H(十六进制)=-101=>温度=-10.1℃
	>
	> 湿度： 292 H(十六进制)=658=>湿度=65.8%RH

* 编写JS脚本函数

解码器函数的输入参数，是设备上报的温湿度二进制序列；输出结果为含有温度(wd)和湿度(sd)字段的json字符串。

```
function decodeDat(bytes) {
  var MAX_WD = 100;
  var MIN_WD = -100;
  var MAX_SD = 100;
  var MIN_SD = 0;
  
  if (bytes.length < 9 || bytes[0]!=1 || bytes[1]!=3) {
  	return null;
  }
  var bHumi = new Uint8Array([0x00, 0x00, bytes[3], bytes[4]]);	
  var bTemp = new Uint8Array([0x00, 0x00, bytes[5], bytes[6]]); 
  var minus = 1;
  // 当温度低于 0°C时以补码形式上传
  if ((bTemp[2]&0x80) == 0x80) {
    minus = -1;
    bTemp[2] = ~bTemp[2];
    bTemp[3] = ~bTemp[3] + 0x01;
    if (bTemp[3] == 0x00) {
       bTemp[2] =+ 0x01;
       bTemp[2] = bTemp[2] & 0x7F;
    }
  }

var intHumi = 0;  
  var intTemp = 0;  
  intHumi += (bHumi[0] & 0xFF) << (8 * (3 - 0));  
  intHumi += (bHumi[1] & 0xFF) << (8 * (3 - 1));  
  intHumi += (bHumi[2] & 0xFF) << (8 * (3 - 2));  
  intHumi += (bHumi[3] & 0xFF) << (8 * (3 - 3));  
  intTemp += (bTemp[0] & 0xFF) << (8 * (3 - 0));  
  intTemp += (bTemp[1] & 0xFF) << (8 * (3 - 1));  
  intTemp += (bTemp[2] & 0xFF) << (8 * (3 - 2));  
  intTemp += (bTemp[3] & 0xFF) << (8 * (3 - 3));

intTemp = intTemp/10.0*minus;
  intHumi = intHumi/10.0;

if (intTemp>MAX_WD || intTemp < MIN_WD || intHumi > MAX_SD || intHumi < MIN_SD) {
	return null;
  }
  return JSON.stringify({"sno":1,"data":{"wd":intTemp,"sd":intHumi}});
}

```

* 设置解码器

进入解码器设置页面，将上述js函数复制到“javascript函数”文本域中：
   
>    注：具体操作方法可参考 [Moqbus物联网平台使用手册（V1.0）][id_manual]。
   
   [id_manual]:https://zhuanlan.zhihu.com/p/559475438

![javascript函数](_media/js_decoder.png)

* 设置返回值模式
   
   在“返回值模式”文本域中输入以下内容：

```
   {
    "1": {
        "type": "metric",
        "field": {
            "wd": {
                	"display": "温度",
                	"format": "#.0",
                	"unit": "℃"
                },
			"sd": {
                    "display": "湿度",
                    "format": "#.0",
                    "unit": "%"
                }
            }
        }
    }

```

* 设置测试用例
   
   在“测试用例”文本域中输入以下内容，并单击右侧工具栏的保存图标：

```
  [
    {
        "input": "01 03 04 01 7B 00 A7 CA 6C",
        "output": {
            "sno": 1,
            "data": {
                "wd": 16.7,
                "sd": 37.9
            }
        }
    },
    {
        "input": "89",
        "output":"null"
    }
  ]
```

* 查看解码后的数据

重新运行 [与设备交互](#与设备交互) 中的步骤，最后我们将会在“实时控制”界面中看到解码后的json格式数据：

![解析后的数据](_media/parsed_dat.png)

## 设备状态和历史数据

* 设备状态

正常工作的设备需要与平台保持连接，以便能够接收到用户或上层应用通过平台下发的指令，并作出反馈。

在moqbus中，我们使用“状态监控”功能，可以查看设备的上线/下线的事件日志。也可以在上层应用中订阅这些事件，及时掌握设备的状态。

![事件日志](_media/event_log.png)

* 历史数据

设备应答或主动上报的数据，moqbus将其保存在mongodb中，可以在“历史数据”中查看。上层应用也可以使用api接口访问这些数据。

![事件日志](_media/history.png)

# 技术支持

[官网文档][id_doc]  &emsp;| &emsp; QQ群: 941036927

[id_doc]:http://doc.moqbus.com

ultimate_smile/moqbus-iot

简介

发行版

贡献者

近期动态

ultimate_smile/moqbus-iot .gitee-modal { width: 500px !important; }

简介

发行版

贡献者

近期动态

搜索帮助

ultimate_smile/moqbus-iot