Skip to content

Latest commit

 

History

History
64 lines (51 loc) · 9.21 KB

bluetooth_api.md

File metadata and controls

64 lines (51 loc) · 9.21 KB

Общие сведения

Данный протокол основан на модели запрос-ответ. При реализации используются такие понятия, как ведущее устройство, инициирующее отправку пакетов, и ведомое, которое отвечает на полученные данные. Также предусматривается возможность отправки с ведомого устройства данных без запроса (телеметрии), такой пакет имеет специальный тип и не должен восприниматься как ответ на запрос, а должен обрабатываться отдельно

Формат передаваемых пакетов

SFD Тип Размер Данные CRC8
8 байт 1 байт 2 байта 0-65536 байт 1 байт
  • SFD (Start of Frame Delimiter) - резделитель пакетов, определяет начало нового пакета.
  • Тип – тип передаваемого пакета. Значение этого поля определяет, как должен обрабатываться пакет.
  • Размер – определяет размер поля данных пакета. В значение данного параметра не входят размеры других полей, кроме поля данных. Размер может быть нулевым, тогда поле данных отсутствует. Размер записывается с использованием little endian.
  • Данные – поле с данными пакета. Их формат зависит от типа передаваемого пакета. Если поле размер имеет нулевое значение, поле данных отсутствует.
  • CRC8 – циклически избыточный код, рассчитываемый для всех полей. При приёме это поле должно соответствовать полученым данным, иначе пакет отбрасывается, а источнику направляется соответствующее сообщение.

SFD (Start of Frame Delimiter)

Для определения начала фрейма используются 8 байт: {0xFD, 0xBA, 0xDC, 0x01, 0x50, 0xB4, 0x11, 0xFF} Для начала приема нового пакета следует определять SFD и начинать прием только после его успешной проверки.

Ограничения на работу протокола

В связи со сложностью реализации неблокирующей обработки пакетов на некоторых элементах системы, единовременно в системе может находиться только 1 пакет. Это значит, что ведущее устройство не должно отправлять новый пакет, пока не получит ответ от ведомого на предыдущий запрос. Если ведущее устройство не получило ответ в течение 5 секунд, то считается, что ведомое устройство не способно обработать пакет и возвращается ошибка таймаута.

Типы запросов

В таблице приведено описание API протеза со следующими полями:

  • Запрос - название предоставляемой команды
  • Код запроса - идентификатор, размещаемый в поле типа. Код ответа должен соответствовать коду запроса
  • Данные - Полезная нагрузка запроса. Как правило является protobuf структурой, исключем является пакет ERR.
  • Ответ - данные, которые должны возвращаться в качестве ответа
  • Описание - описание команды
Запрос Код запроса Данные Ответ Описание
Telemetry 3 - Telemetry Телеметрия протеза. Содержит актульную информацию о системе. Обновляется при подписке на телеметрию через StartTelemetry.
GetSettings 4 - GetSettings Топик хранит текущую конфигурацию протеза.
SetSettings 5 SetSettings ACK/ERR Выполнить конфигурацию протеза. После успешного завершения данные в топике GetSettings будут обновлены, а в телеметрии будет слаться новое состояния.
GetGestures 6 - GetGestures Актуальные жесты, хранимые на протезе.
SaveGesture 7 SaveGesture ACK/ERR Выполнить сохранение/обновление жеста протеза. После успешного завершения данные в топике GetGestures будут обновлены, а в телеметрии будет слаться новое время синхронизации.
DeleteGesture 8 DeleteGesture ACK/ERR Выполнить удаление жеста протеза. После успешного завершения данные в топике GetGestures будут обновлены, а в телеметрии будет слаться новое время синхронизации.
PerformGestureId 9 PerformGestureId ACK/ERR Выполнить жест по id. В телеметрии в поле Gesture будет установлено id жеста при успешном поиске по id.
PerformGestureRaw 10 PerformGestureRaw ACK/ERR Выполнить жест, который не сохранен в системе. В телеметрии в поле Gesture будет установлено id жеста, который был отправлен на исполнение.
SetPositions 11 SetPositions ACK/ERR Установить положения пальцев протеза.
UpdateLastTimeSync 12 UpdateLastTimeSync ACK/ERR Обновить общее время синхронизации жестов системы.
GetTelemetry 13 - GetTelemetry Текущая телеметрия системы.
StartTelemetry 14 StartTelemetry ACK/ERR Подписаться на получение телеметрии устройством. После отключения устройства телеметрия прекратит отправку. Повторная отправка этого запроса невозможна до остановки телеметрии через StopTelemetry.
StopTelemetry 15 - ACK/ERR Остановить отправку телеметрии.
GetMioPatterns 16 - GetMioPatterns Получить набор паттернов системы.
SetMioPatterns 17 SetMioPatterns ACK/ERR Обновить паттерны системы.

ACK/ERR

Тип ответа Код ответа Данные Описание
Empty 0 - Невалидное состояние. Не должно присутсвовать в системе, свидетельствует о серьезном нарушении работоспособности протокола.
ACK 1 - Запрос принят и исполнен.
ERR 2 ErrorType Ошибка выполнения запроса. Payload может содержать enum с уточняющей ошибкой.

Данные фреймы являются частными случами ответов. Они имеют собственный код, который записывается в Тип пакета. ACK должен возвращаться при успешном выполнении запроса, на который не подразумевается ответ ввиде какой-то структуры данных. Тип пакета равняется 1. Пакетом с типом ERR возвращается в качестве ответа, если система не смогла корректно обработать запрос. Тип пакета равняется 2. ERR в отличии от ACK может быть отправлен в качестве ответа на любой тип пакета, поэтому ведущее устройство всегда должно быть готово к получению данного фрейма. ERR может содержать дополнительную информацию об ошибке в Payload в виде protobuf сообщения Error.

Payload

См. MQTT API, полезная нагрузка идентична.