Yokis-hack is a project around the reverse engineering of Yokis devices, a french company building stuff for home automation. I started this project to better automate my own installation and to better understand the proprietary protocol driving my stuff :) !
Two devices interested me:
- MTV500ER (a dimmer)
- MTR2000ER (a switch)
Beware if you want to buy, MTV500E and MTR2000E are not driven using RF !
If you are interested, you can look at the reverse engineering documentation.
This firmware can be compiled and installed on the following devices:
- Arduino
- ESP8266
The following Yokis devices are supported:
- MTV500ER(P)
- MTR2000ER(P)
- MTR2000MR(P)
- MVR500ER
Configuration storage (ESP8266 devices only) has changed (from SPIFFS to LittleFS) as of version 1.2. As a result, before upgrading, copy your old configuration to be able to restore it afterward.
- Carefully copy the result of the following command:
dSpiffs
-
Upgrade to v1.2. Your conf has now been erased.
-
Restore all your devices one at a time using the following command:
dRestore <line>
example:
dRestore lamp|6f4d|2d|00|00|490020|9f84|0000
- Make a backup of your configuration using the command
dConfigFS(copy the content of the command's result somewhere safe) - Upgrade using OTA or with
esptools.py - In case of issue with your config, restore it line by line using the command
dRestore - In case of weird bug (module stops functioning, weird stuff in the Serial, etc.), you need to completely erase the flash of the ESP8266 and reburn the firmware.
Erase can be done with:
esptool.py -p /dev/<serial_port> erase_flash
- MCU (Arduino, ESP8266)
- NRF24L01+ (NRF24L01 should also work)
Remember that the NRF24 chip must be powered with 3.3V !! It supports 5V on SPI though.
I used a small adapter to better regulate power to the NRF24L01+ easily found on eBay.
CE, CS and IRQ are specific to my implementation.
For SPI wiring, use your usual device ports.
| Arduino | ESP8266 | |
|---|---|---|
| CE | 7 | D2 |
| CS | 8 | D8 |
| IRQ | 20 | D1 |
Wiring IRQ pin is not optional !
For example, here are the pinout of my testing MCUs:
| Wemos D1 mini | Arduino Mega | |
|---|---|---|
| CLK | D5 | 52 |
| MOSI | D7 | 51 |
| MISO | D6 | 50 |
See releases.
Tools needed: https://github.com/espressif/esptool
Upload the binary file to your ESP using esptools.py like so:
esptool.py -p /dev/<serial_port> write_flash -fm dio 0x00000 /path/to/yokis-hack.bin
- Once uploaded and restarted, a new wifi network appears (named
YokisHack-XXXXXX), connect to it. - Open your browser to the following IP address: http://192.168.4.1
- Configure WiFi and optionally MQTT.
Once applied, you need to switch back to your WiFi. ESP gets its IP from DHCP so you have to figure out which ip it has now...
Then, to continue further (pairing devices, etc.), you can telnet to the ESP using its IP:
telnet <ip_address>
Note: It is also possible to configure everything using serial directly (with minicom for example).
The following commands can help:
> help
> wifiConfig
> wifiDiag
> mqttConfig
> mqttDiag
If you use Arduino, a very small set of features are available. Use an ESP8266 for all connectivity features (WiFi and MQTT).
The following features are available:
- Command line interface over serial (115200 bauds)
- Web UI to configure WiFi and MQTT
- Serial over Telnet connection
- OTA upgrades
- Home Assistant auto discovery (with prefix
/homeassistantas describe on Home Assistant documentation)
From serial, one can use the following commands:
Note: To use telnet, just get the ip address of the device and use telnet <ip> to get the serial commands over Telnet.
Note: When you pair a device, its configuration is stored and can be use for various commands if you don't pass any device_name as parameter. If you pair a new device, it replaces the stored configuration.
| command | paramters | help |
|---|---|---|
help |
Display all commands available | |
debug |
Toggle debug mode | |
raw |
Toggle raw output (output from pairing command will not be formatted) - deprecated | |
poll |
Toggle the option to poll all the configured devices for their status and publish them over MQTT | |
config |
Display configuration flags state | |
pair |
Add a new device (emulate the pairing process) - it's like pressing a button's remote 5 times | |
toggle |
[device_name] |
Toggle the state of a device |
scan |
[device_name] |
scan for packet |
copy |
[device_name] |
Copy a device - send the payload corresponding the device to pair |
dConfig |
Display all loaded devices information | |
on |
[device_name] |
Switch on a device |
off |
[device_name] |
Switch off a device |
pause |
[device_name] |
Pause the configured device (MVR500 only - shutter device) |
press |
[device_name] |
Emulate a button press (and hold) - this is mostly used for debugging |
pressFor |
device_name duration |
Emulate a button press and hold for a duration (dimmers only) |
release |
[device_name] |
Emulate a button release - this is mostly used for debugging |
status |
[device_name] |
Get device status |
dimmem |
[device_name] |
Only for dimmers - Set to dimmer memory (1 button press) |
dimmin |
[device_name] |
Only for dimmers - Set the dimmer to minimum light (4 button presses) |
dimmax |
[device_name] |
Only for dimmers - Set the dimmer to 100% light (2 button presses) |
dimmid |
[device_name] |
Only for dimmers - Set the dimmer to 50% light (3 button presses) |
dimnil |
[device_name] |
Only for dimmers - Set the dimmer night light mode (7 button presses) |
save |
device_name |
Persist the current device to internal ESP memory (LittleFS) |
delete |
device_name |
Delete one entry from the internal ESP memory (LittleFS) |
clear |
Clear all config previously stored to LittleFS | |
reload |
Reload config from LittleFS to memory | |
dConfigFS |
display config previously stored in LittleFS | |
dRestore |
config_line |
restore a previously saved raw config line |
wifiConfig |
ssid password |
Configure wifi with parameters: ssid psk (does not work for psk containing spaces) |
wifiDiag |
Display wifi configuration debug info | |
wifiReset |
Reset wifi configuration and setup AP mode | |
restart |
Restart the ESP8266 board | |
mqttConfig |
ip port user pass |
Configure MQTT options (format: mqttConfig host port username password) |
mqttDiag |
Display current MQTT configuration | |
mqttConfigDelete |
Delete current MQTT configuration |
You need to use the serial or web ui for initial configuration. Commands are only available through serial.
On the serial, use the pair command for each device you want to store and save it to config:
pair- click on the connect button on the back of the device
save <device_name>reload
Instead of pressing the connect button at the back of the device which is sometimes not accessible. You can use an already paired remote:
- use the
paircommand like before - press a remote's button for more than 3 seconds
To (re)configure a genuine yokis remote, use the copy command like so:
- put the remote in pairing mode (5 short presses on a button)
- use the
copycommand from the serial
Published topics:
- Auto discovery uses Home Assistant prefix:
homeassistant/. - Device's state is sent using the following topic patterns:
<device_name>/tele/LWT={Online,Offline}<device_name>/tele/STATE={"POWER":"On"}or{"POWER":"Off"}<device_name>/tele/BRIGHTNESS={"BRIGHTNESS":"value"}wherevalueis0,1,2,3or4.3and4are the same and set the device to MAX brightness.
Subscribed topics:
<device_name>/cmnd/POWER:ONorOFF<device_name>/cmnd/BRIGHTNESS:0,1,2,3or4
- Install platform.io
- Compile with the following command (for ESP8266):
pio run -e d1_mini -t upload
Resulting firmwares can be uploaded to any supported device.
Firware location depends on the device:
- Arduino Mega firmware location:
.pio/build/megaatmega2560/firmware.elf - ESP8266 firmware location:
.pio/build/d1_mini/firmware.bin
To configure the ESP8266 build, use the following command:
MQTT_IP="<MQTT_IP>" \
MQTT_PORT="<MQTT_PORT>" \
MQTT_USERNAME="<MQTT_USERNAME>" \
MQTT_PASSWORD="<MQTT_PASSWORD>" \
WIFI_SSID="<SSID>" \
WIFI_PASSWORD="<WIFI_KEY>" \
pio run -e d1_mini [-t upload]
First upload has to be done using an usb cable. However, all subsequent upgrades can be done using OTA as such (use d1_mini_ota instead of d1_mini):
MQTT_IP="<MQTT_IP>" \
MQTT_PORT="<MQTT_PORT>" \
MQTT_USERNAME="<MQTT_USERNAME>" \
MQTT_PASSWORD="<MQTT_PASSWORD>" \
WIFI_SSID="<SSID>" \
WIFI_PASSWORD="<WIFI_KEY>" \
pio run -e d1_mini_ota --upload-port=<ip_address> -t upload