FernoPy

FernoPy enables the control of Rademacher FernoTron devices (shutters) conveniently via a web interface and REST-API.

Features

Responsive web interface
REST-API (Home Assistant, ioBroker, openHAB support)
Unlimited number of devices
The original FernoTron remote control can be used alongside FernoPy
Quick and easy to set up
Cheap (total cost of only 10€)
Covers a whole medium-sized house
ESP32 / ESP8266 support
Written in MicroPython
Protocol documentation

ℹ️ Only the basic control of devices is supported (up / down / stop). If you want to program devices please use: tronferno-mcu

Overview

The web interface (left figure) is provided directly via the web server of the ESP. The design and functionality of the interface is based on the original FernoTron remote control.

The upper left button switches between light and dark mode (dark mode is not yet implemented)
The upper right button is used to switch between multiple remote controls. You can configure as many remote controls as you like, allowing you to control an unlimited number of devices via FernoPy. However, the maximum number of groups and participants per remote control still exist in FernoPy (7 groups with 7 devices each).
The left two buttons control the group number and the right ones the device number (also called member). Each group and device can be assigned a name.
The lower three buttons are used to control the shutters.

REST-API

FernoPy can be integrated into other programs by using its REST-API. This allows you to connect the shutters to central smart home systems such as Home Assistant, ioBroker or openHAB.

`/api/config`

This URI can be used to query all available remote controls with their groups and the respective devices by using the GET method. To be more precise: The data of the fernotron dictionary in the tx_config.py file is returned (without the device types and id).

$ curl -X GET http://<YOUR_ESP_IP>/api/config
{"remotes": [
	[
		{"name": "All", "members": ["All"]}, 
		{'name': 'Living room', 'members': ['All', 'North', 'East', 'South', 'West']},
		...
	], 
	[
		...
	],
]}

`/api/cmd`

This URI can be used to transmit control messages to the shutters by using the POST method. Requests with the content-type application/json and application/x-www-form-urlencoded are supported. Group and member numbers 0-7, where 0 represents all. The available commands are up, down and stop.

# application/json
$ curl -d '{"remote":0, "member":2, "group":5, "cmd":"down"}' -H "Content-Type: application/json" -X POST http://<YOUR_ESP_IP>/api/cmd

# application/x-www-form-urlencoded
$ curl -d 'remote=0&member=2&group=5&cmd="down"' -X POST http://<YOUR_ESP_IP>/api/cmd

Hardware requirements

You only need an ESP32 / ESP8266 and a 433 MHz transmitter + receiver set. The functionality of FernoPy was tested with a Wemos D1 mini clone and the cheapest transmitter + receiver set from amazon.

Part	Amazon query	Cost	Specific type	Data sheet
433 MHz receiver + transmitter	DE	2€	XY-MK-5V / XD-RF-5V / FS1000A	Archive
Wemos D1 mini (ESP8266)	DE	4€	-	Archive

When buying the transmitter + receiver set, there is something to consider:
The transmitters in each set are basically the same and all work equally well. However, there are differences with the receivers. There are ones with a tunable inductor (small coil with a screw) and ones with a crystal oscillator (small metallic box). Receivers with a tunable inductor have a greater noise component, which makes it more difficult to receive a valid messages. However, testing has shown that these are sufficient for FernoPy, especially considering that the receiver is only needed once for the initial setup and not for normal operation. Receivers with a crystal oscillator (also called superheterodyne) can nevertheless simplify the initiation phase in some cases.

Installation Linux (recommended)

Click to see the complete installation instructions

0. Flash MicroPython

Before FernoPy can be installed, the MicroPython firmware must be flashed onto the micro controller. If MicroPython is already running on your micro controller you can skip this step. A more detailed tutorial can be found here.

Install the esptool CLI.
```
pip install esptool
```
Download the appropriate firmware for the micro controller here. The file must be in binary format (.bin).
Connect the micro controller to your PC.
Now find out which device file is used to communicate with the micro controller. By default it should be /dev/ttyUSB0. Alternatively, you can also determine it via the command: sudo dmesg | grep tty. The output should look similar like this and give you information about the used file.
```
$ sudo dmesg | grep tty
[435144.714226] usb 1-1: ch341-uart converter now attached to ttyUSB0
```

Erase the flash of the micro controller.

esptool.py --port /dev/ttyUSB0 erase_flash

Flash the MicroPython firmware.

esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dout 0 ESP8266_GENERIC-20231005-v1.21.0.bin

Port and the name of the firmware should of course be changed by you as needed.

1. Obtain the device ID

⚠️ You can also find the ID on a sticker in the battery compartment of the remote control. The batteries must be removed for this.

1.1 Prepare FernoPy

Install the mpremote CLI.
```
pip install --user mpremote
```

Clone the FernoPy repository.

git clone https://github.com/prefixFelix/fernopy.git

Connect the micro controller to your PC.
Verify that MicroPython is running properly on your micro controller by accessing the REPL prompt.
```
mpremote connect /dev/ttyUSB0 repl
```

1.2 Sniff the device ID

The shutters are normally controlled by a 2411 Rademacher remote control. The remote has a unique identification number, which is required for the operation of FernoPy.

Connect the micro controller to the 433 MHz receiver as shown below:

Micro controller 433 MHz receiver

GND GND

5V VCC

GPIO5 DATA

GPIO5 is the standard pin for the data connection. If you want to use another one you have to change it in the file /src/rx/rx_config.py.
Connect the micro controller to your PC.
Run the sniffing install script and follow the given instructions.
```
python3 1-rx-install.py /dev/ttyUSB0
```
⚠️ The recording should ideally not take place in the vicinity of possible sources of interference, such as radio weather stations that also transmit on 433 MHz. The distance between the PC and the micro controller should also be maximized for the same reason (what the USB cable can offer). Also micro controller and receiver should not be next to each other. Compare your setup with this illustration.

⚠️ The antenna of the receiver should be parallel to the left side of the remote control. Vertically, the antenna should be in the lower third of the remote control. The distance between the remote control and the antenna should be as small as possible (they can also touch each other). Compare your placement with this illustration.

ℹ️ If the recording does not work even after multiple position changes, you can activate the debug settings in the config file and alter the margin value. For the changes to take effect, the install script must be rerun.

ℹ️ If a MemoryError occurs you can reduce the n_edges value in the config. You may also need to enable debug output there.

Alternative: Sniff via an SDR and Universal Radio Hacker (For experienced users)

If you have a SDR on hand, such as an RTL-SDR, you can also sniff the ID by using the software Universal Radio Hacker. You can find a prepared project in the urh folder. It contains predefined message types and a custom decoder for the FernoTron protocol. The program also allows you to better understand the protocol structure.

2. Install FernoPy

Open the tx configuration file in an editor of your choice.

nano /src/tx/tx_config.py

Enter the ESSID of your home network and the password in the general dict.

# General device configuration
general = {
    'symbol_length': 350,           # in µs
    'tx_pin': 5,                    # GPIO!
    'tx_repeat': 4,                 # MSGs transmitted per command
    'essid': 'YOUR_NETWORK_ESSID',
    'password': 'YOUR_NETWORK_PASSWORD',
    'html_assets': 'assets'         # Path to web assets
}

ℹ️ The symbol length of FernoTron is actually 400µs, but 350µs are used because of the latency of the MC. You may have to adjust this value.

Next, the configuration of your FernoTron remote control must be entered into the fernotron list. Start by entering for each remote the type and id you got from the previous step.

fernotron = [
    {
        # Remote 0
        'device_type': 0x80,    # Add information from the RX scipt here!
        'device_id': 0x1234,	# Add information from the RX scipt here!
		...

Now enter all groups and their devices with their respective names. The index of the groups and devices corresponds to that of the remote control.

⚠️ The first group of a remote control is always the All group! This must not be removed! Likewise, the first device of a group (index 0) must always be All! You can translate the name into your own language if you wish.

...		
		'groups': [
            {
                # Default group. Do not remove!
                'name': 'All',
                'members': ['All']
            },
            {
                # Group 1 - Example
                'name': 'Living room',                          		# Group name
                'members': ['All', 'North', 'East', 'South', 'West']	# Group member names
            },
            {   # Group 2 - Example
                'name': 'Kitchen',
                'members': ['All', 'Street', 'Garden']
            },
			...

Connect the micro controller to the 433 MHz transmitter as as described above in section 1.2.
Connect the micro controller to your PC.
Run the FernoPy install script.
```
python3 2-tx-install.py /dev/ttyUSB0
```
Open the web interface by entering the displayed IP in your browser.

ℹ️ You can save a short cut to FernoPy on the home screen of your smart phone. Instructions can be found here.

Installation Windows

Click to see the complete installation instructions

0. Flash MicroPython

Before FernoPy can be installed, the MicroPython firmware must be flashed onto the micro controller. If MicroPython is already running on your micro controller you can skip this step. A more detailed tutorial can be found here.

Make sure that Python and pip (py -m ensurepip --upgrade) are installed!
Open CMD and Install the esptool CLI.
```
py -m pip install esptool
```
Download the appropriate firmware for the micro controller here. The file must be in binary format (.bin).
Connect the micro controller to your PC.
Open the Windows Device Manager to find out which port the micro controller is using. It should be listed under the item Ports (COM & LPT).

Erase the flash of the micro controller.

py -m esptool.py --port COM4 erase_flash

Flash the MicroPython firmware.

py -m esptool.py --port COM4 --baud 460800 write_flash --flash_size=detect -fm dout 0 ESP8266_GENERIC-20231005-v1.21.0.bin

Port and the name of the firmware should of course be changed by you as needed.

1. Obtain the device ID

⚠️ You can also find the ID on a sticker in the battery compartment of the remote control. The batteries must be removed for this.

1.1 Prepare FernoPy

Install the mpremote CLI.
```
py -m pip install --user mpremote
```

Clone or download the FernoPy repository.

git clone https://github.com/prefixFelix/fernopy.git

Connect the micro controller to your PC.
Verify that MicroPython is running properly on your micro controller by accessing the REPL prompt.
```
py -m mpremote connect COM4 repl
```

1.2 Sniff the device ID

The shutters are normally controlled by a 2411 Rademacher remote control. The remote has a unique identification number, which is required for the operation of FernoPy.

Connect the micro controller to the 433 MHz receiver as shown below:

Micro controller 433 MHz receiver

GND GND

5V VCC

GPIO5 DATA

GPIO5 is the standard pin for the data connection. If you want to use another one you have to change it in the file /src/rx/rx_config.py.
Connect the micro controller to your PC.
Run the sniffing install script and follow the given instructions.

⚠️ A bug in mpremote can cause a UnicodeDecodeError error! The installation is still executed successfully. However, the subsequent outputs are not printed. Please switch to a different serial terminal software. Set the baud to 115200 and press the reset button on the micro controller.
```
py 1-rx-install.py COM4
```
⚠️ The recording should ideally not take place in the vicinity of possible sources of interference, such as radio weather stations that also transmit on 433 MHz. The distance between the PC and the micro controller should also be maximized for the same reason (what the USB cable can offer). Also micro controller and receiver should not be next to each other. Compare your setup with this illustration.

⚠️ The antenna of the receiver should be parallel to the left side of the remote control. Vertically, the antenna should be in the lower third of the remote control. The distance between the remote control and the antenna should be as small as possible (they can also touch each other). Compare your placement with this illustration.

ℹ️ If the recording does not work even after multiple position changes, you can activate the debug settings in the config file and alter the margin value. For the changes to take effect, the install script must be rerun.

ℹ️ If a MemoryError occurs you can reduce the n_edges value in the config. You may also need to enable debug output there.

Alternative: Sniff via an SDR and Universal Radio Hacker (For experienced users)

If you have a SDR on hand, such as an RTL-SDR, you can also sniff the ID by using the software Universal Radio Hacker. You can find a prepared project in the urh folder. It contains predefined message types and a custom decoder for the FernoTron protocol. The program also allows you to better understand the protocol structure.

2. Install FernoPy

Open the tx configuration file /src/tx/tx_config.py.

Enter the ESSID of your home network and the password in the general dict.

# General device configuration
general = {
    'symbol_length': 350,           # in µs
    'tx_pin': 5,                    # GPIO!
    'tx_repeat': 4,                 # MSGs transmitted per command
    'essid': 'YOUR_NETWORK_ESSID',
    'password': 'YOUR_NETWORK_PASSWORD',
    'html_assets': 'assets'         # Path to web assets
}

ℹ️ The symbol length of FernoTron is actually 400µs, but 350µs are used because of the latency of the MC. You may have to adjust this value.

Next, the configuration of your FernoTron remote control must be entered into the fernotron list. Start by entering for each remote the type and id you got from the previous step.

fernotron = [
    {
        # Remote 0
        'device_type': 0x80,    # Add information from the RX scipt here!
        'device_id': 0x1234,	# Add information from the RX scipt here!
		...

Now enter all groups and their devices with their respective names. The index of the groups and devices corresponds to that of the remote control.

⚠️ The first group of a remote control is always the All group! This must not be removed! Likewise, the first device of a group (index 0) must always be All! You can translate the name into your own language if you wish.

...		
		'groups': [
            {
                # Default group. Do not remove!
                'name': 'All',
                'members': ['All']
            },
            {
                # Group 1 - Example
                'name': 'Living room',                          		# Group name
                'members': ['All', 'North', 'East', 'South', 'West']	# Group member names
            },
            {   # Group 2 - Example
                'name': 'Kitchen',
                'members': ['All', 'Street', 'Garden']
            },
			...

Connect the micro controller to the 433 MHz transmitter as as described above in section 1.2.
Connect the micro controller to your PC.
Run the FernoPy install script.

⚠️ A bug in mpremote can cause a UnicodeDecodeError error! The installation is still executed successfully. However, the subsequent outputs are not printed. Please switch to a different serial terminal software. Set the baud to 115200 and press the reset button on the micro controller.
```
py 2-tx-install.py COM4
```
Open the web interface by entering the displayed IP in your browser.

ℹ️ You can save a short cut to FernoPy on the home screen of your smart phone. Instructions can be found here.

Credits

Protocol documentation - tronferno-mcu (Bert Winkelmann)
Web server - Nanoweb (Charles R.)
Signal processing - Micropython Remote (Peter Hinch)
Logo - Flaticon

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
img		img
src		src
urh		urh
.gitignore		.gitignore
1-rx-install.py		1-rx-install.py
2-tx-install.py		2-tx-install.py
PROTOCOL.md		PROTOCOL.md
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

FernoPy

Features

Overview

REST-API

`/api/config`

`/api/cmd`

Hardware requirements

Installation Linux (recommended)

0. Flash MicroPython

1. Obtain the device ID

1.1 Prepare FernoPy

1.2 Sniff the device ID

Alternative: Sniff via an SDR and Universal Radio Hacker (For experienced users)

2. Install FernoPy

Installation Windows

0. Flash MicroPython

1. Obtain the device ID

1.1 Prepare FernoPy

1.2 Sniff the device ID

Alternative: Sniff via an SDR and Universal Radio Hacker (For experienced users)

2. Install FernoPy

Credits

About

Releases

Packages

Languages

Micro controller	433 MHz receiver
GND	GND
5V	VCC
GPIO5	DATA

Micro controller	433 MHz receiver
GND	GND
5V	VCC
GPIO5	DATA

prefixFelix/FernoPy

Folders and files

Latest commit

History

Repository files navigation

FernoPy

Features

Overview

REST-API

/api/config

/api/cmd

Hardware requirements

Installation Linux (recommended)

0. Flash MicroPython

1. Obtain the device ID

1.1 Prepare FernoPy

1.2 Sniff the device ID

Alternative: Sniff via an SDR and Universal Radio Hacker (For experienced users)

2. Install FernoPy

Installation Windows

0. Flash MicroPython

1. Obtain the device ID

1.1 Prepare FernoPy

1.2 Sniff the device ID

Alternative: Sniff via an SDR and Universal Radio Hacker (For experienced users)

2. Install FernoPy

Credits

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

`/api/config`

`/api/cmd`

Packages