Note: This project is currently under active development. Expect changes and potential issues.
This repository provides a way to program the HOPE XV Electronic Badge (archive) using ESPHome. ESPHome is a powerful yet simple framework for controlling your ESP32-based devices.
By Vinicius Fortuna.
By enabling users to program the badge with ESPHome, this project aims to:
- Simplify Development: ESPHome's YAML-based configuration and built-in components make it easier to get started with custom functionality.
- Increase Accessibility: Lower the barrier to entry for hacking and customizing the HOPE Badge.
- Foster Community: Encourage collaboration and sharing of custom badge configurations.
- Leverage Home Assistant: Integrate the badge into your Home Assistant setup.
GPIO Components
- Tactile Buttons (SW3/SW4/SW1/SW2, GPIO19/GPIO18/GPIO10/GPIO09, ESPHome)
- Green LED (D28, GPIO13, ESPHome)
- WS2812B RGB LED strip (D1-D16, GPIO08, ESPHome)
- IRM-H638 IR receiver (IC1, GPIO03, ESPhome)
- VSMY1850 IR transmitter (D23, GPIO02, ESPHome)
- Vibration motor (GPIO13/SPIWP, ESPHome)
I2C Components
- MAX17048 Battery Sensor (U4, address 0x36, ESPHome)
- Note: We can use the MAX17043 ESPHome component because MAX17048 is a drop-in replacement for MAX17043.
- ST25DV04K Dynamic NFC/RFID tag IC (U6)
- Access to user memory, Dynamic registers or Mailbox: 0x53
- System configuration area: 0x57
- ???: 0x2D
- SGP30 Air Quality Sensor (U7, address 0x58, ESPHome)
- PCF8574 GPIO Expander (U9, ESPHome)
- ATECC608A Cryptographic Co-Processor with Secure Hardware-Based Key Storage (U11)
SPI Components
- Remote Access
- Wifi provisioning
- Web Server controller
- OTA update support
- Add application pages
- Badge screen
- Basic air sensor screen
- QR Code screen. Use the MeCard format for contact info.
- Basic IR Blaster
- LED control and effects
- IR Transmitter/Receiver
- Make it easier to add application pages
- Basic encapsulation of application pages
- Remove need for a focus group per page
- Create selector entry template
- Create page template
- Write documentation on how to flash
- Write documentation on how to add a new page
- Prerequisites:
- A HOPE XV Electronic Badge.
- A computer with ESPHome installed. (See the ESPHome Getting Started Guide)
- USB cable to connect the badge to your computer.
- Customization (Optional):
- Customize the badge to your liking by editing the deployment.yaml configuration file.
- Flashing:
- Connect the HOPE Badge to your computer.
- Use the ESPHome command-line tool to compile and upload your configuration to the badge:
esphome run deployment.yaml
The badge has these conflicts between the tactile buttons and the USB data pins:
- Button 1 (SW3/TACT_C) uses GPIO19, which is shared with USB_D+
- Button 2 (SW4/TACT_D) uses GPIO18, which is shared with USB_D-
The buttons require setting the pin for input, with a pull-down resistor. That breaks the USB connection. As a result, the computer won't even detect the device, preventing flashing and log monitoring.
To successfully flash, you must put it in flash mode:
- Turn off the device
- Hold Button 4 (SW2/TACT_B). This uses GPIO09, the BOOT pin
- Turn on the device
- Release the Button
This will enter flashing mode and prevent the firmware from running and breaking the USB connection.
Once flashing is complete, you won't see any logs, because as soon as the firmware starts, it breaks USB.
Also, the firmware won't run correctly somehow. You need to reset it (turn it off and back on).
If you don't disconnect the USB cable, you will see that buttons 1 and 2 will not work. You must disconnect the cable.
This is the full recipe for successfully flashing:
- Turn off the badge
- Connect the badge via USB
- Turn it on in flash mode
- Flash
- Disconnect from USB
- Turn it off and back on
Contributions are welcome! If you have ideas, bug fixes, or new features, please open an issue or submit a pull request.
ESP32-C3 Pin Usage on Hope Badge
Here is a table summarizing the ESP32-C3 pins based on the ESP32-C3 datasheet and the badge schematic. The "Usage in Badge" column details how the pin is connected in the schematic, and "Availability" indicates if the pin is easily accessible for general use on this specific badge design.
| Pin No. | Pin Name (Datasheet) | Usage in Badge (Schematic) |
|---|---|---|
| 1 | LNA_IN | RF Antenna Input |
| 2 | VDD3P3 | +3.3V Power Supply |
| 3 | VDD3P3 | +3.3V Power Supply |
| 4 | XTAL_32K_P / GPIO0 | TFT DC (TFT_DC) |
| 5 | XTAL_32K_N / GPIO1 | TFT Reset (SPI_CS2) |
| 6 | GPIO2 | IR Transmitter (IR_TX) |
| 7 | CHIP_EN | Chip Enable Control |
| 8 | GPIO3 | IR Receiver Input (IR_RX) |
| 9 | MTMS / GPIO4 | TFT Chip Select (SPI_CS1) |
| 10 | MTDI / GPIO5 | SPI Data In (SPI_SDI) |
| 11 | VDD3P3_RTC | +3.3V RTC Power Supply |
| 12 | MTCK / GPIO6 | SPI Clock (SPI_SCK) |
| 13 | MTDO / GPIO7 | SPI Data Out (SPI_SDO) |
| 14 | GPIO8 | RGB LED Data (RGB_DAT) |
| 15 | GPIO9 / BOOT | Tactile Button 4 (SW2, TACT_B) |
| 16 | GPIO10 | Tactile Button 3 (SW1, TACT_A) |
| 17 | VDD3P3_CPU | +3.3V CPU Power Supply |
| 18 | VDD_SPI / GPIO11 | SPI Flash Power Supply |
| 19 | SPIHD / GPIO12 | Vibration Motor (VIBRAMOTOR) |
| 20 | SPIWP / GPIO13 | LED (D28) |
| 21 | SPICS0 / GPIO14 | Internal Flash Chip Select |
| 22 | SPICLK / GPIO15 | Internal Flash Clock |
| 23 | SPID / GPIO16 | Internal Flash Data Out (MOSI) |
| 24 | SPIQ / GPIO17 | Internal Flash Data In (MISO) |
| 25 | GPIO18 / USB_D- | Tactile Button 2 (SW4, TACT_D) |
| 26 | GPIO19 / USB_D+ | Tactile Button 1 (SW3, TACT_C) |
| 27 | U0RXD / GPIO20 | I2C SDA (I2C_SDA) |
| 28 | U0TXD / GPIO21 | I2C SCL (I2C_SCL) |
| 29 | XTAL_N | Main Crystal Input |
| 30 | XTAL_P | Main Crystal Output |
| 31 | VDDA | Analog Power Supply |
| 32 | VDDA | Analog Power Supply |
| 33 | GND | Ground |
Note: Based on the schematic analysis, all ESP32-C3 pins are utilized for specific functions within the Hope Badge circuit, and none appear to be readily available as unallocated GPIOs for general user experimentation without modifying the board.
Information derived from esp32-c3_datasheet_en.pdf and hopebadgeschema-0.8.19.pdf.
You can find the original Hacking in Parallel Badge firmware in their official repository.
You can flash WLED. See WLED Instructions.
You can also flash MicroPython. See MicroPython Instructions.
For both WLED and MicroPython you can't use buttons 1 and 2 due to the USB conflict.
- HOPE XV Electronic Badge Wiki
- HOPE XV Electronic Badge User Manual
- HOPE XV Badge Schematics
- Blinkenlights Pinout
- Blinkenlights Firmware
- Infrared trigger:
- Encoding:
NECext - Address:
0xD880 - Command:
0xDD22
- Encoding: