ECHONET Lite to MQTT bridge.
日本語のReadmeはこちら (Readme in Japanese is here)
This application publishes ECHONET Lite devices to MQTT. And uses MQTT to work with ECHONET Lite devices. This will allow you to operate your ECHONET Lite device from a smart home application that supports MQTT.
The supported devices are as follows.
- Crime prevention sensor (0x0002)
- Emergency button (0x0003)
- Human detection sensor (0x0007)
- Temperature sensor (0x0011)
- Humidity sensor (0x0012)
- Bath heating status sensor (0x0016)
- CO2 sensor (0x001B)
- VOC sensor (0x001D)
- Electric energy sensor (0x0022)
- Current sensor (0x0023)
- Illuminance sensor (0x00D0)
- Home air conditioner (0x0130)
- Ventilation fan (0x0133)
- Air conditioner ventilation fan (0x0134)
- Air cleaner (0x0135)
- Package-type commercial air conditioner (indoor unit) (except those for facilities) (0x0156)
- Package-type commercial air conditioner (outdoor unit) (0x0157)
- Electrically operated blind/shade (0x0260)
- Electrically operated rain sliding door/shutter (0x0263)
- Electrically operated window (0x0265)
- Electric water heater (0x026B)
- Electric lock (0x026F)
- Instantaneous water heater (0x0272)
- Bathroom heater dryer (0x0273)
- Household solar power generation (0x0279)
- Cold or hot water heat source equipment (0x027A)
- Floor heater (0x027B)
- Fuel cell (0x027C)
- Storage battery (0x027D)
- EV charger and discharger (0x027E)
- Watt-hour meter (0x0280)
- Water flowmeter (0x0281)
- Gas meter (0x0282)
- Power distribution board metering (0x0287)
- Low-voltage smart electric energy meter (0x0288)
- High-voltage smart electric energy meter (0x028A)
- Smart electric energy meter for sub-metering (0x028D)
- distributed generator's electric energy meter (0x028E)
- Bidirectional high voltage smart electric energy meter (0x028F)
- General lighting (0x0290)
- Mono functional lighting (0x0291)
- EV Charger (0x02A1)
- Lighting system (0x02A3)
- Extended lighting system (0x02A4)
- Multiple input pcs (0x02A5)
- Hybrid water heater (0x02A6)
- Frequency regulation (0x02A7)
- Refrigerator (0x03B7)
- Cooking heater (0x03B9)
- Rice cooker (0x03BB)
- Commercial showcase (0x03CE)
- Washer and dryer (0x03D3)
- Commercial show case outdoor unit (0x03D4)
- Switch (supporting JEM-A/HA terminals) (0x05FD)
- Controller (0x05FF)
- Television (0x0602)
echonetlite2mqtt automatically finds devices in the same network.
Therefore, echonetlite2mqtt must be run on the same network as the devices.
Also, when using docker, --net=host is required.
You can install from the following link.
see details: https://github.com/banban525/hassio-echonetlite2mqtt
- Run the following command
docker run -d --net=host -e MQTT_BROKER="mqtt://your.mqtt.brocker" banban525/echonetlite2mqtt
- Open "http://(docker host):3000" in your browser. You can view the detected devices and logs.
- clone this repository.
git clone https://github.com/banban525/echonetlite2mqtt.git
- Run the following command to initialize in repository root directory.
cd echonetlite2mqtt
npm install
- Run the following command to start the service.
npm start -- --MqttBroker "mqtt://your.mqtt.brocker"
- Open "http://localhost:3000" in your browser. You can view the detected devices and logs.
MQTT Options
| Environment Variables | Commandline Parameter | Description |
|---|---|---|
MQTT_BROKER |
--MqttBroker |
The MQTT broker's URL. starts with "mqtt://" or "mqtts://". |
MQTT_PORT |
--MqttPort |
The MQTT broker port number. (Default: 1883) |
MQTT_CLIENT_ID |
--MqttClientId |
The MQTT client id. (Default: empty) |
MQTT_USERNAME |
--MqttUsername |
The MQTT user name. (Default: empty) |
MQTT_PASSWORD |
--MqttPassword |
The MQTT password. (Default: empty) |
MQTT_OPTION_FILE |
--MqttOptionFile |
the MQTT option file path. The schema is MQTT.js ClientOptions. (Default: empty) |
MQTT_CA_FILE |
--MqttCaFile |
The MQTT CA file path. If this file exists, it will be loaded and set as an "ca" option. (Default: not load) |
MQTT_CERT_FILE |
--MqttCertFile |
The MQTT cert file path. If this file exists, it will be loaded and set as an "cert" option. (Default: not load) |
MQTT_KEY_FILE |
--MqttKeyFile |
The MQTT key file path. If this file exists, it will be loaded and set as an "key" option. (Default: not load) |
MQTT_BASE_TOPIC |
--MqttBaseTopic |
MQTT topic prefix. (Default:"echonetlite2mqtt/elapi/v2/devices") |
REST API Options
| Environment Variables | Commandline Parameter | Description |
|---|---|---|
REST_API_HOST |
--RestApiHost |
Host IP of the administrator page. If there are multiple IPs, specify them. (Default: 0.0.0.0) |
REST_API_PORT |
--RestApiPort |
Admin page port number. (Default: 3000) |
REST_API_ROOT |
--RestApiRoot |
Rest API url prefix. (Default: empty) |
REST_API_SERVER_SENT_EVENT_METHOD |
--RestApiServerSentEventMethod |
Specifies how server events are sent on the web page. The default is WebSocket, and specifying 1 will enable long polling. If the web page does not refresh automatically, try 1. (Default: WebSocket) |
ECHONET Lite Options
| Environment Variables | Commandline Parameter | Description |
|---|---|---|
ECHONET_TARGET_NETWORK |
--echonetTargetNetwork |
Specify the network for ECHONET Lite in the format "000.000.000.000/00". (Default: Auto) |
ECHONET_DEVICE_IP_LIST |
--echonetDeviceIpList |
Specify the device IPs separated by commas. (Default: none) |
ECHONET_COMMAND_TIMEOUT |
--echonetCommandTimeout |
Specify the timeout for ECHONET Lite commands. (Unit: ms) (Default: 3000) |
ECHONET_DISABLE_AUTO_DEVICE_DISCOVERY |
--echonetDisableAutoDeviceDiscovery |
Disable automatic device discovery. (default: off) |
ECHONET_ALIAS_FILE |
--echonetAliasFile |
The file path for alias option file. (Defalt: not use) |
ECHONET_LEGACY_MULTI_NIC_MODE |
--echonetLegacyMultiNicMode |
Revert to legacy communication mode. (Default: off) |
ECHONET_UNKNOWN_AS_ERROR |
--echonetUnknownAsError |
Specifies whether to treat unknown classes and unknown properties as errors. (Default: off) |
ECHONET_USER_CUSTOM_MRA_FOLDER |
--echonetUserCustomMraFolder |
Specifies the folder path for user custom MRA files. (Default: not use) |
ECHONET_INTERVAL_TO_GET_PROPERTIES |
--echonetIntervalToGetProperties |
(Deprecated since v3.0.0) |
ECHONET_ALT_MULTI_NIC_MODE |
--echonetAltMultiNicMode |
(Deprecated since v3.0.0) |
You can alias device Ids using ECHONET_ALIAS_FILE ( or --echonetAliasFile ) option.
This option specifies the path of the Alias Option File.
The Alias Option File is a Json file with the following format:
{
"aliases":[
{
"name":"living_aircon",
"eoj":"0130*",
"ip":"192.168.1.48"
},
{
"name":"bedroom_aircon",
"id":"fe0000251c4190000081e5bb0000000000"
}
]
}
| Property | Description |
|---|---|
| name | [Required] Name of device to be used instead of ID |
| ip | IP address to identify device. * can be used as wildcard. |
| eoj | ECHONET Lite object ID to identify device. * can be used as wildcard. |
| id | ID to identify device. * can be used as wildcard. |
An alias is selected if all of the ip, eoj, and id conditions are met. If there are multiple matches, the first match takes precedence.
the major changes from version 1.x to version 2.x:
- (1) Default MQTT topic name changed from "echonetlite2mqtt/elapi/v1" to "echonetlite2mqtt/elapi/v2".
- (2) The Id has changed on some devices.
- (3) The property "schema" specification changed.
- (4) Redesigned the web front end.
If you want to keep compatibility with version 1.x as much as possible, you can use the MQTT_BASE_TOPIC (or --MqttBaseTopic ) option for (1) and the ECHONET_ALIAS_FILE ( or --echonetAliasFile ) option for (2).
docker run -d --net=host -e MQTT_BROKER="mqtt://your.mqtt.brocker" -e MQTT_BASE_TOPIC="echonetlite2mqtt/elapi/v1/devices" -e ECHONET_ALIAS_FILE=/app/configure/alias.json -v (some folder):/app/configure banban525/echonetlite2mqtt
or
npm start -- --MqttBroker "mqtt://your.mqtt.brocker" --MqttBaseTopic "echonetlite2mqtt/elapi/v1/devices" --echonetAliasFile ./alias.json
If your execution environment has multiple IPs, try the environment variable ECHONET_TARGET_NETWORK and ECHONET_ALT_MULTI_NIC_MODE. (when use Node.js, the command line parameter --echonetTargetNetwork and --echonetAltMultiNicMode)
- for Docker:
-e ECHONET_TARGET_NETWORK="192.168.1.0/24" -e ECHONET_ALT_MULTI_NIC_MODE=1 - for Node.js:
--echonetTargetNetwork "192.168.1.0/24" --echonetAltMultiNicMode
You can reload the properties on the web screen. If you can reload from the web screen, you can manually update the properties by sending an MQTT topic.
For example, if you want to update the room temperature value of an air conditioner, send the following MQTT topic. (Replace "fe00-your-device-id-00000000000000" with your device ID.)
echonetlite2mqtt/elapi/v2/devices/fe00-your-device-id-00000000000000/properties/roomTemperature/request
This is not possible as the ECHONET Lite "Set temperature value" (ja:温度設定値) specification is in units of 1 degree.
See specs below.
ECHONETLite2MQTT uses Echonet lite Machine Readable Appendix (MRA) as a device definition.
However, you may want to use a device class that is not in MRA, or a manufacturer-specific extension.
You can use a user-defined MRA by specifying a folder with the environment variable ECHONET_USER_CUSTOM_MRA_FOLDER ( --echonetUserCustomMraFolder ).
Example: For air conditioner (eoj=0x0130)
- for Docker:
-e ECHONET_USER_CUSTOM_MRA_FOLDER=/(your-folder)/MY_MRA/ - for Node.js:
--echonetUserCustomMraFolder "/(your-folder)/MY_MRA/"
/(your-folder)/MY_MRA/0x0130.json
{
"eoj": "0x0130"
...
}
For the file format, please refer to Echonet lite Machine Readable Appendix (MRA). Also, Json Schema is provided in "MraTypes.schema.json".
- The images in the repository use materials such as "いらすとや" (https://www.irasutoya.com/).
- Machine Readable Appendix (MRA) Version 1.3.1 is used as the definition of ECHONET Lite. (https://echonet.jp/spec_mra_rr3/)