karol.kozlowski/esp-genie
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
No description
24 commits 1 branch 0 tags 41 MiB
Find a file
Exact
Karol Kozłowski 2415c8765f
 minor fixes
2025-10-10 17:24:41 +02:00
docs Add PN512 datasheet 2025-10-07 23:24:23 +02:00
esphome abstract some magic numbers to substitutions 2025-10-10 17:24:02 +02:00
img update flash image 2025-10-10 13:31:47 +02:00
README.md minor fixes 2025-10-10 17:24:41 +02:00

README.md

ESP Genie

The Perfume Genie is an aroma diffuser made by Dutch company Rituals. Recently they have been heavily modifying both their API which made home-assistant integration unusable. On top of that recent changes to the application rendered the older Genies (v2.0) unusable (as noticed by me and other users), as the application cannot communicate with the firmware to set up a wireless connection. To avoid having a rather expesive paperweight I reversed engineered as much of the board as I could (the PN512 connection remains a mystery).

Components:

  • CPU: ESP-WROOM-02
  • FAN: Sunon MagLev MF40100V2-1D04U-S99 DC 5V 0,36W (datasheet page: 50)
  • LED: WS2812 type
  • NFC: PN512

ESPHome configuration

The configuration can be found under esphome directory. It is written to mimic the original firmware with minor enchancements:

  • device boots up with white LED and turns blue when connected to wifi
  • there are 5 speeds of the fan (configrable via fan_speed_count substitution)
  • when fan is on LED turns green to indicate operation
  • there is an internal timer that will turn off fan when it reaches either:
    • current runtime setpoint (global: fan_runtime_set)
    • global rutnime max (substitution: fan_runtime_max) - hardcoded to prevent infinite fan runtime
  • if there is less than 5 minutes on the timer (configurable via notify_when_minutes_remaining substitution) the LED will tur yellow to indicate
  • if the device gets disconnected the LED will turn red
  • if a fan stall is detected LED will turn red (threshold hardcoded with fan_stall_threshold substitution default is 5% of the fan nominal speed)
  • rear button sets runtime to 15 minutes

Notes:

  • FIXME: there are some issues with fan PWM module and neopixel for LED - when the PWM is enabled the LED transitions result in random flickering. The workaround is to change the PWM frequency to a lower value (hardcoed to 100Hz - substitution: fan_pwm_frequency_low) while the LED is transitioning. After transition the requency is brought back to a higher values as lower frequencies are audible. Maybe there is a better solution for it, this seems to be working good so far.
  • TODO: higher fan speeds generate noise, original firmware certainly does not run it at max RPM, so I'm considering hardcoding a limit for upper speed, for example 4200 RPM which is audible (substitution: fan_max_allowed_rpm).

Initial flashing

To flash inital ESPHome firmware you need to wire USB to UART converter to the board (see picture below). It is importatnt to pull down IO0 to put the board into UART download mode (page 4 of the datasheet). There is a through-hole nearby (marked below) that you can put "kynar" type wire into and bridge it to any ground point on the board. You also might need to power the board for the flash to succeed (using the micousb connector on the board).

alt text

Once connected to the PC you can flash the initial firmware using the tool of your choice, for example esptool

  • Test connection:

    $ esptool --port /dev/ttyUSB0 chip-id
esptool v5.1.0
Connected to ESP8266 on /dev/ttyUSB0:
Chip type:          ESP8266EX
Features:           Wi-Fi, 160MHz
Crystal frequency:  26MHz
MAC:                08:3a:8d:XX:YY:ZZ

Stub flasher running.

Chip ID: 0x00cbc44f

Hard resetting via RTS pin...

  • Backup factory firmware (optional):

    esptool --port /dev/ttyUSB0  read_flash 0x00000 0x100000 factory.bin
Warning: Deprecated: Command 'read_flash' is deprecated. Use 'read-flash' instead.
esptool v5.1.0
Connected to ESP8266 on /dev/ttyUSB0:
Chip type:          ESP8266EX
Features:           Wi-Fi, 160MHz
Crystal frequency:  26MHz
MAC:                08:3a:8d:XX:YY:ZZ

Stub flasher is already running. No upload is necessary.

Configuring flash size...
Read 1048576 bytes from 0x00000000 in 100.2 seconds (83.7 kbit/s) to 'factory.bin'.

Hard resetting via RTS pin...

  • Flash firmware:

    $ esptool --port /dev/ttyUSB0 write_flash 0x0 rituals-genie-1.bin
Warning: Deprecated: Command 'write_flash' is deprecated. Use 'write-flash' instead.
esptool v5.1.0
Connected to ESP8266 on /dev/ttyUSB0:
Chip type:          ESP8266EX
Features:           Wi-Fi, 160MHz
Crystal frequency:  26MHz
MAC:                08:3a:8d:XX:YY:ZZ

Stub flasher is already running. No upload is necessary.

Configuring flash size...
Flash will be erased from 0x00000000 to 0x0008ffff...
Wrote 587456 bytes (407526 compressed) at 0x00000000 in 37.3 seconds (126.1 kbit/s).
Hash of data verified.

Hard resetting via RTS pin...

Hardware information

Pin assignments

No. Pin Name Functional Description 📖 Notes Implmentation
1 3V3 3.3 V power supply (VDD) It is recommended the maximum output current a power supply provides be of 500 mA or above.
2 EN Chip enable pin. Active high.
3 IO14 GPIO14
HSPI_CLK
4 IO12 GPIO12
HSPI_MISO
5 IO13 GPIO13
HSPI_MOSI
UART0_CTS
6 IO15 GPIO15
MTDO
HSPICS
UART0_RTS		 Pull down. WS2812 LED
7 IO2 GPIO2
UART1_TXD		 Floating (internal pull-up) or pull up.
8 IO0 GPIO0 • UART download: pull down.
• Flash boot: floating or pull up.
9 GND GND
10 IO4 GPIO4 FAN PWM
11 RXD UART0_RXD, receive end in UART download
GPIO3		 SW3 (control)
12 TXD UART0_TXD, transmit end in UART download, floating or pull up
GPIO1
13 GND GND
14 IO5 GPIO5 FAN RPM
15 RST Reset
16 TOUT It can be used to test the power-supply voltage of VDD3P3 (Pin3 and Pin4) and the input power voltage of TOUT (Pin6).
These two functions cannot be used simultaneously.
17 IO16 GPIO16 used for Deep-sleep wake-up when connected to RST pin. SW2 (connect)
18 GND GND

Other

  • B1 - Step-down converter (probably)
  • SW1 - "cold reset" - cuts power to the ESP (indirectly through step-down converter B1)

Test points

No. Connection
TP1 -
TP2 -
TP3 -
TP4 PN512 - AUX1
TP6 PN512 - AUX2
TP6 -
TP7 Vusb
TP8 SW1 (cold reset) - pull-down
TP9 SW3 (control) - pull-down
TP10 SW2 (connect) - pull-down
TP11 5V
TP12 -
TP13 -
TP14 -
TP15 ESP RST (pin 15)
TP16 PN512 - NCS
TP17 FAN RPM
TP18 3V3
TP19 GND
TP20 DTR - connected via R3 (1K) to TP16
TP21 MRT - FAN PWM
TP22 MRT - FAN PWM

References: