Whisper OS

User Manual

A practical guide for flashing, pairing, and operating Whisper OS on supported mesh devices.

Current firmware

v1.3.4

Overview

Whisper OS turns small-screen mesh hardware into a usable messaging tool. The core idea is simple: the device should remain understandable in the field without a laptop, serial console, or guesswork.

Once installed, the device can handle on-device navigation, encrypted mesh messaging, contact browsing, radio status checks, and Bluetooth pairing with companion clients for faster text input and management.

Before You Start

Use a real USB data cable

Charge-only cables are the most common flashing failure. If your browser never sees the board, swap the cable first.

Use a desktop browser with Web Serial support

Chrome, Edge, Brave, and Opera work best for the web flasher. Safari and Firefox do not provide the same serial support.

Confirm your exact board family

ESP32 and nRF52 devices use different firmware formats and different flashing flows. Treat them as separate installation paths.

Prepare a companion client

After flashing, pair through the MeshCore mobile app or connect from Haikou in a browser that supports Web Bluetooth.

Supported Hardware

ESP32 Family

Typical examples include Heltec V3, Heltec V4, and Heltec T114. These boards flash raw binary images over a serial connection.

nRF52 Family

Typical examples include RAK4631, Wio Tracker L1, MeshTiny, GAT562 variants, and related community boards. These boards use a DFU package flow instead of direct raw flashing.

The final source of truth is always the device selector in the web flasher because supported targets expand over time.

Choose the Right Install Path

Whisper OS does not have a single universal flashing method. First principles here are straightforward: the microcontroller determines the update path, so the board family matters more than the product name.

ESP32

Uses .bin firmware and a direct serial flashing process. First-time installs usually require the merged image.

nRF52

Uses a .zip DFU package and often needs a one-time erase step when replacing older firmware stacks.

ESP32 Installation

Connect the board and open the flasher

Open the web flasher in a Chromium-based browser and let the page load before selecting a device.

Select version, board, and language

Choose the firmware version, your exact ESP32 board, and your preferred language so the correct build is resolved.

Use Merged for a clean first install

If the board is brand new or coming from different firmware, select the merged image. That writes bootloader, partitions, and app together.

Use Erase device only when you need a clean slate

Erase is useful for first-time installs and recovery, but it also wipes stored identity and pairing data.

Flash and wait for completion

Click Flash Device, pick the serial port shown by the browser, and do not unplug the board until the process completes.

Press reset after success

A manual reset is often required on ESP32 boards before Whisper OS boots for the first time.

nRF52 Installation

If the board previously ran other firmware, do the one-time FLASH_ERASE preparation step first. Skipping it is one of the most common reasons an nRF52 upgrade appears to succeed but boots into a broken state.

Erase the old SoftDevice if this is the first Whisper OS install

When the board previously ran other firmware, start with the FLASH_ERASE file from the flasher instructions. This clears the BLE stack area that often causes bad upgrades.

Enter bootloader mode

Most supported boards enter UF2 or DFU mode after a quick double-tap on the reset button.

Select the nRF52 build

Choose the version, nRF52 family, exact model, and language before starting the device update flow.

Use Enter DFU Mode if the board supports it

The web flasher can request DFU mode from some boards. If it fails, double-tap reset and continue manually.

Flash the ZIP package and wait

nRF52 boards receive a DFU package rather than a raw binary. Leave the cable connected until the board reboots by itself.

First Boot Checklist

Display renders correctly

You should see the Whisper OS boot sequence and a readable UI. Garbled text usually means the wrong hardware variant was selected.

Buttons or joystick respond

Basic navigation should work immediately. If input is dead, confirm the build matches the board and input hardware.

Status indicators appear

Battery and Bluetooth state should be visible from the initial screens. Missing status is a sign of incomplete startup.

Bluetooth PIN is available

If the device shows no BLE PIN when expected, the Bluetooth stack likely did not initialize cleanly.

Bluetooth Pairing

Whisper OS keeps field operation on the device and moves heavier text entry or management tasks to a companion client. Pairing is the bridge.

MeshCore mobile app

Enable Bluetooth on your phone, wake the device, scan from the app, select the Whisper device, then enter the 6-digit PIN shown on the device screen.

Haikou web client

Open /haikou in a browser with Web Bluetooth support, click connect, and choose the device from the browser prompt.

Device Navigation

Single-button devices

Short press usually moves forward through screens or lists. Long press usually confirms or opens the selected item.

Joystick or multi-button devices

Left and right change screens. Up and down move through lists. Center press selects. A long center press often acts as back.

Keyboard devices

Arrow keys navigate, Enter confirms, and the dedicated back key exits menus when the hardware provides one.

Core screens

Expect a home view for device state, messages for recent traffic, contacts for heard nodes, and radio diagnostics for RF health.

Navigation rule of thumb

Horizontal movement changes context. Vertical movement changes selection inside that context. That mental model is more stable than memorizing every board layout separately.

GPS Duty-Cycle Modes

Supported standby-capable boards can reduce GPS battery draw by switching between short awake windows and longer standby windows. The core idea is simple: keep GPS awake until the first valid fix, then spend more of the hour in standby instead of running the receiver continuously.

Added GPS duty-cycle types for supported standby-capable boards. Fast saves about 11.4% battery life, Basic 22.0%, Eco 30.1%, and Ultra Eco 33.6%. These values come from measured Heltec V4 GPS current, using about 105mA while active and 78mA while in GPS sleep.

Mode	How It Works	Best For	Standby Pattern	Battery Gain
Realtime	GPS stays awake continuously for the fastest continuous updates.	Driving, live tracking, or bench testing	No standby	0.0%
Fast	Frequent refreshes with a modest battery saving.	Cycling, city movement, or short field runs	72 sec awake + 48 sec sleep	11.4%
Basic	Balanced refresh rate and battery life.	General outdoor use and day hikes	72 sec awake + 168 sec sleep	22.0%
Eco	Longer standby windows to favor battery life.	Long hikes, camp movement, and slower travel	1 min awake + 9 min sleep	30.1%
Ultra Eco	Longest standby windows for maximum battery savings.	Stationary beacons, overnight use, and battery-first tracking	1 min awake + 49 min sleep	33.6%

Troubleshooting

Board not detected by the browser

Replace the USB cable, try a different USB port, and close any desktop serial tools that may already be holding the device.

Flash succeeded but the device does not boot correctly

Repeat the install with the exact board target. For ESP32, use the merged image. For nRF52, repeat the erase step before reflashing.

Bluetooth pairing fails

Wake the device screen first, remove old pairings on the phone or computer, then pair again using the current on-screen PIN.

Messages are not moving across the mesh

Check radio status, confirm nodes share the same network settings, and verify the device is not stuck with stale settings from an older install.