client-api

Этот документ описывает протокол для внешних клиентов API, использующих наши устройства. Если вы заинтересованы в запуске своего кода непосредственно на устройстве, ознакомьтесь с документацией по module API вместо этого.

API устройства предназначено для наличия только простого потока пакетов ToRadio и FromRadio, и весь полиморфизм обеспечивается гибким набором Google Protocol Buffers, которые передаются по сети. Мы широко используем protocol buffers как для Bluetooth API, так и для пакетов внутри mesh или при предоставлении пакетов другим приложениям на телефоне.

Версия с потоковой передачей

Этот протокол почти идентичен при развертывании поверх BLE, Serial/USB или TCP (наши три в настоящее время поддерживаемых транспорта для подключения к телефону/ПК). Большая часть этого документа касается оригинальной версии BLE, но этот раздел описывает небольшие изменения, когда этот API предоставляется поверх потокового (не датаграммного) транспорта. Версия с потоковой передачей имеет следующие изменения:

• Мы предполагаем, что поток надежный (хотя протокол пере-синхронизируется, если байты потеряны или повреждены). т.е. мы не включаем CRC или коды коррекции ошибок.
• Пакеты всегда имеют четырехбайтовый заголовок (описан ниже), префиксированный перед каждым пакетом. Этот заголовок обеспечивает кадрирование и длину.
• Поток в направлении радио состоит только из пакетов ToRadio (с дополнительными 4-байтовыми заголовками).
• Поток в направлении ПК — это поток пакетов FromRadio (с 4-байтовыми заголовками), или если конечный автомат приемника не видит допустимые байты заголовка, он может (опционально) выводить эти байты как отладочную консоль от радио. Это позволяет устройству выводить обычные серийные отладочные сообщения (которые может понять терминальная программа), но также переключаться на более структурированный набор protobuf, как только увидит, что клиент ПК отправил protobuf в его сторону.

Четырехбайтовый заголовок сконструирован так, чтобы обеспечивать кадрирование и не выглядеть как «обычный» 7-битный ASCII.

• Byte 0: START1 (0x94)
• Byte 1: START2 (0xc3)
• Byte 2: MSB длины protobuf
• Byte 3: LSB длины protobuf

Приемник проверит длину, и если она >512, то предположит, что пакет поврежден, и вернется к поиску START1. При поиске START1 любые другие символы выводятся как «отладочный вывод». Для небольшого примера реализации этого считывателя см. реализацию на python.

Bluetooth (MeshBluetoothService)

Это основной сервис Bluetooth для устройства, который предоставляет API, которое ваше приложение должно использовать для получения информации о mesh, отправки пакетов или настройки радио.

Для справочной реализации клиента, использующего этот сервис, см. RadioInterfaceService.

Типичная последовательность при подключении телефона к устройству должна быть следующей (если вы хотите наблюдать эту последовательность из python-приложения, просто запустите meshtastic --debug --info — последовательность поверх BLE идентична):

• Есть только три релевантные конечные точки (и у них есть встроенная документация BLE — так что используйте инструмент BLE по вашему выбору для наблюдения за ними): FromRadio, FromNum (отправляет уведомления, когда новые данные доступны в FromRadio) и ToRadio.
• Установите размер MTU в 512.
• Запишите protobuf ToRadio.startConfig в конечную точку «ToRadio» — это сообщает радио, что вы новое подключение и вам нужна вся NodeDB, отправленная вниз.
• Повторно читайте из конечной точки «FromRadio». Каждый раз при чтении вы получите обратно protobuf FromRadio (см. Meshtastic-protobuf). Продолжайте чтение из этой конечной точки, пока не получите пустой буфер.
• См. ниже ожидаемую последовательность для вашей начальной загрузки.
• После начальной загрузки вы должны подписаться на уведомление BLE «notify» в конечной точке «FromNum». Если приходит уведомление, это означает, что теперь в FromRadio ожидают один или несколько пакетов FromRadio. Читайте из FromRadio, пока не получите пустой пакет.
• В любое время, когда вы хотите отправить пакеты на радио, вы должны записать пакет ToRadio в ToRadio.

Ожидаемая последовательность для начальной загрузки:

• После отправки startConfig вы получите серию пакетов FromRadio. Последовательность этих пакетов будет следующей (но лучше не полагаться на это, а вместо этого обновлять вашу модель для любого полученного пакета — на основе просмотра типа).
• Прочитайте RadioConfig из «radio» — используется для получения канала и настроек радио.
• Прочитайте User из «user» — чтобы получить имя пользователя для этого узла.
• Прочитайте MyNodeInfo из «mynode», чтобы получить информацию об этом локальном устройстве.
• Прочитайте серию пакетов NodeInfo, чтобы построить копию текущей NodeDB для mesh на телефоне.
• Прочитайте пакет endConfig, который указывает, что вся необходимая вам информация отправлена.
• Прочитайте серию MeshPackets, пока не вернется пустой, чтобы получить любые сообщения, прибывшие для этого узла, пока телефон был отключен.

Для определений (и документации) protocol buffers FromRadio, ToRadio, MyNodeInfo, NodeInfo и User см. mesh.proto

UUID для сервиса: 6ba1b218-15a8-461f-9fa8-5dcae273eafd

Каждая характеристика перечислена следующим образом:

UUID Properties Description (including human readable name)

2c55e69e-4993-11ed-b878-0242ac120002 read fromradio — содержит недавно полученный пакет FromRadio, предназначенный для телефона (до MAXPACKET байт на пакет). После чтения ESP32 поместит следующий пакет в этот почтовый ящик. Если FIFO пуст, он поместит пустой пакет в этот почтовый ящик.

f75c76d2-129e-4dad-a1dd-7866124401e7 write toradio — запишите сюда protobuf ToRadio, чтобы отправить их (до длины MAXPACKET)

ed9da18c-a800-4f66-a670-aa7547e34453 read,notify,write fromnum — текущий номер пакета в сообщении, ожидающем внутри fromradio; если телефон видит это уведомление, он должен читать сообщения, пока не догонит этот номер.

5a3d6e49-06e6-4423-9944-e9de8cdf9547 notify Сообщение журнала как protobuf LogRecord. Клиентам рекомендуется слушать это уведомление и предоставлять опцию логирования этих отладочных сообщений.

6c6fd238-78fa-436b-aacf-15c5be1ef2e2 notify Сырое сообщение журнала как строка (с переводом строки). Эта характеристика УСТАРЕЛА и не должна использоваться в новом клиентском коде.

Телефон может записать в этот регистр, чтобы вернуться назад до FIXME пакетов, чтобы обработать редкий случай, когда пакет fromradio был отброшен после вызова обратного вызова ESP32, но до прибытия на телефон. Если телефон записывает в этот регистр, ESP32 отбросит старые пакеты и поместит следующий пакет >= fromnum в fromradio. Когда ESP32 продвигает fromnum, он задержит отправку уведомления на 100 мс в надежде, что уведомление никогда не потребуется отправить, если телефон уже читает из fromradio.

Примечание: если телефон когда-либо увидит уменьшение этого номера, это означает, что ESP32 перезагрузилась.

Re: Управление очередью, не все сообщения хранятся в очереди fromradio (фильтруются на основе SubPacket):

• Хранятся только самые свежие сообщения Position и User для конкретного узла.
• Все SubPackets Data хранятся.
• Сообщения WantNodeNum / DenyNodeNum не хранятся.
• Переменная keepAllPackets, если установлена в true, подавит это поведение и вместо этого сохранит все для пересылки на телефон (для отладки).

Примечание о размерах MTU

Это устройство будет работать с любым размером MTU, но настоятельно рекомендуется вызывать функцию «setMTU вашего телефона для увеличения MTU до 512 байт» сразу после подключения к сервису. Это значительно улучшит производительность при чтении/записи пакетов.

Protobuf API

При подключении вы должны отправить protobuf want_config_id на устройство. Это заставит устройство отправить свою базу данных узлов и конфигурацию радио через конечную точку fromradio. После отправки полной БД радио отправит want_config_id, чтобы указать, что отправка конфигурации завершена.

Другие сервисы Bluetooth

Этот документ фокусируется на основном протоколе устройства, но стоит отметить, что устройство также предоставляет следующие другие сервисы Bluetooth.

BluetoothSoftwareUpdate

Сервис обновления программного обеспечения. Для примера функции, выполняющей обновление программного обеспечения с использованием этого API, см. startUpdate.

UUID SoftwareUpdateService cb0b9a0b-a84c-4c0d-bdbb-442e3144ee30

Характеристики

DeviceInformationService

Реализует стандартный контракт BLE для этой службы (содержит версию программного обеспечения, модель оборудования, серийный номер и т. д...).

BatteryLevelService

Реализует стандартную службу BLE-контракта, предоставляет уровень заряда батареи таким образом, чтобы большинство клиентских устройств автоматически его понимали (т. е. он должен автоматически отображаться на экране устройств Bluetooth).