Sleep Buddy documentation

Sleep Buddy is a local snoring monitor for the Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3. The firmware analyses the two integrated microphones directly on the ESP32-P4, presents the current result on the touch display and stores night summaries on a microSD card.

Sleep Buddy is not a medical device. It does not diagnose sleep apnoea, sleep disorders, sleep stages or sleep quality. Do not use its results to make medical decisions.

Required hardware

• Waveshare ESP32-P4-WIFI6-Touch-LCD-4.3

• FAT32-formatted microSD card

• stable 5 V USB power supply

• USB-C data cable for firmware installation

The two microphones are already integrated into the Waveshare board and connected through the ES7210 codec. No soldering or additional sensor wiring is required.

Prepare the microSD card

Insert the microSD card before powering on the board. Monitoring requires the card because every completed night, including a valid night recovered after power loss, is stored locally.

The card must use FAT32. Cards larger than 32 GB still require a FAT32 partition. The current firmware does not support exFAT.

Install firmware with the Web Flasher

No Arduino IDE, PlatformIO or local ESP-IDF environment is required. Use a desktop computer, Chrome or Edge, and a USB-C cable that supports data.

1. Insert the microSD card and connect the Waveshare board to the computer through USB-C.

2. Open https://spacepc.dev/en/flash/sleep-buddy in Chrome or Edge.

3. Check the selected firmware version and hardware.

4. Confirm that existing settings may be erased.

5. Select “Connect board and start installation”.

6. Choose the serial port belonging to the ESP32-P4.

7. Do not disconnect the cable or close the browser during installation.

8. Wait for the success message and then restart the device.

The Web Flasher obtains the bootloader, partition table, application firmware and build-generated flash offsets automatically from the published manifest.

Initial setup

1. Insert a FAT32-formatted microSD card.

2. Connect a suitable 5 V USB power supply.

3. Open Settings on the touch display.

4. Configure Wi-Fi credentials.

5. Select the correct time zone.

6. Check Wi-Fi and NTP status.

7. Return to Monitor.

Audio classification works without Wi-Fi and without a cloud connection. Wi-Fi allows Sleep Buddy to synchronise time through NTP and store meaningful clock times in summaries.

Start monitoring

The centre of the circle on the Monitor screen shows live Snore Confidence calculated by the model.

Drag the pink marker around the circle to change the threshold. While dragging, the centre shows Snore Threshold and the selected percentage. Releasing the marker saves the value and restores live confidence.

The threshold ranges from 5 to 90 percent and defaults to 50 percent. One model result at or above the threshold starts a candidate event. Four results below the lower end threshold finish it. This hysteresis prevents rapid on/off transitions.

Start

The green Start button begins local analysis without storing complete audio. Only derived event and summary data is written to microSD.

Start + Record

The red Start + Record button begins analysis and additionally stores a 32 kHz, 16-bit stereo WAV file. Use this function only with consent from everyone who may be recorded.

End the night

End Night or End + Save finishes the active session. Sleep Buddy then opens the summary automatically.

Screens and touch controls

Monitor

Shows live confidence, threshold, elapsed time, detected events and the actions used to start or end monitoring.

Summary

Shows monitored time, detected snoring time, longest phase, event count and an explicitly non-medical acoustic score. The touch-selectable timeline distinguishes quiet periods from periods detected as snoring.

History

Shows snoring duration for the seven most recently stored nights.

Settings

Contains Wi-Fi credentials, connection state, NTP state and time-zone selection.

The Off button turns the panel and backlight off. Touching the display wakes it again. Active audio analysis continues while the display is off.

Local files

• NIGHTS.BIN – authoritative binary night history including the snoring timeline

• NIGHTS.JL – human-readable JSON Lines summaries for completed nights

• EVENTS.JL – event start, end, confidence and relative sound level

• CURRENT.BIN – checksummed rolling checkpoint of the active night

• ST0001.WAV through ST9999.WAV – optional stereo recordings created by Start + Record

Wi-Fi credentials, the selected time zone and threshold are stored in ESP32 NVS rather than in the night files on microSD.

Recovery after power loss

Sleep Buddy updates the active-night checkpoint after completed events and at least every 30 seconds. On the next boot, a valid interrupted night is recovered into normal history before the checkpoint is removed.

Local snoring detection

The firmware embeds a quantised EfficientAT AudioSet MN04 model and uses its pretrained Snoring output. Microphone 2 is evaluated as 32 kHz mono through a two-second window, pre-emphasis, a 1024-point STFT, 128 Kaldi Mel bands, fixed normalisation and int8 inference. Inference uses a 1.25-second stride.

The adjustable display threshold does not alter the model or its quantisation. It only determines when model probabilities are converted into stored events.

The model is a practical prototype tested on the target board, not a clinically validated classifier. Rooms, people, distance and background noise can affect results.

Privacy

Classification runs locally. Normal Start sessions do not store complete audio. Complete audio is written to the local microSD card only after explicitly selecting Start + Record.

Obtain consent from everyone who may be recorded. Treat WAV files as sensitive data, do not transfer them without protection and delete them when no longer required.

Troubleshooting

Monitoring does not start

Power the device off, insert a FAT32-formatted microSD card and restart it. exFAT is unsupported.

Time is missing or incorrect

Check Wi-Fi and time zone in Settings. NTP synchronisation requires internet access, but local audio classification does not.

Too many or too few events

Adjust the threshold using the pink marker. A higher threshold reduces sensitivity; a lower threshold increases it. Distance, room acoustics and background noise also affect detection.

No WAV file is present

A WAV file is written only for Start + Record. Normal Start sessions store only event and summary data.

Display remains dark

Check the USB-C cable and 5 V supply. If the panel was switched off with Off, touch the display to wake it.

Web Flasher does not detect the board

Use Chrome or Edge on a desktop computer and a USB-C data cable. Close other programs using the serial port and reconnect the board.

Safety and medical notice

• Sleep Buddy is not a medical device or medical diagnostic aid.

• Persistent or concerning snoring and suspected breathing interruptions require assessment by a qualified medical professional.

• Operate only from a suitable regulated 5 V USB power supply.

• Use only in dry indoor locations.

• Do not continue using damaged boards, cables or memory cards.

• Insert or remove the microSD card while the device is powered off whenever possible.

• Respect consent and privacy whenever audio recording is enabled.