Scent Engine Remote Control

A touchscreen remote control for an 8-slot Scent Engine by ScentedRealms, built with CircuitPython on an ESP32 CYD "Cheap Yellow Display".

Why build this? By default, the ScentedRealms hardware exposes a hardcoded WiFi SSID and a captive portal web interface. To control it, you have to connect your phone or computer directly to the machine's network, which temporarily disconnects you from the internet.

This dedicated remote solves that problem. It connects directly to the Scent Engine's WiFi and sends the necessary HTTP commands (extracted from the original web interface) behind the scenes. This frees up your phone and computer for normal use while giving you a dedicated, always-on physical control panel for the diffuser.

Technical note: This project uses a pre-rendered background image to keep RAM usage low, avoiding out-of-memory errors common with standard UI libraries on ESP32 devices.

Hardware

• Board: Sunton ESP32-2432S028 (CYD with separate SPI for touch)
• Display: 320x240 ILI9341 TFT Touchscreen
• Firmware: CircuitPython 10.0.3

How to Install and Edit

If you are new to microcontrollers, the easiest way to edit the code and transfer files is using a free program called Thonny.

1. Initial Board Setup (Circuitpython)

1. Download the board's firmware:adafruit-circuitpython-sunton_esp32_2432S028-en_GB-10.0.3.bin
2. Download and install Thonny.
3. In Thonny's Tools menu, select Options, then the Interpreter tab, then esptool in the bottom right corner.
4. At the bottom of the window, press = and then Select local image. Select the firmware file from step 1 above, then select ESP32.
5. Connect the board to your computer via USB. For me, mini USB worked better than USB C.
6. On the board, press the BOOT button and keep it pressed while pressing the reset (RST) button. Release both.
7. In Thonny, press Install. Installation will take a couple of minutes.
8. In the bottom right corner, click the current interpreter name and select CircuitPython (generic).

2. Transferring Files

Important: Do not use Thonny's "Manage Packages" menu to install libraries. That installs heavy PC versions of code that will crash your board. Always transfer the .mpy files directly.

Patience: The processor is slow and changes may not appear immediately. Rebooting also takes its time.

1. In Thonny, go to View > Files.
2. Press the STOP button (or Ctrl-F2, or in the Run menu, select Stop/Restart Backend).
3. Wait until the log stabilizes and the files of the device appear below the local files (top).
4. In the local files view, navigate to the project files you downloaded from this repository.
5. Upload the following to your device's root directory (right-click -> Upload to /):
   • code.py (The main program)
   • scent_engine.py (The hardware controller logic)
   • bg.bmp (The user interface graphics)
   • settings.toml (Wifi settings pointing to the scent engine)
6. Create a folder named lib on your device and double-click it to enter it.
7. Upload the contents of this repository's lib folder into your device's lib folder.

3. Customizing the Background Graphic

The entire user interface (the grid, the icons, the button labels) is just a standard image file.

1. Open bg.bmp in Photoshop, GIMP, or any image editor.
2. The layout relies on a strict grid:
   • Row 1 (Y: 0-80px): Slots 1-4
   • Row 2 (Y: 80-160px): Slots 5-8
   • Row 3 (Y: 160-240px): Action Buttons (Switch on Left, Activate on Right)
3. Make your design changes.
4. Crucial Export Settings: Save the file as a 320x240 pixel BMP. For the best performance on the ESP32, export it as a 16-bit (R5 G6 B5) or standard 24-bit BMP with no compression.
5. Use Thonny to overwrite the old bg.bmp on your device with your new one.

---

Credits & Licenses

• Code Assistance & Troubleshooting: Gemini
• The hardware drivers and UI libraries included in the lib folder are part of the Adafruit CircuitPython Bundle. They are licensed under the MIT License. Copyright (c) Adafruit Industries.