meshtastic-local-stack

Локальный веб-клиент Meshtastic в Docker с HTTP-прокси для связи с устройством по USB/Serial.

Архитектура

Браузер
   │  HTTP :8088
   ▼
┌──────────────────────┐
│  meshtastic-web      │  (fgc92/meshtastic_local_web_client)
│  Meshtastic Web UI   │
└──────────┬───────────┘
           │  HTTP :4404  (REST API)
           ▼
┌──────────────────────┐
│  meshtastic-proxy    │  (Python + Flask)
│  Serial ↔ HTTP       │
└──────────┬───────────┘
           │  Serial /dev/ttyACM0
           ▼
     Meshtastic-устройство
     (RP2040 / ESP32 и т.д.)

Сервисы

Сервис	Образ / Сборка	Порт	Назначение
meshtastic-web	fgc92/meshtastic_local_web_client	8088→80	Веб-интерфейс Meshtastic
meshtastic-proxy	./proxy (локальная сборка)	4404→4404	HTTP-прокси для Serial-порта

---

Требования

• Docker >= 20.10 и Docker Compose >= 2.x
• Meshtastic-устройство, подключённое по USB (Serial)
• Linux-хост (требуется доступ к /dev/ttyACM0)

---

Быстрый старт

1. Подключите Meshtastic-устройство к USB.

2. Убедитесь, что устройство определилось как /dev/ttyACM0:

   ls -l /dev/ttyACM*

3. Запустите стек:

   docker compose up -d

4. Откройте браузер: http://localhost:8088 (либо адрес хоста в локальной сети)

5. В New Connection указать адрес прокси http://localhost:4404 (либо адрес хоста в локальной сети)

---

Конфигурация

Настройки Serial-порта задаются через переменные окружения сервиса proxy в docker-compose.yml:

Переменная	По умолчанию	Описание
SERIAL_PORT	/dev/ttyACM0	Путь к Serial-устройству
SERIAL_BAUD	115200	Скорость передачи (бод)

Пример: изменить Serial-порт

# docker-compose.yml
proxy:
  environment:
    - SERIAL_PORT=/dev/ttyUSB0
    - SERIAL_BAUD=115200
  devices:
    - "/dev/ttyUSB0:/dev/ttyUSB0"

---

HTTP API прокси (порт 4404)

Прокси реализует часть Meshtastic HTTP API, необходимую для работы веб-клиента.

PUT /api/v1/toradio

Отправить пакет на устройство.

Параметр	Тип	Описание
Body	application/octet-stream	Бинарный Protobuf-пакет ToRadio

Ответы:

• 204 No Content — пакет отправлен
• 400 Bad Request — тело запроса пустое

Пример:

curl -X PUT http://localhost:4404/api/v1/toradio \
     --data-binary @packet.bin

---

GET /api/v1/fromradio

Получить пакет(ы) от устройства из входящей очереди.

Query-параметр	Значения	Описание
all	true / false (по умолчанию)	true — вернуть все накопленные пакеты за один запрос

Ответ: 200 OK, Content-Type: application/octet-stream — бинарный Protobuf-пакет FromRadio (или пустое тело, если очередь пуста).

Примеры:

# Один пакет
curl http://localhost:4404/api/v1/fromradio

# Все накопленные пакеты
curl "http://localhost:4404/api/v1/fromradio?all=true"

---

Как работает прокси

proxy.py реализует Serial-framing протокол Meshtastic:

┌────────┬────────┬──────────────────────┐
│ HEADER │ LENGTH │       PAYLOAD        │
│ 2 байта│ 2 байта│     N байт           │
│ 0x94C3 │big-end.│  Protobuf ToRadio /  │
│        │        │  FromRadio           │
└────────┴────────┴──────────────────────┘

• Чтение выполняется в отдельном daemon-потоке. Входящие пакеты накапливаются в кольцевой очереди (deque, максимум 256 пакетов).
• Запись защищена threading.Lock для безопасности при параллельных запросах.
• При потере синхронизации (неверный заголовок) прокси автоматически выполняет ресинхронизацию — ищет следующий валидный заголовок 0x94C3 в буфере.
• Все HTTP-ответы содержат CORS-заголовки, что позволяет веб-клиенту обращаться к прокси напрямую из браузера.

---

Структура проекта

mesh-docker/
├── docker-compose.yml   # Определение сервисов
└── proxy/
    ├── Dockerfile       # Сборка образа прокси (python:3.11-slim)
    └── proxy.py         # Serial ↔ HTTP прокси (Flask)

---

Полезные команды

# Запустить в фоне
docker compose up -d

# Посмотреть логи в реальном времени
docker compose logs -f

# Логи только прокси
docker compose logs -f proxy

# Остановить
docker compose down

# Пересобрать образ прокси после изменений
docker compose up -d --build proxy

---

Устранение неполадок

Устройство не найдено / [Errno 2] No such file or directory: '/dev/ttyACM0'

• Проверьте подключение USB и наличие устройства: ls /dev/ttyACM*
• Обновите путь в SERIAL_PORT и devices в docker-compose.yml.

Ошибка доступа к порту Permission denied

• Добавьте пользователя в группу dialout:

  sudo usermod -aG dialout $USER

  Затем перелогиньтесь.

Веб-интерфейс не подключается к устройству

• Убедитесь, что контейнер meshtastic-proxy запущен: docker compose ps
• Проверьте, что веб-клиент настроен на адрес http://localhost:4404.