Files
pager/README.md
T
2026-11-12 19:27:41 +01:00

6.0 KiB

ESP32-H2 POCSAG Receiver

An experimental ESP-IDF 6.0 receiver for 1200-baud POCSAG using an ESP32-H2, CC1101, and 128x64 SPI SSD1306 OLED. The CC1101 is configured for a 26 MHz crystal and 435 MHz by default. Reception is decoded in firmware from the CC1101 asynchronous GDO0 output.

This project is receive-only. It does not implement POCSAG transmission.

Hardware Pins

All button inputs are active-low and use the ESP32-H2 internal pull-ups. Connect external pushbuttons between their GPIO and GND. BOOT remains available as a complete single-button fallback.

ESP32-H2 GPIO Function
GPIO0 CC1101 MISO
GPIO1 CC1101 CSN
GPIO2 Battery-divider ADC input when enabled; ADC1 channel 1
GPIO3 CC1101 GDO0 asynchronous data
GPIO4 Shared SPI SCLK for CC1101 and OLED
GPIO5 Shared SPI MOSI for CC1101 and OLED
GPIO6 Menu Up button
GPIO7 Menu Down button
GPIO8 On-board NeoPixel data
GPIO9 BOOT button
GPIO10 OLED CS
GPIO11 OLED DC
GPIO12 OLED reset
GPIO13 Normal status LED
GPIO14 Menu Select button

The shared SPI bus runs CC1101 and the OLED on separate chip-select pins. Keep the listed SPI, RF, display, and LED pins unchanged unless you also update the firmware and wiring.

Button wiring change: GPIO2 is now reserved for the optional battery ADC. The optional Select button is GPIO14; if it is still wired to GPIO2 from an earlier firmware version, move it to GPIO14 before enabling battery monitoring.

Battery Measurement

The board's battery pads are power connections, not a voltage-sense output. Do not connect a Li-ion battery directly to an ESP32 GPIO: a charged cell can reach 4.2 V and exceed the ADC input range.

To measure battery voltage, install an external resistor divider:

BAT+ ---- Rtop ----+---- GPIO2 (ADC1_CH1)
                   |
                 Rbottom
                   |
GND ---------------+---- ESP32-H2 GND

The defaults in main/main.c are Rtop = 100 kOhm and Rbottom = 100 kOhm, so 4.2 V at the battery produces about 2.1 V at the ADC pin. Use the actual installed resistor values in BATTERY_DIVIDER_TOP_OHMS and BATTERY_DIVIDER_BOTTOM_OHMS; the firmware calculates:

battery_mV = adc_pin_mV * (Rtop + Rbottom) / Rbottom

After wiring and checking that the ADC pin voltage stays below the ESP32-H2 ADC limit, set BATTERY_MONITOR_ENABLE to 1. The firmware uses ADC one-shot mode with IDF calibration, samples every five seconds, logs millivolts, and shows the voltage on the live screen. It is disabled by default because this board revision has no built-in voltage-sense circuit.

Controls and Menu

With the added buttons:

  • Up / Down: move through menu items; browse older/newer history; decrease/increase the tuning candidate.
  • Select: activate the selected menu item, apply a tuned frequency, enter history from Live, or return to Live from History.
  • BOOT fallback: short press advances through menu items, message pages, and history; long press opens the menu or selects/applies the current item.

The menu contains:

  • Filter: Private mode is the default and stores/displays only MY_RIC. Monitor mode stores/displays all decoded RICs. Switching modes clears the in-memory history.
  • Frequency: opens the receive-only tuner.
  • Live display: returns to the main screen.
  • Message history: shows the eight most recent saved messages.
  • Return: goes back to the previous screen.

The tuner steps in 25 kHz increments across 433.000 to 435.500 MHz. Up/Down choose either direction; Select applies the frequency, recalibrates the CC1101, and resumes reception. With BOOT only, short presses step upward and wrap at the end; a long press applies the candidate.

The live screen updates while a message is decoded. Messages up to 159 characters are displayed over multiple pages. In Live, BOOT short-press advances message pages and then opens history. The OLED turns off after 60 seconds without UI activity; button presses and displayed pages wake it.

Pages addressed to MY_RIC (default 1234567) flash the normal LED on GPIO13 and NeoPixel on GPIO8 for approximately three seconds.

Persistent Message History

The firmware stores the eight-entry message ring in the default NVS partition. Saved messages are restored after reboot or power loss. Private mode saves only MY_RIC; Monitor mode saves all decoded RICs. Changing the filter mode clears the stored history. NVS is initialized automatically on startup; if its metadata is incompatible or out of free pages, ESP-IDF recovery may erase the NVS partition and the saved messages.

Flash Layout

The ESP32-H2 has 4 MB of flash, and sdkconfig now sets the ESP image header flash size to 4 MB. The existing single-app partition layout is retained: it provides a 1 MB factory application partition plus the standard NVS and PHY partitions. The remaining flash is currently unused; the firmware does not resize partitions automatically.

Configuration

Important definitions are near the top of main/main.c:

  • RF_FREQ_HZ: startup receive frequency.
  • TUNE_MIN_HZ, TUNE_MAX_HZ, TUNE_STEP_HZ: menu tuner range and step.
  • MY_RIC: private-mode address and own-page alert address.
  • BATTERY_MONITOR_ENABLE: battery voltage reading, disabled by default.
  • BATTERY_DIVIDER_TOP_OHMS, BATTERY_DIVIDER_BOTTOM_OHMS: installed divider resistor values.
  • OLED_IDLE_OFF_MS: OLED timeout.

The firmware assumes a 26 MHz CC1101 crystal. Confirm the crystal and signal frequency for your hardware. The frequency tuner only changes the receiver frequency.

Build and Flash

Open the project in ESP-IDF 6.0 with target esp32h2, then run:

idf.py build
idf.py -p PORT flash
idf.py -p PORT monitor

The component dependencies include the ESP-IDF GPIO, SPI, GPTimer, ADC, NVS, and Espressif LED-strip drivers.

Limitations

This is a proof of concept, not a certified pager or radio product. Reception quality depends on CC1101 configuration, antenna, RF environment, and signal timing. The firmware does not transmit pages or save menu settings across reboot.