HamView runs on an ESP32-S3 and shows HamAlert DX spots.

• Default mode is headless/web UI (no TFT required).
• Optional TFT support via TFT_eSPI (auto-initializes when wired/configured; BOOT-at-power-on forces safe headless mode).

• Captive-portal provisioning via WiFiManager
• Web UI showing spots + JSON endpoints for auto-refresh
• HamAlert ingestion via:
  • REST (legacy endpoint now returns 404 on hamalert.org)
  • Telnet (recommended; firmware auto-falls back to Telnet when REST fails)

Provisioning portal:

• SSID: HamAlert-Setup
• Portal IP: http://172.16.27.1/

Web UI:

• App HTTP port: 8080
• URL: http://:8080/
• mDNS (if supported by your network): http://hamview.local:8080/

Example (from a real setup):

• http://172.16.4.26:8080/
• http://172.16.4.26:8080/test

Why port 8080? WiFiManager runs a config portal on port 80 and on ESP32 the port can remain busy long enough that AsyncTCP fails to bind (begin(): bind error: -8). Running the app on 8080 avoids that conflict.

HamAlert Telnet:

• Host: hamalert.org
• Port: 7300

Prereqs:

• VS Code + PlatformIO
• ESP32-S3 board (this repo targets freenove_esp32_s3_wroom)

Important: Verify platformio.ini contains:

framework = arduino  # Required for ESP32 builds

Build + upload:

• pio run -t upload

Startup behavior:

• On first boot (or after BOOT-button reset), shows captive portal
• On subsequent boots, attempts saved WiFi connection first (10s timeout)
• Falls back to captive portal only if saved WiFi fails
• Hold BOOT button during power-on to force portal and reset credentials

First-time provisioning:

1. Connect your phone/laptop to HamAlert-Setup
2. Open http://172.16.27.1/ if the captive portal doesn’t pop
3. Enter WiFi + HamAlert settings and Save

After it joins your WiFi:

• Open http://:8080/
• Or try http://hamview.local:8080/

Quick verification:

• curl http://<device-ip>:8080/test
• nmap <device-ip> -p 8080

Set in the WiFiManager portal:

• WiFi SSID / password
• HamAlert username / password (needed for Telnet)
• Optional filters: callsign, band
• “Use REST API” checkbox

Notes:

• HamAlert REST’s legacy https://hamalert.org/api.php currently returns HTTP 404; firmware will automatically switch to Telnet after seeing 404/403/401.

Common commands:

• Build: pio run
• Upload: pio run -t upload
• Serial monitor: pio device monitor -b 115200

Board/settings live in platformio.ini.

HamView will try to initialize the TFT at boot.

• Safe mode / headless override: hold the BOOT button (GPIO0) while powering on/resetting to skip TFT init. (This also triggers WiFiManager credential reset.)
• If the screen is totally dark, it’s usually backlight power (see WIRING.txt).

Configuration:

1. Set TFT_eSPI driver + pins via build flags in platformio.ini
2. A PlatformIO pre-script patches a known ESP32-S3 TFT_eSPI SPI-port macro issue: tools/patch_tft_espi.py

Wiring reference: WIRING.txt

Cause: Missing framework = arduino in platformio.ini

Solution: Add this line to your [env:...] section in platformio.ini:

[env:freenove_esp32_s3_wroom]
platform = espressif32
board = freenove_esp32_s3_wroom
framework = arduino  # Add this line!

Cause: JSON configuration accidentally in main.cpp source file

Solution: Ensure main.cpp starts with C++ includes, not JSON. Remove any c_cpp_properties.json content that may have been pasted.

1. Confirm you’re using the right port:
   • http://<device-ip>:8080/
2. Verify the device is the device you think it is:
   • Compare printed WiFi MAC in serial logs with what your router shows.
   • Beware: nmap may show a different MAC if you scanned the wrong IP.
3. Check the test endpoint:
   • curl http://<device-ip>:8080/test

Expected: the app runs on 8080.

Hold the BOOT button (GPIO0) during boot to reset WiFiManager settings.

• Setup guide: QUICKSTART.md
• Project overview: PROJECT_SUMMARY.md
• More docs: docs/README.md

This repo is still moving fast. For a running list of user-visible changes, see:

• CHANGELOG.md