MMDVM Display by 13MAD86 / Martin - Use at your own risk.

A touchscreen ESP32 dashboard for monitoring an MMDVM hotspot running Pi-Star or WPSD.

This project connects to your hotspot over Wi-Fi and shows live radio activity, last-heard stations, status information, frequencies, signal quality, and basic device stats on a small TFT display.

This software is intended for amateur radio hotspot monitoring and display use.


***** Features *****
- Live and last-heard view for hotspot traffic
- Support for Pi-Star and WPSD
- Touchscreen interface with multiple pages
- Wi-Fi setup fallback with local AP/web configuration
- Theme color, brightness, and screen rotation options
- Screensaver support
- SD card support for config and flag images
- Optional WAV/audio/sound support, selectable at build time
- ESP32 CYD OTA or huge-app/factory partition mode, selectable at build time
- Windows desktop version support
- Windows batch tools for building and flashing
- and many more...


***** Supported hardware / firmware targets *****

Default firmware build targets:
- ESP32-2432S028R ILI9341       Target: CYD_ILI9341      Firmware prefix: esp32-2432S028R-ILI9341
- ESP32-2432S028R ILI9341 V2    Target: CYD_ILI9341_V2   Firmware prefix: esp32-2432S028R-ILI9341-V2
- ESP32-2432S028R ST7789        Target: CYD_ST7789       Firmware prefix: esp32-2432S028R-ST7789
- JC3248W535C                   Target: JC3248W535C      Firmware prefix: esp32s3-JC3248W535C
- WS8048S043C                   Target: WS8048S043C      Firmware prefix: esp32s3-WS8048S043C
- WS8048S070C                   Target: WS8048S070C      Firmware prefix: esp32s3-WS8048S070C
- EC8048S070C                   Target: EC8048S070C      Firmware prefix: esp32s3-EC8048S070C
- EC8048S070B                   Target: EC8048S070B      Firmware prefix: esp32s3-EC8048S070B
- EC8048S070CT                  Target: EC8048S070CT     Firmware prefix: esp32s3-EC8048S070CT
- WSTOUCHLCD28                  Target: WSTOUCHLCD28     Firmware prefix: esp32s3-WSTOUCHLCD28

Each target can also be built manually by passing the target name to build_firmware.bat.


***** Recommended Windows project layout *****

The batch files are designed for this portable Arduino IDE 2 layout:

C:\ArduinoIDE\Data\Arduino15
C:\ArduinoIDE\Data\Sketchbook
C:\ArduinoIDE\Data\Lib

Recommended project folder:

C:\ArduinoIDE\Project\MMDVM-Display\content

Inside the content folder:

content\build_firmware.bat
content\flash_firmware.bat
content\esptool.exe
content\Makefile
content\partitions.csv
content\partitions_ota.csv
content\mmdvm-display\mmdvm-display.ino
content\firmware\
content\sdcard\
content\svxlink\

Partition files:

content\partitions_ota.csv
  ESP32 CYD 4 MB OTA layout. This creates app0/app1 OTA slots.

content\partitions.csv
  ESP32 CYD 4 MB factory/huge-app layout. This creates one large app partition and does not support OTA.

The Arduino CLI is expected from Arduino IDE 2. The batch file will search common locations, including:

C:\ArduinoIDE\resources\app\lib\backend\resources\arduino-cli.exe

If your Arduino CLI is somewhere else, set it before running the build file:

set "ARDUINO_CLI=C:\path\to\arduino-cli.exe"
build_firmware.bat --check


***** Building on Windows *****

Use build_firmware.bat for building only. Flashing is done with the separate flash_firmware.bat file.

Double-click:

build_firmware.bat

Menu:

1) Build firmware for all displays
2) Build Windows desktop version only
3) Build firmware for all displays + desktop
4) Install/update Arduino ESP32 core and libraries
5) Check paths/configuration
6) Toggle sound on/off
7) Toggle ESP32 partition: OTA / Factory
0) Exit

Default build options:

Sound support: enabled
ESP32 partition: ota

First-time setup:

build_firmware.bat --install

Check paths/configuration:

build_firmware.bat --check

Build firmware for all default display targets:

build_firmware.bat --firmware-only

Build Windows desktop version only:

build_firmware.bat --desktop-only

Build firmware and desktop version:

build_firmware.bat --all

Build one display target only:

build_firmware.bat WS8048S070C
build_firmware.bat CYD_ILI9341
build_firmware.bat CYD_ILI9341_V2
build_firmware.bat CYD_ST7789
build_firmware.bat EC8048S070B

Build CYD for OTA without sound, recommended when the firmware is close to the OTA size limit:

build_firmware.bat --no-sound --ota CYD_ST7789
build_firmware.bat --no-sound --ota CYD_ILI9341

Build CYD for OTA with sound:

build_firmware.bat --sound --ota CYD_ST7789
build_firmware.bat --sound --ota CYD_ILI9341

Build CYD with the huge-app/factory partition, no OTA:

build_firmware.bat --sound --factory CYD_ST7789
build_firmware.bat --no-sound --factory CYD_ILI9341

Alternative partition option syntax:

build_firmware.bat --partition ota CYD_ST7789
build_firmware.bat --partition factory CYD_ST7789

Temporary Arduino build folders are created under:

content\_build_work

The script removes temporary build folders after a successful build so the firmware folder stays clean.

Firmware output goes here:

content\firmware

Example output files:

content\firmware\esp32s3-WS8048S070C.bin
content\firmware\esp32s3-WS8048S070C.boot.bin
content\firmware\esp32s3-WS8048S070C.bootloader.bin
content\firmware\esp32s3-WS8048S070C.partitions.bin

For the ESP32-S3 targets, some builds may not generate a .boot.bin file. The flash tool handles this automatically.


***** Optional sound support *****

Sound is controlled at compile time with this build flag:

MMDVM_ENABLE_SOUND

The build tool sets it automatically:

--sound
  Builds with WAV/audio/sound support. This is the default.

--no-sound
  Builds without WAV/audio/sound support. This reduces firmware size and is useful for ESP32 CYD OTA builds.

Examples:

build_firmware.bat --sound CYD_ST7789
build_firmware.bat --no-sound CYD_ST7789
build_firmware.bat --no-sound --ota CYD_ILI9341

Important:

The firmware source must support the MMDVM_ENABLE_SOUND flag. If the source code does not contain the optional-sound guards yet, the batch option will still pass the flag, but the code size will not be reduced correctly.


***** ESP32 CYD partition modes *****

The original ESP32 CYD boards use 4 MB flash. Because of this, OTA and huge firmware builds need different partition layouts.

OTA mode:

build_firmware.bat --ota CYD_ST7789
build_firmware.bat --ota CYD_ILI9341

Uses:

content\partitions_ota.csv

OTA mode creates two app slots:

app0 / ota_0
app1 / ota_1

Maximum app size in OTA mode:

0x1F0000 bytes = 2,031,616 bytes = about 1.94 MiB

Use this mode if you want OTA updates. If the firmware .bin is bigger than this limit, OTA will not work. Use --no-sound to reduce the app size.

Factory / huge-app mode:

build_firmware.bat --factory CYD_ST7789
build_firmware.bat --factory CYD_ILI9341

Uses:

content\partitions.csv

Factory mode creates one large app partition.

Maximum app size in factory mode:

0x3E0000 bytes = 4,063,232 bytes = about 3.88 MiB

Use this mode when the firmware is too large for OTA. This mode is for serial flashing and does not support OTA updates.

The build tool checks the generated .bin size after every firmware build. If the .bin is too large for the selected partition mode, the build will fail with a clear size error.

Important partition notes:

- --ota and --factory affect the original ESP32 CYD targets.
- ESP32-S3 targets use the generated 16 MB custom OTA layout from the build tool.
- Rebuild before flashing if you change the partition mode.
- Flash the matching .partitions.bin together with the matching firmware .bin.
- OTA and factory/huge-app partition binaries are not interchangeable.


***** Windows desktop version build *****

The desktop version is built with MinGW using the Makefile in the content folder.

Default MinGW path used by build_firmware.bat:

C:\devcpp\i686-w64-mingw32\bin

The desktop build is equivalent to:

set PATH=C:\devcpp\i686-w64-mingw32\bin;%PATH%
mingw32-make -f Makefile

If MinGW is installed somewhere else, set MINGW_BIN before running:

set "MINGW_BIN=C:\path\to\i686-w64-mingw32\bin"
build_firmware.bat --desktop-only


***** Flashing on Windows - recommended method *****

Use the separate flash tool:

flash_firmware.bat

Put it in the content folder next to esptool.exe and the firmware folder:

content\flash_firmware.bat
content\esptool.exe
content\firmware\

Double-click:

flash_firmware.bat

Menu:

1) Flash firmware to a display
2) List serial COM ports
3) Check paths and firmware folder
0) Exit

When flashing, the tool will:

1. List detected COM ports.
2. Ask which COM port to use.
3. Ask which display/device you have.
4. Check that the needed .bin files exist in content\firmware.
5. Ask for confirmation.
6. Erase flash and write the selected firmware.

Command-line examples:

flash_firmware.bat --target WS8048S070C --port COM5
flash_firmware.bat --target EC8048S070B --port COM7
flash_firmware.bat CYD_ILI9341 COM5
flash_firmware.bat CYD_ST7789 COM5
flash_firmware.bat WS8048S070C COM5

Skip erase-flash if needed:

flash_firmware.bat --target WS8048S070C --port COM5 --no-erase

List COM ports:

flash_firmware.bat --list-ports

Check flash tool paths:

flash_firmware.bat --check

If flashing fails at "Connecting...", hold the BOOT button while connecting or while the flash starts, then release after the connection begins.


***** Manual flashing with esptool.exe on Windows *****

The flash_firmware.bat tool is recommended. These commands are only for manual flashing.

Replace COM7 with the correct serial port for your device.

2432S028R - ILI9341:

esptool.exe --chip esp32 --port COM7 --baud 460800 write-flash -z 0x1000 firmware\esp32-2432S028R-ILI9341.bootloader.bin 0x8000 firmware\esp32-2432S028R-ILI9341.partitions.bin 0xe000 firmware\esp32-2432S028R-ILI9341.boot.bin 0x10000 firmware\esp32-2432S028R-ILI9341.bin

2432S028R - ILI9341 V2:

esptool.exe --chip esp32 --port COM7 --baud 460800 write-flash -z 0x1000 firmware\esp32-2432S028R-ILI9341-V2.bootloader.bin 0x8000 firmware\esp32-2432S028R-ILI9341-V2.partitions.bin 0xe000 firmware\esp32-2432S028R-ILI9341-V2.boot.bin 0x10000 firmware\esp32-2432S028R-ILI9341-V2.bin

2432S028R - ST7789:

esptool.exe --chip esp32 --port COM7 --baud 460800 write-flash -z 0x1000 firmware\esp32-2432S028R-ST7789.bootloader.bin 0x8000 firmware\esp32-2432S028R-ST7789.partitions.bin 0xe000 firmware\esp32-2432S028R-ST7789.boot.bin 0x10000 firmware\esp32-2432S028R-ST7789.bin

ESP32-S3 display with boot.bin file, example WS8048S070C:

esptool.exe --chip esp32s3 --port COM7 --baud 460800 write-flash -z 0x0000 firmware\esp32s3-WS8048S070C.bootloader.bin 0x8000 firmware\esp32s3-WS8048S070C.partitions.bin 0xe000 firmware\esp32s3-WS8048S070C.boot.bin 0x10000 firmware\esp32s3-WS8048S070C.bin

ESP32-S3 display without boot.bin file, example JC3248W535C:

esptool.exe --chip esp32s3 --port COM7 --baud 460800 write-flash -z 0x0000 firmware\esp32s3-JC3248W535C.bootloader.bin 0x8000 firmware\esp32s3-JC3248W535C.partitions.bin 0x10000 firmware\esp32s3-JC3248W535C.bin

Use the matching firmware prefix for your display:

esp32-2432S028R-ILI9341
esp32-2432S028R-ILI9341-V2
esp32-2432S028R-ST7789
esp32s3-JC3248W535C
esp32s3-WS8048S043C
esp32s3-WS8048S070C
esp32s3-EC8048S070C
esp32s3-EC8048S070B
esp32s3-EC8048S070CT
esp32s3-WSTOUCHLCD28


***** Flashing with Python / Linux *****

First install esptool:

pip install esptool

On Linux, your device will usually appear as something like /dev/ttyUSB0 or /dev/ttyACM0.

Replace /dev/ttyUSB0 with the correct serial device for your system.

2432S028R - ILI9341:

python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash -z 0x1000 firmware/esp32-2432S028R-ILI9341.bootloader.bin 0x8000 firmware/esp32-2432S028R-ILI9341.partitions.bin 0xe000 firmware/esp32-2432S028R-ILI9341.boot.bin 0x10000 firmware/esp32-2432S028R-ILI9341.bin

2432S028R - ILI9341 V2:

python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash -z 0x1000 firmware/esp32-2432S028R-ILI9341-V2.bootloader.bin 0x8000 firmware/esp32-2432S028R-ILI9341-V2.partitions.bin 0xe000 firmware/esp32-2432S028R-ILI9341-V2.boot.bin 0x10000 firmware/esp32-2432S028R-ILI9341-V2.bin

2432S028R - ST7789:

python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash -z 0x1000 firmware/esp32-2432S028R-ST7789.bootloader.bin 0x8000 firmware/esp32-2432S028R-ST7789.partitions.bin 0xe000 firmware/esp32-2432S028R-ST7789.boot.bin 0x10000 firmware/esp32-2432S028R-ST7789.bin

ESP32-S3 display with boot.bin file, example WS8048S070C:

python -m esptool --chip esp32s3 --port /dev/ttyUSB0 --baud 460800 write-flash -z 0x0000 firmware/esp32s3-WS8048S070C.bootloader.bin 0x8000 firmware/esp32s3-WS8048S070C.partitions.bin 0xe000 firmware/esp32s3-WS8048S070C.boot.bin 0x10000 firmware/esp32s3-WS8048S070C.bin

ESP32-S3 display without boot.bin file, example JC3248W535C:

python -m esptool --chip esp32s3 --port /dev/ttyUSB0 --baud 460800 write-flash -z 0x0000 firmware/esp32s3-JC3248W535C.bootloader.bin 0x8000 firmware/esp32s3-JC3248W535C.partitions.bin 0x10000 firmware/esp32s3-JC3248W535C.bin


***** Notes *****

- Use build_firmware.bat only for building.
- Use flash_firmware.bat only for flashing.
- Firmware files must exist in content\firmware before flashing.
- Run build_firmware.bat --install once before the first Arduino CLI build.
- Use --no-sound when you need to reduce the ESP32 CYD firmware size.
- Use --ota if you need OTA updates on ESP32 CYD.
- Use --factory if you need the larger ESP32 CYD app partition and do not need OTA.
- Rebuild and reflash after changing sound mode or partition mode.
- If Arduino CLI cannot find libraries, check C:\ArduinoIDE\Data\Lib and C:\ArduinoIDE\Data\Sketchbook\libraries.
- If Pi-Star SSH support is enabled, the required SSH library must also be available in your Arduino libraries.
- Use at your own risk.
