yokis-hack

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.

Hardware compatibility

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

Upgrading

To v1.2

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.

1. Carefully copy the result of the following command:

   dSpiffs

2. Upgrade to v1.2. Your conf has now been erased.

3. Restore all your devices one at a time using the following command:

   dRestore <line>

example:

dRestore lamp|6f4d|2d|00|00|490020|9f84|0000

Upgrade general guidelines

• 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

Usage

Hardware needed

• 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.

Wiring and pinout

CE, CS and IRQ are specific to my implementation. For SPI wiring, use your usual device ports.

Wiring IRQ pin is not optional !

For example, here are the pinout of my testing MCUs:

Download and installation

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

Firmware usage

Features

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 /homeassistant as 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.

You need to use the serial or web ui for initial configuration. Commands are only available through serial.

Examples

Pair devices and save configuration

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 pair command like before
• press a remote's button for more than 3 seconds

Program a genuine Yokis remote

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 copy command from the serial

MQTT reference

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"} where value is 0, 1, 2, 3 or 4. 3 and 4 are the same and set the device to MAX brightness.

Subscribed topics:

• <device_name>/cmnd/POWER: ON or OFF
• <device_name>/cmnd/BRIGHTNESS: 0, 1, 2, 3 or 4

Development

• 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