User Manual

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

1. 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.
2. Select version, board, and language. Choose the firmware version, your exact ESP32 board, and your preferred language so the correct build is resolved.
3. 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.
4. 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.
5. 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.
6. 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.

1. 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.
2. Enter bootloader mode. Most supported boards enter UF2 or DFU mode after a quick double-tap on the reset button.
3. Select the nRF52 build. Choose the version, nRF52 family, exact model, and language before starting the device update flow.
4. 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.
5. 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.

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

The navigation rule of thumb is stable across boards: horizontal movement changes context, while vertical movement changes selection inside that context.

Screen Options

Contact, Radio, GPS, and System each have a long-press options menu. Short presses keep moving through screens or list items; long-press select opens the action menu for the current screen.

The firmware only shows actions that make sense for the current board, build flags, and license state. If an item below is not on your device, the usual reason is missing hardware support or a firmware build without that feature enabled.

Contact

The Contact screen is where you pick a destination and send direct or channel messages.

• Destination opens a sorted list of saved contacts and named channels.
• Ping sends a trace request to the selected destination.
• Quick Message sends one of the preset messages stored on the device.
• PRO: Morse Code appears on supported licensed builds.
• Type Message appears on keyboard or virtual-keyboard builds for free text input.
• PRO: Predictive input suggests word completions and next-word or next-character candidates on IME-enabled builds.

Radio

The Radio screen shows RF status and exposes actions that affect radio identity, relay behavior, and routing.

• Send Advert broadcasts the device identity advert.
• Flood Advert sends an advert through the mesh path.
• Relay appears on packet-forwarding builds and requires restart to fully apply.
• Routing selects Basic, Standard, or Max route detail.
• Radio Preset writes frequency, spreading factor, bandwidth, and coding rate, then restarts the device.

GPS

The GPS screen shows fix state, satellites, speed, altitude, and coordinates when available.

• Turn GPS On or Turn GPS Off starts or stops the receiver.
• PRO: Mode opens the duty-cycle selector on supported licensed standby-capable builds.
• PRO: Duty-cycle choices are Std., Fast, Basic, Eco, and Ultra Eco.
• PRO: Show Coordinates or Hide Coordinates controls whether coordinates are shown on the device screen.

System

The System screen shows node name, pairing state, board name, firmware version, and license state.

• Display controls brightness and always-on watch face.
• Connection controls BLE, USB, or Bluetooth visibility when supported.
• Notifications controls buzzer, tap buzz, LED, vibration, and Zen Mode.
• Region controls radio presets, timezone, and language.
• Power controls battery info, restart, and power off.
• About shows license details and firmware update entry when available.

CardKB Wiring

CardKB uses I2C address 0x5F and must be connected to the external I2C pins for the device. Do not wire it to internal display pins.

If CardKB is not detected, swap the SDA and SCL signal wires and reboot.

System Settings

Long-press select on the System screen to open the settings tree. The exact list depends on the board, license state, and firmware build because Whisper OS hides controls for hardware the device does not have.

When a setting changes radio parameters, transport mode, or saved device behavior, Whisper OS stores it in device preferences. Some hardware-level changes show a restart prompt before they fully take effect.

Display

Controls how the local screen behaves. Brightness changes apply immediately and are stored on the device.

• Brightness: Low, Medium, or Max. Some boards use board-specific brightness values so the labels are more important than the raw number.
• Always On: Off, Default, Binary, Cat, Dog Face, or Radio Robot. Off disables the idle watch face.

Connection

Controls the active companion connection path when the hardware and build expose those choices.

• Connection: BLE or USB on dual-interface builds.
• Bluetooth turns BLE advertising and pairing on or off on BLE-capable builds.

Notifications

Controls local alerts. Only hardware-supported outputs appear in the menu.

• Buzzer, Tap Buzz, LED, and Vibration can be toggled when the board has that output.
• Zen Mode keeps the device quieter during wake and alert flows.
• Some alert-output changes ask for a restart before the new behavior is fully applied.

Region

Groups settings that affect local radio behavior and how time or text is shown.

• Radio Preset writes the preset frequency, spreading factor, bandwidth, and coding rate, then restarts the device.
• Timezone supports whole-hour UTC offsets from UTC-12 through UTC+14.
• PRO: Languages appears on multilingual firmware builds for licensed devices. Current locales are English and Simplified Chinese.

Power

Shows battery information and provides shutdown controls.

• Power Info shows measured voltage and the current ADC multiplier.
• Calibrate Battery assumes the battery is full at 4200mV and adjusts the ADC multiplier from the current reading.
• Reset Battery clears the custom ADC multiplier and returns to the board default.
• PRO: ESP32 Power Save automatically lowers power use when the screen is off, no companion connection is active, and GPS is off.
• Restart and Power Off are available from the Power menu.

About

Shows firmware and licensing details for the current board.

• Pro License shows the device ID, supported version range, and issued date when a valid license is present.
• Unlicensed devices show the ssaprus.works license destination.
• Firmware Update appears on nRF52 builds that support OTA update entry from the menu.

Haikou Settings

Haikou exposes management tasks that are easier from a browser: typing a device name, editing quick messages, saving a screen capture, changing radio values, and syncing the clock.

These controls require an active Web Bluetooth connection. If a button fails or a value does not save, reconnect first and confirm the device is running firmware that supports that command.

Device Name

Renames the node advertised by the device.

• Names are limited to 32 characters.
• Keep names short enough to fit small screens and contact lists.

Screenshot

Captures the device screen over Bluetooth and downloads it as a PNG.

• Theme choices are Classic, Inverted, Sand, Ocean, and Forest.
• The theme only changes the rendered capture in Haikou; it does not change the device display theme.
• Recapture pulls a fresh screen buffer from the connected device.

Quick Messages

Writes preset replies used by the device quick-message menu.

• Use one message per line.
• The device stores up to 15 quick messages.
• Each message is trimmed to 31 characters.
• Requires firmware newer than v1.2.2 and currently supports English text only.

Radio Parameters

Edits the radio values that decide whether nearby nodes can hear each other.

• Community Presets fill frequency, spreading factor, bandwidth, and coding rate from common regional profiles.
• Frequency is entered in kHz and accepts 300000 through 2500000.
• Bandwidth options range from 7.8 kHz through 500 kHz.
• Spreading factor supports SF5 through SF12; higher values favor range over speed.
• Coding rate supports 4/5 through 4/8; higher values add more error correction.
• TX Power is limited by the maximum reported by the connected device.

Device Time

Synchronizes the device clock from the computer running Haikou.

• Use Sync Time after flashing, battery drain, or long storage.
• Set the on-device timezone separately from System Settings > Region > Timezone.

Radio changes can isolate a node from the rest of the mesh. Keep one known-good device or written copy of your previous radio values before changing frequency, bandwidth, spreading factor, coding rate, or TX power.

GPS Duty-Cycle Modes

PRO: 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.

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

Try these steps in order:

1. Perform a full erase installation first.
2. Use only lowercase letters a-z and numbers 0-9 for the BLE device name. Do not use spaces, symbols, or special characters. Examples: haikou01, mesh123, whisper9.
3. Forget this device on your phone or computer, turn Bluetooth off, wait 10 seconds, then turn Bluetooth back on.
4. Restart the mesh device, then try connecting again from your phone or computer.
5. If the device still cannot connect after entering the correct PIN, disconnect the mesh device connection and tap Connect again.

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.

FAQ

What is WhisperOS?

WhisperOS is a mesh firmware for LoRa devices with a display, featuring a user-friendly UI and easy operation. It includes features like CJK (Chinese, Japanese, Korean) font support and virtual keyboard input. It is built on top of the MeshCore library.

How do I install WhisperOS?

Go to the Flasher page from the navigation menu. Choose your device model from the device selector. Select the firmware version you want to install. Click the "Install" button to begin the flashing process.

Is WhisperOS free?

Basic firmware is free of charge and covers all essential features. There is a premium version which unlocks power save mode and IME (word/phrase prediction). Only purchase premium if you specifically need these features. The basic firmware is enough for most users.

What is Power Save Mode?

Power Save Mode is a premium feature that greatly extends your battery life. It automatically puts the device to sleep when the screen is off and you are not using GPS or connected to your phone. It wakes up instantly when you receive a message or press a button.

What devices are supported?

WhisperOS supports Heltec V3, Heltec V4, Heltec T114, RAK4631, WIO Tracker L1, Meshtiny, GAT562 Mesh Watch, GAT562 Mesh Trial Tracker, Fobe Quill nRF52840, Fobe Idea Mesh Tracker C1, ProMicro, and LingXi D5. Check the Flasher page for the latest list.

Is WhisperOS open source?

No, WhisperOS is a private commercial project.

What is the virtual keyboard?

WhisperOS includes a built-in on-screen virtual keyboard for text input on devices without a physical keyboard. Tap the text box to enable it. Some devices like M5Stack Cardputer ADV also have a physical hardware keyboard.

What is a merged bin?

A merged bin is a complete firmware image for fresh installation. It overwrites everything including the bootloader and existing Bluetooth pairing database. A non-merged bin only updates the application and preserves the Bluetooth pairing database.