pymysensors

用于与MySensors 网关对话的 Python API 。目前支持串口协议v1.4、v1.5、v2.0-v2.2。尚未实现 v2.x 的所有功能。

• 通过串行 API v2.x 支持 smartsleep。
• 支持带有串行 API v2.x 的 MQTT 客户端网关。
• 支持DualOptiboot和MYSBootloader引导加载程序的 OTA 更新。
• 所有网关实例、串行、tcp（以太网）或 mqtt 将在单独的线程中运行。
• 作为在自己的线程中运行网关的替代方案，所有网关都有使用 asyncio 的实验性实现。

要求

pymysensors 需要 Python 3.6+。

安装

您可以从 PyPI 轻松安装它：

pip3 install pymysensors

用法

目前最好通过实现回调处理程序来使用 API

import mysensors.mysensors as mysensors

def event(message):
    """Callback for mysensors updates."""
    print('sensor_update ' + str(message.node_id))

GATEWAY = mysensors.SerialGateway('/dev/ttyACM0', event)
GATEWAY.start()

在上面的示例中，只要 Mysensors 网络中的节点更新，pymysensors 就会调用“event”。传递给回调处理程序的消息具有以下数据：

Message
    gateway - the gateway instance
    node_id - the sensor node identifier
    child_id - the child sensor id
    type - the message type, for example "set" or "presentation" (int)
    ack - True is message was an ACK, false otherwise (0 or 1)
    sub_type - the message sub_type (int)
    payload - the payload of the message (string)

注意： sub_type 的内容因上下文而异。在表示消息中，sub_type 表示 S_TYPE 数据（例如 S_INFO）。在“set”和“req”消息中，sub_type 表示 V_TYPE 数据（例如 V_TEXT）。

消息类型和子类型的符号名称在协议版本特定的 const_X.py 文件中定义。

网关及其网络的数据结构如下所述。

SerialGateway/TCPGateway/MQTTGateway
    sensors - a dict containing all nodes for the gateway; node is of type Sensor

Sensor - a sensor node
    children - a dict containing all child sensors for the node
    sensor_id - node id on the MySensors network
    type - 17 for node or 18 for repeater
    sketch_name
    sketch_version
    battery_level
    protocol_version - the mysensors protocol version used by the node

ChildSensor - a child sensor
    id - child id on the parent node
    type - data type, S_HUM, S_TEMP etc.
    description - the child description sent when presenting the child
    values - a dictionary of values (V_HUM, V_TEMP, etc.)

获取节点 23 的类型和值，子传感器 4 将执行如下：

s_type = GATEWAY.sensors[23].children[4].type
values = GATEWAY.sensors[23].children[4].values

同样，打印找到的节点的所有草图名称可能如下所示：

for node in GATEWAY.sensors.values():
    print(node.sketch_name)

在事件函数中获取子对象可能是：

    if GATEWAY.is_sensor(message.node_id, message.child_id):
        child = GATEWAY.sensors[message.node_id].children[message.child_id]
    else:
        print("Child not available yet.")

要更新节点子传感器值并将其发送到节点，请使用 Gateway 类中的 set_child_value 方法：

# To set sensor 1 (int), child 1 (int), sub-type V_LIGHT (= 2) (int), with value 1.
GATEWAY.set_child_value(1, 1, 2, 1)

持久性

启用持久性模式后，您可以重新启动网关，而无需重新启动传感器网络中的每个单独节点。要启用持久模式，persistence 构造函数中的关键字参数应为 True。配置文件的路径可以指定为关键字参数persistence_file。文件类型（.pickle 或 .json）将设置要使用的持久性协议，pickle 或 json。JSON 文件可以使用普通的文本编辑器读取。如果自上次保存后已完成更新，则将按计划每 10 秒保存到持久性文件。确保在启动网关之前启动持久性保存。

GATEWAY.start_persistence()

协议版本

设置关键字参数protocol_version以设置要使用的 MySensors 串行 API 的版本。默认值为'1.4'。将 设置为protocol_version您正在使用的版本。

串行网关

串口网关还支持设置波特率、读取超时和重连超时。

import mysensors.mysensors as mysensors

def event(message):
    """Callback for mysensors updates."""
    print("sensor_update " + str(message.node_id))

GATEWAY = mysensors.SerialGateway(
  '/dev/ttyACM0', baud=115200, timeout=1.0, reconnect_timeout=10.0,
  event_callback=event, persistence=True,
  persistence_file='some_folder/mysensors.pickle', protocol_version='2.2')
GATEWAY.start_persistence() # optional, remove this line if you don't need persistence.
GATEWAY.start()

除了串行网关外，还支持另外两种网关类型：tcp-ethernet 网关和 MQTT 网关。

TCP 以太网网关

以太网网关的初始化类似于串行网关。以太网网关除了常用设置和主机ip地址外，还支持设置tcp主机端口、接收超时和重连超时。

GATEWAY = mysensors.TCPGateway(
  '127.0.0.1', port=5003, timeout=1.0, reconnect_timeout=10.0,
  event_callback=event, persistence=True,
  persistence_file='some_folder/mysensors.pickle', protocol_version='1.4')

MQTT 网关

MQTT 网关需要 MySensors 串行 API v2.0 或更高版本以及在网关设备中加载的 MQTT 客户端网关示例草图。网关还需要一个 MQTT 代理和一个到代理的 python MQTT 客户端接口。请参阅mqtt.py以获取有关如何实现此功能和初始化 MQTT 网关的示例。

无线 (OTA) 固件更新

调用Gateway方法update_fw设置一个或多个节点进行OTA固件更新。该方法采用三个位置参数和一个关键字参数。第一个参数应该是要更新的节点的节点 ID。这也可以是许多节点 ID 的列表。接下来的两个参数应该是代表固件类型和版本的整数。关键字参数是可选的，应该是带有新固件的 hex 文件的路径。

GATEWAY.update_fw([1, 2], 1, 2, fw_path='/path/to/firmware.hex')

调用该方法后，update_fw当 pymysensors Gateway 收到下一个设置消息时，将请求重新启动节点。重启后和 MySensorsbegin方法期间，节点将发送固件配置请求。pymysensors 库将响应配置请求。如果节点收到正确的固件配置响应，它将发送一个固件块的固件请求。pymysensors 库将处理此问题并发送固件响应消息。后面的请求-响应对话将继续进行，直到所有固件块都发送完毕。如果传输固件的 CRC 与固件配置响应的 CRC 匹配，则节点将重新启动并加载新固件。

网关编号

网关方法get_gateway_id将尝试返回网关的唯一 ID。这将是串行网关的 USB 设备的序列号、tcp 网关的连接网关的 mac 地址或 mqtt 网关的发布主题前缀 (in_prefix)。

连接回调

可以在网关上注册两个可选回调，这些回调在建立连接和与网关设备的连接丢失时调用。两个回调都应接受网关参数，即网关实例。连接丢失回调还应接受可能的连接错误异常参数的第二个参数。如果连接丢失且没有错误，例如断开连接时，错误参数将为None.

注意： MQTT 网关不支持这些回调，因为与 MQTT 代理的连接是在 pymysensors 之外处理的。

def conn_made(gateway):
  """React when the connection is made to the gateway device."""
  pass

GATEWAY.on_conn_made = conn_made

def conn_lost(gateway, error):
  """React when the connection is lost to the gateway device."""
  pass

GATEWAY.on_conn_lost = conn_lost

异步网关

串行、TCP 和 MQTT 网关现在也有支持 asyncio 的版本。使用 AsyncSerialGateway类、AsyncTCPGateway类或AsyncMQTTGateway类来制作使用 asyncio 的网关。以下公共方法是异步网关中的协程：

• get_gateway_id
• start_persistence
• 开始
• 停止
• update_fw

有关如何使用此网关的示例，请参阅async_main.py 。

发展

安装开发所需的包。

pip install -r requirements_dev.txt

使用 Makefile 运行常见的开发任务。

make

代码格式

我们使用黑色代码格式化程序来自动格式化代码。这需要 Python 3.6 进行开发。

black ./

发布

请参阅发布说明。