mirror of
https://github.com/MarekWo/mc-webui.git
synced 2026-07-04 08:51:58 +02:00
MarekWo
b516d4e370
Root cause is device firmware contact table being empty (after reflash or reset), not the v1→v2 migration itself. DB retains hundreds of contacts from advert history but device only has those explicitly added. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
46 lines
2.4 KiB
Markdown
46 lines
2.4 KiB
Markdown
# Migration Guide: v1 to v2
|
|
|
|
## Overview
|
|
|
|
v2 replaces the `meshcore-cli` bridge with direct `meshcore` library communication. This changes how contacts and DMs work at a fundamental level.
|
|
|
|
## Breaking Changes
|
|
|
|
### 1. DM contacts must exist on the device firmware
|
|
|
|
**Symptom**: Sending a DM to an existing contact fails with "Contact not on device".
|
|
|
|
**Why**: In v2, `meshcore` communicates directly with the device firmware, which **requires** the contact to exist in its internal contact table (max 350 entries) to send a DM. The mc-webui database may contain hundreds of contacts from advertisement history, but only a handful are actually present on the device.
|
|
|
|
This can happen after:
|
|
- **Firmware reflash** — wipes the device contact table while the DB retains all contacts
|
|
- **Migration from v1** — v1 `meshcore-cli` bridge managed contacts independently; many DB contacts may have never been added to the device
|
|
- **Device reset** — any factory reset clears the firmware contact table
|
|
|
|
**How to verify**: Check the startup log for `Synced N contacts from device to database`. This N is the actual number of contacts on the device — likely much smaller than the total in the DB.
|
|
|
|
**Fix**: For each contact you want to DM:
|
|
1. Delete the contact from the Contacts page
|
|
2. Wait for their next advertisement
|
|
3. Approve the contact when it appears in the pending list
|
|
|
|
This adds the contact to the device's firmware table, enabling DM sending.
|
|
|
|
**Note**: Incoming DMs from any contact still work regardless — this only affects *sending* DMs.
|
|
|
|
### 2. Contact soft-delete preserves DM history
|
|
|
|
In v2, deleting a contact is a soft-delete (marked as `source='deleted'` in the database). This preserves DM conversation history. When the contact is re-added, it automatically "undeletes" and all previous DMs are visible again.
|
|
|
|
### 3. Database schema
|
|
|
|
v2 uses SQLite with WAL mode instead of flat JSON files. The migration from v1 data happens automatically on first startup (see `app/migrate_v1.py`). The v1 data files are preserved and not modified.
|
|
|
|
## Post-Migration Checklist
|
|
|
|
- [ ] Verify device connection (green "Connected" indicator)
|
|
- [ ] Check that channel messages are flowing normally
|
|
- [ ] Check startup log: `Synced N contacts from device to database` — this is your actual device contact count
|
|
- [ ] For each DM contact you need: delete, wait for advert, re-approve
|
|
- [ ] Verify DM sending works with a test message
|