9M2PJU ESP32 DX Cluster Client

USB cable

Many USB cables are charge-only and don't carry data. Try a different cable — ideally one that you know works for data transfer (e.g. the cable that came with your phone).

USB hub

Plug directly into the computer, not through a hub. Some hubs block serial data.

ESP32-S3 boards: BOOT button trick

If you have an ESP32-S3 board (T-Display-S3, T-QT, T-HMI, T-Watch S3, Waveshare S3 Round, T-Deck, Heltec WiFi Kit 32 V3, WiFi LoRa 32 V3, Wireless Tracker) and the port doesn't appear:

1. Unplug the board.
2. Hold the BOOT button.
3. Plug in the USB cable (keep holding BOOT).
4. After 1–2 seconds, release BOOT.
5. The port should now appear. Click Connect and select it.

Drivers

Most ESP32 boards use CP2102 or CH340 USB-to-serial chips. Modern OS versions include drivers, but if the port doesn't appear you may need to install:
CP2102: Silicon Labs VCP drivers
CH340: WCH CH340 drivers

• Try a different USB cable and port.
• Close other programs that might be using the serial port (PlatformIO, Arduino IDE, serial monitors).
• If flashing gets stuck at "Erasing", try the BOOT button trick above to force the board into download mode.
• If it fails repeatedly, refresh the page and try again. The ESP Web Tools library is generally reliable but occasional glitches happen.

• Wrong board selected? Make sure you selected the correct board for your hardware. Each board has a different display configuration. If you flashed the wrong firmware, re-flash with the correct board.
• Heltec OLED boards: The WiFi Kit 32, WiFi LoRa 32, and Wireless Stick use SSD1306 OLED displays via I2C. If the screen is blank, double-check you selected the right Heltec variant — V1/V2 boards (ESP32) and V3 boards (ESP32-S3) use different I2C pins.
• Heltec Wireless Tracker: Uses a TFT LCD (ST7735) via SPI, not OLED. Make sure you selected "Wireless Tracker" and not one of the OLED boards.
• T-Watch 2020: The display is powered by the AXP202 PMU. The firmware initializes it automatically, but if the battery is completely dead, plug in USB power and wait 10 seconds.
• Backlight too dim: The default brightness is 220/255. If your screen seems dark, try looking at it from different angles — some IPS panels look dark head-on. OLED boards (Heltec) don't have a backlight — they're always on at full brightness.

• The setup AP name is 9M2PJU-DXCluster-XXXX (last 4 characters are unique to your device). Look for a network starting with 9M2PJU-DXCluster.
• It's an open network — no password needed to connect.
• If you don't see it, the device might not be in setup mode. Hold BOOT + press RESET to force it.
• On some phones, you need to turn off mobile data for the captive portal to appear.

If you connect to the setup Wi-Fi but no page appears automatically:

1. Open any web browser on your phone.
2. Type http://192.168.4.1/ in the address bar.
3. The configuration form should load.

If that doesn't work either, try http://192.168.4.1 (without the trailing slash) or navigate to any website — the captive portal redirect should kick in.

• 2.4 GHz only: ESP32 does not support 5 GHz Wi-Fi. If your router is dual-band, make sure you selected the 2.4 GHz network name.
• Wrong password: Re-enter setup mode (hold BOOT + RESET) and try again. Wi-Fi passwords are case-sensitive.
• WPA3: Some ESP32 firmware versions have trouble with WPA3-only networks. If your router supports WPA2/WPA3 mixed mode, use that.
• Hidden SSID: The scan button won't find hidden networks. Type the SSID manually.
• Too far from router: The device falls back to setup mode if Wi-Fi doesn't connect within 30 seconds. Move closer to your router.

• Check the connection dot: If it's orange, the device is still connecting to the cluster. If it stays orange for more than a minute, the cluster server might be down or unreachable.
• Check the cluster host and port: Re-enter setup mode and verify the settings. Default is 9m2pju.hamradio.my port 7300.
• Callsign rejected: Some clusters only accept registered users. The default placeholder is N0CALL — make sure you entered your real callsign.
• Cluster is quiet: If no one is spotting, there's nothing to show. Try sending sh/dx via the button menu to request recent spots.
• Firewall: Some networks block port 7300. Try a different Wi-Fi network or check with your network admin.

• The BOOT button (GPIO 0) is used for the menu. On most boards this is the button labeled BOOT or IO0.
• The menu only works in normal mode (when the device is showing spots). It doesn't work in setup mode.
• Short press = quick click (less than 1 second). Long press = hold for at least 1 second.
• If the button is hard to reach on your board (e.g. inside a case), you may need to wire an external button to GPIO 0.

Hold the BOOT button while pressing RESET. The device boots into setup mode and you can enter new settings. The old settings will be overwritten when you save.

To completely wipe all settings, re-flash the firmware using the web flasher — this erases NVS and starts fresh.

A DX Cluster is a network of servers that relay "spots" — real-time reports of interesting amateur radio activity. When someone hears a rare station, they post a spot to the cluster, and it's immediately distributed to all connected operators. A spot looks like:

This tells you: station 9M2XYZ spotted JA1ABC on frequency 14.074 MHz (20m band), the mode is FT8, the signal was strong in Europe, and the spot was posted at 12:34 UTC.

This device connects to a DX cluster server and displays these spots on its screen in real time, so you can see what's being heard around the world without running a computer or telnet client.

Any DXSpider-compatible cluster that speaks the standard telnet protocol on port 7300. This includes:

• 9M2PJU DXSpider Docker — 9m2pju.hamradio.my:7300
• Any public DXSpider node (search for "DX cluster list" online)
• CC Cluster and AR-Cluster servers (mostly compatible)

The default host is 9m2pju.hamradio.my but you can point the device at any cluster server via the web admin UI.

No. The ESP32 only supports 2.4 GHz Wi-Fi (802.11 b/g/n). If your router is dual-band (2.4 + 5 GHz), connect to the 2.4 GHz network name.

No. The device runs on USB power. Boards with batteries (T-Watch, M5StickC Plus, M5Stack Core2) will also run on battery — the firmware doesn't do anything special with battery power, but the display and Wi-Fi will work normally.

Yes. Hold the BOOT button while pressing RESET to enter setup mode. The web admin UI lets you change Wi-Fi, callsign, cluster server, and all other settings. Changes are saved to NVS (flash memory) and persist across reboots.

The DX cluster protocol is plain telnet (unencrypted). This is standard for amateur radio DX clusters. The callsign is sent in plain text. The callsign password (if your cluster requires one) is also sent in plain text. This is the same as any telnet DX cluster client. The web admin UI (configuration page) is local — it only travels between your phone and the ESP32 over the setup Wi-Fi, not over the internet.

Typical flash usage is 25–30% on ESP32-S3 (16 MB flash) and 65–75% on ESP32 (4 MB flash). RAM usage is about 15% (48 KB of 320 KB). There's plenty of room for future features.

Yes. The project uses PlatformIO. Clone the repository, copy include/config.example.h to include/config.h, edit your defaults, and run pio run -e <your-board>. See the Developer Guide in the docs/ folder for full instructions.

It takes about 30 lines of code. You need to create a board configuration file (LovyanGFX subclass with the display pins), add an entry in BoardConfig.h, and add a PlatformIO environment. See "Adding a New Board" in the docs/ folder for a step-by-step guide.