Written and (C) 2015 Oliver Wagner [email protected]
Provided under the terms of the MIT license.
eno2mqtt is a gateway between a Enocean ESP3-capable gateway module (e.g. a TCM310, USB300 or Enocean PI) and MQTT. It receives Enocean ERP1 telegrams and publishes them as MQTT topics.
It's intended as a building block in heterogenous smart home environments where an MQTT message broker is used as the centralized message bus. See https://github.com/mqtt-smarthome for a rationale and architectural overview.
- Java 1.7 SE Runtime Environment: https://www.java.com/
- Eclipse Paho: https://www.eclipse.org/paho/clients/java/ (used for MQTT communication)
- Minimal-JSON: https://github.com/ralfstx/minimal-json (used for JSON creation and parsing)
- NRJavaSerial: https://github.com/NeuronRobotics/nrjavaserial (used for serial communication)
The connection to the ESP3 device can either be made locally through a serial port (the USB300 stick is just a TCM310 with a FTDI USB<->Serial converter) or remotely via network via some remote serial service. The latter is useful if you want to put the USB300 stick in the most efficient position RF-wise, but have the actual processing running elsewhere. Some very low grade hardware (e.g. a TP-LINK WR703N with OpenWRT) can then be used as a remserial server for the stick.
In order to know what type an Encoean device is and how to interpret it's messages, eno2mqtt needs a device list file. It's a simple text file with three columns:
Enocean_ID EEP Symbolic_Name
The Enocean_ID is the ID of the given device in hex notation, without a 0x prefix.
The EEP is the Enocean Equipment Profile ID, in the form RORG-FUNC-TYPE. A list of all EEPs is available on the Enocean web site at https://www.enocean.com/en/knowledge-base/
The Symbolic_Name is used as the topic prefix when publishing status reports from the given device. Depending on the EEP, this may be suffixed further.
A special topic is prefix/connected. It holds an enum value which denotes whether the adapter is currently running (1) and connected to the ESP3 devices (2). It's set to 0 on disconnect using a MQTT will.
The message format generated is a JSON encoded object with the following members:
- val - the actual value, in numeric format
- eno_srcid - when sending message, eno2mqtt fills in the source ID of the sending device. This field is ignored on incoming messages.
- eno_dbm - the RSSI value of the received message
- F6-02
- F6-03
Rocker switches. Publishes state to subtopics "AI", "AO" etc. as either 1 for pressed or 0 for released. The published messages are not retained, as those are one-shot events. Dual-button presses are reported on the respective dual-button topic, e.g. "AIBI".
- F6-10-00
Window handle: val=0 down, val=1 left/right, val=2 up
Configuration options can either be specified on the command line, or as system properties with the prefix "eno2mqtt". Examples:
java -jar eno2mqtt.jar eno.esp3=/dev/ttyUSB0 eno.deviceList=devicelist.txt
java -Deno.esp3=/dev/ttyUSB0 -jar eno2mqtt.jar
-
eno.esp3
One or more ESP3 devices to connect to (TCM310, USB300, Enocean PI etc.)
Either a com port specification, or a network address in the form
NET:host:port
for a remote serial server. Multiple devices can be specified in a comma-separated list. Must be specified.
-
eno.deviceList
The device list file. Must be specified.
-
eno.setRepeater
Set the repeater mode of the TCM. Format is "mode,level". Mode can be OFF, ALL or FILTERED, level can be LEVEL1 or LEVEL2
-
mqtt.server
ServerURI of the MQTT broker to connect to. Defaults to "tcp://localhost:1883".
-
mqtt.clientid
ClientID to use in the MQTT connection. Defaults to "eno2mqtt".
-
mqtt.topic
The topic prefix used for publishing and subscribing. Defaults to "eno/".
When running eno2mqtt on a server class machine, it makes sense to limit the memory usage to 64MB using the java options
-Xmx64M
- Project overview: https://github.com/mqtt-smarthome
-
0.6 - 2015/07/28 - owagner
- include timestamps ("ts") in generated JSON objects
- updated minimal-json to 0.9.4 and eclipse-paho to 1.0.2
-
0.5 - 2015/03/19 - owagner
- now properly supports multiple ESP3 connections. Will filter duplicate messages within 500ms.
- changed state handling: will now retry failed connections every 10 seconds. Will keep running as long as there is at least one active connection within 15 seconds
- made initial device list dump in log more readable
- log sync errors
- fixed setting repeater to OFF mode
- relabeled all references to TCM310 to the even more accurate ESP3 designation
-
0.4 - 2015/03/15 - owagner
- now sends RD_DUTYCYCLE every 60s and dumps a possible output, mostly as a serial-level keepalive
-
0.3 - 2015/03/14 - owagner
- renamed property eno.usb300 to the more accurate eno.tcm
- added eno.setRepeater to set the repeater mode of the TCM
- more detailed log output about received frames (including dest ID, RSSI and status flags)
- include RSSI value in generated messages
-
0.2 - 2015/03/12 - owagner
- now supports F6-02 and F6-03 EEPs (rocker switches)
-
0.1 - 2015/03/11 - owagner
- initial version