Python API for talking to a MySensors gateway
Python API for talking to a MySensors gateway (http://www.mysensors.org/). Currently supports serial protocol v1.4, v1.5 and v2.0. Not all features of v2.0 are implemented yet.
Currently the API is best used by implementing a callback handler
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()
In the above example PyMysensors will call “event” whenever a node in the Mysensors network has been updated. The message passed to the callback handler has the following data:
Message gateway - the gateway instance node_id - the sensor node identifier child_id - the child sensor id type - the message type (int) ack - True is message was an ACK, false otherwise sub_type - the message sub_type (int) payload - the payload of the message (string)
Symbolic names for the Message types and sub_types are defined in the protocol version-specific const_X.py files.
The data structure of a gateway and it’s network is described below.
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. values - a dictionary of values (V_HUM, V_TEMP, etc.)
Getting the type and values of node 23, child sensor 4 would be performed as follows:
s_type = GATEWAY.sensors.children.type values = GATEWAY.sensors.children.values
To update a node child sensor value and send it to the node, use the set_child_value method in the Gateway class:
# To set sensor 1, child 1, sub-type V_LIGHT (= 2), with value 1. GATEWAY.set_child_value(1, 1, 2, 1)
PyMysensors also supports three other settings. Persistence mode, which saves the sensor network between runs, persistence file path, which sets the type and path of the persistence file and protocol version which sets the MySensors serial API version.
With persistence mode on, you can restart the gateway without having to restart each individual node in your sensor network. To enable persistance mode, the third argument in the constructor should be True. A path to the config file can be specified as a fourth argument. The file type (.pickle or .json) will set which persistence protocol to use, pickle or json. JSON files can be read using a normal text editor.
The serial gateway also supports setting the baudrate, read timeout and reconnect timeout.
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_callback=event, persistence=True, persistence_file='somefolder/mysensors.pickle', protocol_version='1.4', baud=115200, timeout=1.0, reconnect_timeout=10.0) GATEWAY.start()
There are two other gateway types supported besides the serial gateway: the tcp-ethernet gateway and the MQTT gateway.
The ethernet gateway is initialized similar to the serial gateway. The ethernet gateway supports setting the tcp host port, receive timeout and reconnect timeout, besides the common settings and the host ip address.
GATEWAY = mysensors.TCPGateway( '127.0.0.1', event_callback=event, persistence=True, persistence_file='somefolder/mysensors.pickle', protocol_version='1.4', port=5003, timeout=1.0, reconnect_timeout=10.0)
The MQTT gateway requires MySensors serial API v2.0 and the MQTT client gateway example sketch loaded in the gateway Arduino. The gateway also requires an MQTT broker and a python MQTT client interface to the broker. See mqtt.py for an example of how to implement this and initialize the MQTT gateway.
Over the air (OTA) firmware updates
Call Gateway method update_fw to set one or more nodes for OTA firmware update. The method takes three positional arguments and one keyword arguement. The first argument should be the node id of the node to update. This can also be a list of many node ids. The next two arguments should be integers representing the firwmare type and version. The keyword argument is optional and should be a path to a hex file with the new firmware.
GATEWAY.update_fw([1, 2], 1, 2, fw_path='/path/to/firmware.hex')
After the update_fw method has been called the node(s) will be requested to restart when pymysensors Gateway receives the next set message. After restart and during the MySensors begin method, the node will send a firmware config request. The pymysensors library will respond to the config request. If the node receives a proper firmware config response it will send a firmware request for a block of firmware. The pymysensors library will handle this and send a firmware response message. The latter request-response conversation will continue until all blocks of firmware are sent. If the CRC of the transmitted firmware match the CRC of the firmware config response, the node will restart and load the new firmware.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|File Name & Checksum SHA256 Checksum Help||Version||File Type||Upload Date|
|pymysensors-0.10.0-py3-none-any.whl (31.6 kB) Copy SHA256 Checksum SHA256||py3||Wheel||May 6, 2017|
|pymysensors-0.10.0.tar.gz (27.4 kB) Copy SHA256 Checksum SHA256||–||Source||May 6, 2017|