docs: Add troubleshooting section for unresponsive device (firmware corruption)

Documented the bridge crash-loop scenario where the MeshCore device
serial port connects but firmware doesn't respond to commands,
including symptoms, what doesn't help, and the fix (re-flash firmware).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
MarekWo
2026-02-09 10:33:32 +01:00
parent 01fc9edf24
commit 1d8449138d

View File

@@ -5,6 +5,7 @@ Common issues and solutions for mc-webui.
## Table of Contents
- [Common Issues](#common-issues)
- [Device Not Responding](#device-not-responding-bridge-crash-loop)
- [Docker Commands](#docker-commands)
- [Testing Bridge API](#testing-bridge-api)
- [Backup and Restore](#backup-and-restore)
@@ -114,6 +115,39 @@ The 2-container architecture resolves common USB timeout/deadlock problems:
---
### Device not responding (bridge crash-loop)
**Symptoms:**
- `meshcore-bridge` container shows `unhealthy` status
- Bridge logs show repeated `no_event_received` errors and restarts:
```
ERROR:meshcore:Error while querying device: Event(type=<EventType.ERROR: 'command_error'>, payload={'reason': 'no_event_received'})
meshcli process died (exit code: 0)
Attempting to restart meshcli session...
```
- Device name not detected, falls back to `auto.msgs` (file not found)
- All commands (`infos`, `contacts`, etc.) time out
**What this means:**
The serial connection to the USB adapter (e.g. CP2102) is working, but the MeshCore device firmware is not responding to protocol commands. The device boots (serial port connects), but the application code is not running properly.
**What does NOT help:**
- Restarting Docker containers
- Restarting the host machine
- USB reset or USB power cycle (only resets the USB-to-UART adapter, not the MeshCore radio module)
**Fix: Re-flash the firmware**
The MeshCore device firmware is likely corrupted. Re-flash the latest firmware using the MeshCore Flasher:
1. Download the latest firmware from [MeshCore releases](https://github.com/ripplebiz/MeshCore/releases)
2. Flash using [MeshCore Flasher](https://flasher.meshcore.co) or esptool
3. Restart mc-webui: `docker compose up -d`
This can happen after a power failure during OTA update, flash memory corruption, or other hardware anomalies.
---
### Bridge connection errors
```bash