For community troubleshooting and RF survey questions, join the OVMesh Discord. Track reproducible non-sensitive defects in GitHub issues. Security or privacy concerns follow the private reporting guidance.
The desktop is spectrum-only. Missing LoRa discovery, preset/key controls, Detected signals and Packet classifications are intentional in this build, including when older preferences enabled them. Do not troubleshoot their absence by changing keys, reinstalling drivers or enabling internal CLI diagnostics. Use frequency occupancy, observed/busy time, energy events, receiver GPS and reports; none identifies a packet or modem bandwidth.
For rapidly changing narrow rows, confirm whether Show raw fragments is selected. The default candidate view groups supported activity; Pause result list freezes display without interrupting capture. Width kHz is frequency width, Duration ms is elapsed duration, and Active ms excludes grouping gaps. Candidate width can differ from the transmitter's configured bandwidth; inspect the fixed threshold, FFT resolution and overlap/ambiguity before interpreting it. Single-frame activity is still retained in raw evidence. Neither raw fragment nor candidate count is a packet count. See measured grouping evidence.
For quality-flag questions, first identify the Recording file under Details and the applied frequency/time interval in Analyze. Current GPS status does not prove a stored event had both start/end fixes. Read receiver-position coverage and independent missing-start/end durations under Measurement details; these may overlap and are not RF gaps. Hover Quality or expand its explanation. Repeated truncated events can be normal approximately two-second segmentation, and event durations must not be summed as occupancy. The saved-survey audit provides measured examples and a local read-only reproduction tool.
For copyright, licensing or attribution questions, open Settings > About & licenses. CLI --licenses provides the same full texts offline. See the component inventory and license review. A working credits page does not establish that a particular binary release has supplied its corresponding source or met every platform-library obligation.
Status: version 0.4.0 is experimental survey software. New SDR recordings default to Compact schema 6; Detailed schema 5 and historical readers remain available without rewriting old files. RAK sessions use schema 7 sampled measurements. No support SLA or field qualification is established. Follow the user guide, deployment instructions, and security policy.
An ordinary launch opens a fresh, empty workspace with remembered settings and RF stopped. Previous results appear only after Open...; a historical session is marked Read only. For SDRs, Live survey contains the spectrum/waterfall and observation tabs, and Analyze contains By frequency, Over time and By location. RAK displays sampled energy with its own reports instead of FFT occupancy. Packet reception is disabled in the desktop.
| Action | Expected result and support boundary |
|---|---|
| New | Stops and finalizes a recorded session before clearing the workspace; prior files stay intact. A save-verification failure preserves the current session for inspection. Memory-only results require explicit discard confirmation. RF does not start automatically. |
| Open... | Opens an existing saved survey read-only after reception stops. Opening history does not resume a radio or recreate its waterfall. |
| Save | Requests a durable checkpoint of the current recording without stopping RF. Success is shown after the writer commits it; it is not a new export or recovery of discarded memory-only history. |
| More... > Save a copy... | Creates a separate, consistent session database at a new local filename. It leaves the current recording and original file unchanged. |
| Stop reception | Pauses reception and preserves the current recording and results. Resume reception continues the same survey with a new acquisition interval; pauses remain unobserved. |
| Export report... | Creates a selected analysis report from saved history. Stop reception first. It is separate from saving the session database. |
RAK receiver selection adds RAK concentrators settings for explicit one/two-board selection and scan setup. Settings are otherwise grouped into GPS & location, Recording, Display, Measurement & equipment, and About & licenses. Receiver, center frequency, Offset / Hz, span, range and Start/Stop stay on the main screen; sample rate and gain/amplifier controls apply to SDRs. Health counters and detailed explanations remain available under Details and Measurement details; fewer visible counters do not mean less stored evidence.
Capture PNG... saves only the rendered spectrum/waterfall crop at a new local destination. It excludes surrounding message panels, GPS, private paths and other windows, does not save IQ and does not stop reception. Close dialogs before capture. The owned PNG writer is uncompressed, so the image can be larger than a compressed screenshot; it is not a session backup. Settings > Display offers system UI fonts with numeric monospace or All monospace. Existing local OS fonts and the built-in fallback require no download or new external dependency.
Receiver/session actions, recording status, GPS status and session disk size are in the left sidebar. Drag the horizontal handles below the spectrum and waterfall independently to give the result tabs more room; focused handles also accept up/down arrow keys. Resizing and freezing only affect the display.
Within an SDR survey, stop reception, adjust center/span/rate/Offset/gains or supported decoding settings, then resume. Each acquisition retains its configuration and timing; the analysis and reports retain earlier ranges, and reports separate acquisitions rather than imply identical sensitivity. Analyze > Receiver adjustments / acquisition intervals selects one interval. A different receiver type, recording destination/mode, or RAK scan/modem configuration requires explicit New. Saved historical sessions remain read-only.
Collect application and storage-schema versions, operating system/architecture, synthetic versus hardware source, whether the session was saved, relevant non-secret receiver settings, the last applied analysis bounds, visible status/error category and approximate onset time. Separate input availability, measurement duty, observed/busy time, clipping and gaps. Include decoder processed time only when an optional legacy profile was enabled. Record whether the issue is reproducible with the synthetic source before suggesting a hardware experiment.
Do not request channel keys, recipient private keys, raw IQ, packet hex, ciphertext, private decoded text, a complete session database, or a precise operational GPS route. A current saved session can contain private receiver positions and free-form notes. Historical files may also retain old decoded content in their original bytes, although current views and exports exclude it. There is no automatic sanitized support-bundle feature in this build; describe approved status fields manually. Ask the owner to review any proposed sharing and use the minimum necessary metadata. Creating or examining a local report does not authorize uploading it.
Operate test hardware only with the operator's consent and an agreed test scope. The application is receive-only; support procedures must not transmit packets or administer mesh radios.
New and remembered ordinary desktop settings are forced to spectrum-only reception. No decoder, public/default key or configured packet profile is activated. The experimental implementation remains in source for future development but is not a supported user workflow. Spectrum measurements require no keys, known channel frequencies or modem settings; record-first reporting remains the primary workflow.
Ordinary desktop launches default to recording and automatic GPS, then remember the operator's switches, recording folder, selected GPS identity/baud and receiver/source settings including Offset in Hz. Discovery reads OS device metadata without probing serial streams. On ordinary hardware-oriented startup, automatic connection opens only the remembered selected device or a uniquely recognized GPS; a missing or ambiguous identity requires selection. A real-survey start rechecks that identity, and Connect GPS now supports manual reconnection. RF stays stopped at startup. Passive, explicit demo, managed and saved-view launches neither inherit ordinary preferences nor automatically connect GPS. Product behavior does not extend a technician's hardware authorization. Do not request the entire preferences file: its folder and device identity can contain identifying details, despite containing no keys or coordinates.
| Symptom | Safe local check | Interpretation and next action |
|---|---|---|
| Desktop window will not open | Record the error, app build/version, OS, architecture, and available graphics-session context. Confirm the artifact was built with desktop support using the documented build. | The interface requires a local GLFW/OpenGL desktop context. A headless CLI build does not supply a desktop window. Do not install a large GUI framework or change machine configuration without a reviewed need. |
| CLI reports reception but the app has no moving waterfall | Check whether the visible window was opened with --view-survey while the CLI or developer batch owns the receiver. Also check Freeze display in a live session. |
A saved-survey window does not receive the CLI's live samples. Stop the CLI and close its device handles before starting an authorized --desktop-receive-hackrf or --desktop-receive-rtlsdr session for the selected receiver. Use the visible receiver when operator observation is part of the test; saved measurement tiles do not preserve a live-waterfall replay. |
| OpenSSL version/root/configuration error during CMake | Follow Linux/local crypto setup. System OpenSSL packages do not necessarily match the reviewed static configuration. | Run the explicit local helper, then configure with --fresh. Do not replace OS libraries, relax the pin, or point at the OpenSSL executable. Include the exact configure error and platform in a support report. |
| Missing or mixed USB-prefix error during CMake | Follow local USB setup. Check OVMESH_USB_ROOT_DIR and whether the explicit helper completed. |
Prepare the reviewed shared libusb 1.0.30 and static libhackrf 2024.02.1 prefix, then configure with --fresh or a new build directory. Do not substitute host libraries or edit device permissions to fix a build-path error. Disable an unwanted adapter explicitly with its CMake option. |
| HackRF or RTL-SDR source says driver unavailable | Check the build's declared capability for that adapter and the compatibility and deployment dependency lists; do not run a USB discovery utility. | This is a build capability, not evidence about the attached device. Repair or rebuild only the approved project artifact. |
| Receiver start is denied or fails | Confirm the operator reviewed the displayed receive settings and explicitly allowed the session. Record the categorical error and whether another SDR application is already using the device. | Do not repeatedly reopen the device or change gain, amplifier, USB permissions, or firmware without authorization. A failed start is not a successful survey. |
| Window closes after the timed test, but results should remain visible | Check whether the launch used --seconds or --until-stopped and whether saving was enabled before start. |
Timed sessions intentionally stop and close at their deadline. For the next operator-controlled desktop session, use --until-stopped instead; Stop reception keeps the window open. macOS/Linux also accepts a GUI-loop-handled SIGINT stop request; Windows uses the button. A saved session can be reopened later; closed memory-only data cannot be recovered. |
| Survey or sample-rate configuration is rejected | Review the selected receiver's rate list: HackRF 8/10/12/16/20 MS/s; RTL-SDR 1/2 MS/s. Check center, Offset and supplied span against receiver compatibility. | The 80% spectrum-span limit is a guard, not proof of a calibrated passband. the approximately 16 MHz HackRF target requires separate validation. Spectrum-only surveys do not need BW/SF/CR. |
| Receiver Offset is zero, changed after restart, or unsuitable for another receiver | Check Offset and the adjacent Hz unit while stopped; distinguish ordinary desktop startup from an explicit test/hardware/saved-view mode. Confirm the settings directory and any visible preference error. | Ordinary startup remembers signed offsets within ±100,000 Hz; new profiles and legacy version-1 preferences start at 0 Hz. No +900 Hz default is built in. The value is app-profile-wide, so verify it when changing receivers. Explicit modes retain their own configuration and do not change the ordinary preference. Prior recordings retain their actual recorded offset; do not relabel them using today's preference. |
| Low input availability or growing known drops | Record input seconds, host elapsed time, dropped samples, active profile count, and processing load. Compare an authorized synthetic run with the same settings. | Application-visible drops are only part of possible loss. Do not claim lossless capture from a zero counter. Reduce workload or span only for a new, explicitly configured run and preserve the original quality evidence. |
| Healthy counters but no visible bursts from expected traffic | Check Freeze display, compare saved off-center power/activity with the live display, and record receiver settings, antenna connection and USB power/topology. | Sample delivery and a center/DC line do not prove useful RF reception. Keep stimulus evidence separate from SDR observations; compare matched settings and preserve fault evidence before restarting. A successful restart alone does not identify the cause. |
| Combined SDR/GPS reception stops on a hub, or another USB device is being added | Compare a bounded run with matched RF settings, GPS reading and health counters; then validate the intended combined workload. Record physical port layout separately from OS-reported USB paths. | Different registry paths do not prove independent physical hubs or power supplies. One successful run does not qualify a higher rate, longer survey or additional device. Stop repeated unstable runs and investigate USB bandwidth, power and source errors without assuming a cause. |
| Measurement duty is below 100% | Check application/schema version, complete FFT time, delivered time, queue drops, partial FFT tails, source-stall intervals and session completion. | Version 0.2 processes contiguous complete 4096-sample FFTs from accepted samples without deliberate window skipping. Drops and incomplete tails are gaps. Schemas 1–3 used 25-percent sampling; preserve that older coverage meaning. Zero known drops never rules out upstream loss. |
| Occupancy is zero or unavailable | Check observed time, selected frequency/time/area, saved Activity threshold, coverage gaps and recording state. | No observed time is unavailable, not quiet. A zero busy fraction only describes observed intervals at the fixed threshold; weaker signals can remain undetected. Occupancy does not identify a protocol, emitter or safe channel. |
| Frequency occupancy chart looks flat except for a center spike | Select Reveal low activity and hover the affected frequencies to compare measured busy/observed durations with the table. Check the labeled percentage ticks before interpreting height. | The default nonlinear scale reveals sparse activity that a linear 0–100% scale compresses near zero. Exact zero has no active bar; amber marks unobserved data; a minimum marker makes subpixel positive activity visible. A center spike may be a receiver artifact, not confirmed external traffic. Changing scale does not change the threshold or stored data. |
| A chart column covers several frequency bins | Hover to read the represented range and strongest bin's exact values; use the table for individual bins. | The column displays maximum single-bin occupancy, not summed percentages or combined busy-time union. This keeps narrow activity visible at limited screen resolution. Neither its height nor the global energy-event count is a per-frequency packet count. |
| Time/GPS view differs from recorded any-bin busy, or a center spike makes the raw view continuously busy | Check Exclude receiver-center region from time/GPS view, the displayed guard edges/bin count, Center-region busy and Outside-center busy. Clear the checkbox for the original all-bin comparison. | Any-bin busy means at least one frequency was active, not the fraction of bandwidth occupied. The default optional guard excludes up to five FFT bins around receiver center from time/GPS coloring only. Possible DC is not confirmed; real RF may be excluded and that region remains unassessed. Original per-frequency values remain visible with guard shading, and recordings/exports remain unfiltered. |
| Outside-center busy is unavailable or geographic points turn gray | Check whether any selected bins remain outside the guard and whether observed time is positive. Compare the raw view if needed. | An all-guard selection has no outside-center measurement; it must not appear as zero activity. Zero observed time is also unavailable. The time chart and geographic colors use the same comparison; neither establishes a clear channel. |
| GPS appears disconnected just after opening the app | Check automatic GPS, selected device and connection state in Settings > GPS & location; confirm whether startup was ordinary hardware mode or an explicit passive/demo/managed/historical mode. | Ordinary hardware startup can connect a unique recognized or remembered selected GPS. Other modes do not automatically open GPS. Missing or ambiguous identity requires selection; Connect GPS now reconnects only the selected device. Connection is distinct from a valid fix, and it never starts RF. |
| No unique GPS is selected, or the remembered GPS is unavailable | Stop reception, use Refresh GPS devices after reconnecting USB, and select the intended labeled device. Check the displayed path when models look identical. | RF can start without GPS and reports an amber warning; recording and GPS preferences are preserved. Measurements lacking a valid receiver position remain usable for frequency/time analysis but cannot be mapped. Automatic selection recognizes one u-blox USB GNSS device from VID 1546/PIDs 01a5–01a8; other serial GPS receivers require explicit selection. Port/location identities can change after a hub move. No alternate port is probed or silently substituted. On older builds that block Start, disabling automatic GPS is a temporary workaround. |
| GPS is connected but waiting for a fix, becomes stale, or reports a read error | Check the chosen device, supported baud rate and categorical status; allow reacquisition where appropriate. Confirm the receiver supplies checksummed RMC/GGA sentences. | A connected serial port is not a valid position fix. Waiting, stale and read-error states are distinct; no old fix is promoted to current. Gaps remain missing GPS. A manual fixed point is appropriate only for a stationary receiver and is not restored from preferences. |
| Receiver track appears to locate a transmitter | Check whether the field is receiver GPS or a manual receiver point. | It locates the observation, not the transmitter. Sender-reported locations are not interpreted. |
| A stationary receiver looks like it travelled around | Use Stationary / position cloud and read the distance bar before interpreting the spread. Hover reported fixes for satellite count and HDOP when available. | Both geographic plots default to unconnected reported fixes and a neutral mean reference, with equal metre scaling and at least 100 metres across the shorter display dimension. This does not detect stationary operation or establish an accurate reference location. Cloud spread is not a confidence radius or proof of movement. HDOP is dimensionless geometry, not positional error in metres; validity is not accuracy. |
| Position plot lines, scale or colors are confusing | Confirm the shared stationary/mobile view choice and distinguish the RF chart's point colors from the neutral mean reference. | Mobile / connected fixes shows estimated connections and breaks lines across missing or time-discontinuous observations. Both plots account for latitude and dateline wrapping and show metric/feet distance. Orange in Analyze means high selected-region busy time, not poor GPS accuracy. Display choices do not smooth/snap positions or alter RF associations, queries, exports or retention. |
| Saving fails or reports an incomplete session | Record the error, recording status, whether the chosen directory exists, and available local disk space using normal local OS tools. Stop the affected reception and retain the existing approved file and current results. | Failed checkpoint/finalization verification must not be treated as saved success or clear the current session through New. Do not silently switch to raw dumps, overwrite a prior survey or discard the window to hide the error. A failed final write may leave incomplete metadata; preserve that uncertainty. |
| Ordinary startup does not record as expected | Check Settings > Recording, the prepared destination and Recording to disk / Not recording status after starting. Check whether the launch was an explicit demo/test mode. | Ordinary recording defaults on, but an intentional opt-out persists. Explicit modes still need --session or their explicit save choice. Live summary rows can appear in memory-only mode and do not prove retention. Save cannot recover earlier memory-only measurements; New/close asks before discarding them. |
| Recording filename changes after stopping and starting | Compare the parent folder with the remembered location. | This is intentional: each ordinary start/restart uses a fresh UTC/random .sqlite filename. A Browse-selected filename is used once. Prior surveys are never appended to or overwritten. The folder persists across app restarts; filenames do not. |
| Saved setup is unavailable or settings could not be saved | Record the visible error and whether --settings-directory was used. Check the documented local settings directory, its availability and owner-only permissions. |
Settings are versioned, bounded and private. Malformed, unsupported, nonprivate or unreadable files are preserved and reported; there is no automatic repair or silent reset. Do not delete/replace user settings or broaden permissions without approval. Receiver/source setup and display/detection choices persist; keys, coordinates, decoded content and export privacy choices do not. |
| New file creation is refused | Use Browse recording location... or Browse export location... to choose an existing local folder and a new filename. Match the extension to the selected format. Check for an existing file, symlink/reparse point, network/mounted path, or missing write access. | Existing files are deliberately not overwritten. Choosing a path creates nothing; the final write rechecks it. Do not broaden permissions, follow network aliases, or delete existing surveys to bypass the refusal. |
| File browser does not show the expected file/folder | Stop reception, then use Home, Up, Local disk, Refresh or Show hidden. Check for the 2,000-entry truncation notice and choose a smaller folder or enter the known filename. Windows lists fixed local drives. | Listings are cached. Aliases and special files are omitted; unsupported local/network paths are refused before folder enumeration. No shell, external dialog package or recent-file history is used. The app creates its private default settings/Surveys directories; arbitrary folders still use the OS file manager. Mac filesystem/ImGui tests pass; Windows/Linux validation remains pending. |
| Export is unavailable for the current session | Check whether saving was enabled before start, then stop reception. | Memory-only sessions cannot be exported. Start a new saved session for future retention; do not imply that discarded data can be recovered. |
| Export omits GPS or descriptions/notes | Review the independent receiver-coordinate and provenance choices (--positions, --provenance). |
Both start off. Message-content exports were removed and old flags fail explicitly. Numeric RF settings/method metadata remain included. Detailed archive exports the complete metadata session, while focused reports use their analysis selection. |
| Export has no occupancy value for some bins | Check observed_seconds in those rows. |
Zero observed time produces a blank occupancy fraction, not zero activity. Preserve that distinction in downstream analysis. |
| Saved file will not open | Record the format/version error and how the file was created. Preserve the original file. | The reader rejects unrelated schemas, unexpected executable schema objects, malformed typed values, and unsupported versions. There is no generic database importer or automatic repair tool. Never enable SQLite extensions or alter the application's format identifiers to force a file open. |
| Older survey has no detailed spectrum history | Check schema version. | Schemas 1–3 open read-only without migration, but do not contain schema-4 tiles, joint activity masks or generic energy events. The UI shows a legacy unsupported-analysis message and original aggregate summaries. Never edit a schema number or invent timing/occupancy that was not recorded. |
| Energy-event count or width differs from expected packet count or modem bandwidth | Review Start / s, End / s, measured frequency edges, duration and Quality. | Events join connected above-threshold bins. Overlaps can merge, chirps can fragment and persistent events can split. Merged/truncated/boundary flags limit interpretation. Never count these as packets, devices or authenticated sources. |
| Clipped samples or near-center energy appear | Record the clipping count, supplied range, gains, amplifier state and possible DC artifact flag without changing a running survey. | Clipping indicates potentially distorted measurements; absence does not prove analog linearity. Center artifacts are flagged rather than silently discarded. Stop before changing gain; Resume creates an acquisition interval with the new setting while preserving earlier data. |
| Levels changed compared with an old survey | Check schema, FFT spacing, Hann ENBW, threshold and normalization; distinguish per-bin from integrated-region power. | Schema 4 uses uncalibrated integrated-bin power, unlike schemas 1–3. It is not dBm or power spectral density. Compare like quantities; the summed peak envelope is an upper bound, not simultaneous channel peak. |
| Background rises but event threshold does not follow it | Read the saved fixed threshold and estimated background separately. | Background is a lower spectral-percentile estimate and can be contaminated by broad activity. The threshold intentionally stays fixed; increasing background must not silently erase steady interference. Weak signals may remain below it. |
| Detailed analysis appears stale while recording or after changing controls | Distinguish the automatic LIVE FREQUENCY SUMMARY at the top from the filtered query below. Read Analyzed frequencies and Analyzed time, then select Run analysis. | The top full-range chart/table updates with incoming measurements. New observations and manual time/frequency/geographic edits require a new saved-data query. Frequency-graph clicks/drags run that query automatically on release; an updating notice precedes the read. Scale, position-display and receiver-center comparison choices apply immediately to loaded measurements. Memory-only sessions have a live summary but cannot supply saved detailed history or export. |
| Busy-time bars cannot be associated with a frequency | Read Frequency range and Width immediately above CHANNEL OCCUPANCY OVER TIME, including any excluded center interval. Click or drag a frequency graph to update the linked time/GPS view; use a full-range button to restore it. | The upper graph shows per-bin occupancy versus frequency. The time graph shows the union across the selected interval versus elapsed time. A 50% bar means some included frequency was active for half that bucket's observed time. The blue outline/captions describe the applied result, not unapplied input edits; no receiver retuning occurs. |
| Live frequency rows do not correspond to familiar mesh channels | Compare lower/upper edges, width, observed/busy time and FFT spacing. | Rows are measurement bins across the supplied range, not configured modem channels or packet counts. Busy percentage describes above-threshold observed time. Mean/peak dBFS are uncalibrated per-bin levels. Zero observation is unavailable, not a clear channel. |
| A 62.5/125/250/500 kHz or custom view has different actual edges | Compare requested Lower MHz/Upper MHz with Analyzed frequencies and FFT spacing. | Views select intersecting recorded bins and can extend to bin edges or clip at the recorded span. They are arbitrary analysis widths, not decoder presets. Combined busy time is a union of FFT activity across bins, not summed bin percentages. |
| Long survey shows wider time buckets or less GPS detail than requested | Compare Requested time detail / s, Analyzed time and the displayed detail in Full-interval overview. Select a shorter elapsed interval and run analysis again for finer detail. | The app widens buckets to cover the entire selected interval within 2,000 buckets; it does not discard later history to preserve the requested width. All observed time contributes. Each plotted GPS point uses the bucket's last recorded fix and can summarize movement. Event rows have a separate 200-row cap and truncation notice. |
| Time chart has blank, gray or striped intervals | Hover the interval and inspect observed duration plus Recorded coverage gaps. | Measured zero has no active fill but retains gray exposure marks below the axis. Zero observed time and all-guard comparisons are unavailable. Stripes identify recorded gaps, not quiet frequencies. Wide buckets can combine partial coverage; narrow the interval to inspect detail. Unknown upstream loss may remain outside explicit gap records. |
| Geographic query omits activity or has no gap rows | Disable the area filter for comparison and check GPS validity. | Measurements without valid fixes are excluded. Coverage gaps have no position and their applicability to a rectangle is unknown; omission does not imply lossless coverage there. |
A source_stall gap shows no missing sample count |
Read its elapsed interval and reason. | The sample count is unknown, not zero. Preserve the unobserved time and the separately unknown upstream-loss status. |
The current desktop intentionally hides and disables waveform discovery, packet decoding, preset/key setup and classification. This applies to existing preferences, direct desktop launches and RAK packet profiles. A missing decode table is not a receiver fault. Internal CLI/backend diagnostics are reserved for future development and are not a suggested workaround for users.
An energy event is a connected above-threshold envelope. Its width may be narrower or wider than a transmitter's modem setting, and a single transmission can produce several events. Diagnose survey issues using the recorded frequency/time scope, threshold, FFT resolution, clipping, input availability and coverage gaps. Do not label unknown energy as Meshtastic, MeshCore, LoRaWAN or a particular device.
Earlier saved diagnostic metadata remains in original files; hiding features does not erase it. Do not request raw recordings, keys or private locations in a public support report. Past synthetic decoder tests do not establish live recall. See current validation limits.
Start with source inspection and an in-repository synthetic test when development work is authorized. The storage suite exercises private/exclusive files, typed metadata roundtrip, complete-session exports, redaction, malformed-database rejection, and time/location aggregate windows using artificial fixtures. A passing test is evidence for those paths only; it does not establish live receiver performance or Windows/Linux runtime behavior.
For current spectrum behavior, the survey CLI suite uses only bounded synthetic data: command guards, private recording, five arbitrary-width readbacks, empty time/geographic selections and independent provenance export. --analyze-saved ABS_PATH --frequency-range LOW_HZ,HIGH_HZ --time-range START,END [--bounds SOUTH,NORTH,WEST,EAST] prints saved-file coverage, busy/observed time, energy events and gaps without a radio or IQ replay. Keep the reported actual bin boundaries and quality flags with any reproduced result. The measurement record defines finite resolution and field meanings; synthetic checks are not measured live sensitivity, usable passband, long-run capture or moving-GPS accuracy.
Historical surveys open through a metadata-only projection. Original files can still contain old private fields outside the application, but display/export paths exclude them. Save copy refuses unmarked historical files before output creation. New-policy copies are reconstructed from allowed records. Use synthetic canaries and byte/digest checks when reproducing projection or copy issues.
The --prepare-desktop-hackrf --spectrum-only and --prepare-desktop-rtlsdr --spectrum-only modes load survey settings without opening the radio. Keys are unnecessary for spectrum surveying; optional legacy setup can still load profiles and accept keys. With --seconds, its timer starts after the normal UI consent and successful reception start; --ui-smoke N makes preparation passive even if Start is attempted. With --until-stopped, no timer is armed and stopping acquisition leaves the window open. Do not combine --until-stopped with --seconds, --ui-smoke, or a headless mode. A setup-ready banner is not evidence that reception has started.
For a hardware-dependent issue, prepare a receive-only experiment with exact center/span/rate/correction, fixed activity threshold, gain/amplifier state, antenna/receiver description, duration or explicit stop condition, retained data and access authorization. Explicit GPS CLI access uses --gps-device ABSOLUTE_LOCAL_SERIAL_PATH --confirm-gps-access [--gps-baud 9600] in a reception mode and opens only that device before receiver start. Help, analysis and export do not open devices. Do not automatically repeat unstable tests. Keep RF, timing, classification, and storage uncertainties visible in the result.
In operator-controlled mode, Stop reception leaves results open. Timed mode retains its deadline. Preserve the original saved file and use synthetic reproductions for public support. Decoder failures must be localized to preamble, synchronization, header, payload CRC, key eligibility or schema projection; a failure counter does not identify a transmitter or prove a collision.
For suspected data disclosure or an unsafe dependency: stop the affected operation, record the application/dependency versions and a non-sensitive symptom description, preserve approved evidence, and use the established private reporting route in the security policy. Do not attach keys, raw captures, private content, or a full dump. Dependency repair goes through reviewed source/version intake and local validation, not an arbitrary upstream update.
For ordinary reporting, choose Frequency summary, Frequency interval over time, or Frequency by geographic area, with the displayed completed analysis selection. A detailed archive remains a whole-session measurement export and can be very large. An active recording or changed source session disables export; stop reception and reopen the dialog. A report is not a sample of recent UI rows.
Generate analysis report... produces readable, standalone HTML after reception stops. It uses the same completed selection and CSV aggregate calculations. No browser/PDF dependency is installed. Preview generates a local HTML copy without a destination prompt; Write report uses the selected path. Both open the OS default browser after successful generation. If opening fails, use the path in the status message; Linux desktops need their normal xdg-open handler. Preview copies stay in the default Surveys folder until deleted. Export to PDF in the browser preview opens the browser print/save dialog with all sections expanded; choose Save as PDF and a destination. Measured-zero frequency rows remain hidden unless explicitly included. Disable browser headers/footers to omit the local preview path. Missing GPS, unobserved time, center-guard effects and decoding limitations remain visible. Top time/location lists are explicitly limited; full CSV remains available. Resumed SDR reports separate acquisitions so different grids, gains or thresholds are not presented as one setup. Discovery health is retained for the latest acquisition only; earlier intervals are labeled unavailable. A read error about unsupported acquisition tables may indicate an older reader even when the numeric schema is still 5, 6 or 7. Preserve the file and use a compatible build; never strip provenance tables. The report cannot identify transmitter wattage, a particular RAK model or excessive RF power from received dBFS. See the RF gap analysis.
Session disk is a five-second background metadata estimate for the selected database and its SQLite -wal, -shm and -journal sidecars. It is not total application storage or free disk space. A smaller value after checkpoint/stop can be normal; the indicator does not trigger a checkpoint or remove files. Unavailable indicates missing/unreadable file metadata, not an empty database. New sessions clear the prior size; an old asynchronous result cannot populate the replacement session's label.
- Smaller files with
power_time_aggregatedare expected in Compact mode: activity and GPS are preserved, while power support is at most one second. Detailed mode preserves approximately 20 ms power for new sessions. - Original GPS is not rounded or smoothed by recording. Geographic cell size and export decimal places are reporting controls. Missing fixes remain explicit; cell crossing is not proof of precise movement.
- A report-limit error calls for narrower time/frequency selection or larger geographic cells. No rows are silently dropped. The original survey is unaffected, and failed report creation removes only its own new output file.
- Version 0.2 cannot read compact schema 6 or preference version 4. Use the retained new reader for compact data; use an isolated settings directory for an old binary. Do not manually change schema numbers or overwrite preferences to force compatibility.
See the compact validation record and rollback procedure.
- Application version, platform, architecture, and relevant approved dependency versions.
- Expected behavior and observed behavior, with approximate timing.
- Synthetic/hardware source, spectrum-only or optional legacy mode, explicit authorization for any device access, and non-secret acquisition settings.
- Schema and last applied frequency/time/area selection; input availability, complete-FFT measurement duty, observed/busy time, clipping, gap reasons, GPS validity and recording/completion state. Include decoder counters only for an explicitly enabled legacy profile.
- Safe reproduction performed, its result, and what remains unverified.
- Proposed correction, affected versions, validation evidence, and agreed next action.
No background monitoring, remote support connection, automatic upload, or guaranteed response time is implied by this playbook.
Use the RTL-SDR guide for the initial 1/2 MS/s limits, USB permissions, receiver selection and tuner gain. No wide-range sweep is implemented. RTL setup/read errors differ from HackRF errors. With RTL enabled, a missing reviewed libusb prefix stops CMake configuration; OVMESH_ENABLE_RTLSDR=OFF explicitly omits the adapter. Stop must release the receiver before another application can use it. Include source, rate/span, gain mode and aggregate stream counters in a support report; omit serials, keys, GPS routes and private payloads.
Use RAK setup for the supported US915 USB/LBT variant, platform requirements and explicit board selection. A generic STM32 USB label alone does not identify a concentrator. The app never probes every serial port or automatically substitutes another device.
- No waterfall or busy-time plot: expected in RAK mode. The chart shows the latest sampled RSSI histogram at each visited frequency; its percentage is a sample fraction above the displayed threshold, not continuous airtime. Gray means no displayed measurement. Switching to HackRF/RTL selects the SDR workflow.
- One board is missing or already selected: refresh USB metadata while stopped and choose distinct known boards. Keep device paths and identities out of public reports.
- No packets despite scan activity: expected in the spectrum-only desktop. Packet reception, profiles and classifications are disabled; use the sampled scan data for RF-energy reporting.
- Worker unavailable: review the CMake availability message, supported platform and presence of the matching
ovmesh-rak-workerbeside the executable. Do not download an arbitrary replacement worker. RAK is unavailable on Windows in this version. - USB timeout or receiver failure: stop, preserve the fixed error category and aggregate per-board counters, and reconnect the affected concentrator before a deliberate retry. Larger transfers caused stalls during development; bounded host requests improved the tested path, but no universal hub or endurance guarantee follows. Do not flash firmware or weaken permissions as a routine workaround.
- Report or older reader rejects a survey: RAK requires the schema-7 reader and sampled-report path. The SDR-only audit tool deliberately rejects schema 7. Do not change the schema number or reinterpret missing FFT rows as zero occupancy.
STOP drains completed worker records before finalizing. Missing END, transport failure or persistence failure makes the session incomplete while preserving successfully saved measurements. Report board count, scan range/step, readiness, completed scans/sample totals and completion/error state. GPS associations remain receiver observations, not transmitter positions. These counters replace SDR sample rate, clipping and measurement duty for this mode.