Взаимодействие с устройствами Shelly через Bluetooth Low Energy (BLE) с использованием RPC.

Обзор

Bluetooth Low Energy (BLE) стал краеугольной технологией беспроводной связи в современных интеллектуальных устройствах, обеспечивая эффективное и энергоэффективное подключение. Устройства Shelly, являющиеся неотъемлемой частью экосистем умного дома, используют BLE для обеспечения бесперебойной связи и управления. Ключевым аспектом связи Shelly с использованием BLE является реализация протоколов удаленного вызова процедур (RPC) поверх BLE, что позволяет осуществлять сложные взаимодействия между устройствами и контроллерами. В этой статье рассматриваются технические нюансы связи с устройствами Shelly с использованием BLE, с акцентом на универсальный профиль атрибутов (GATT), дескрипторы и механизмы выполнения операций чтения и записи на основе RPC.

Предварительные требования

Прежде чем углубляться в технические аспекты связи с устройствами Shelly через BLE и RPC, необходимо иметь базовое понимание следующих концепций:

Bluetooth Low Energy (BLE): Технология беспроводной персональной сети, разработанная для низкого энергопотребления и стоимости. BLE широко используется в устройствах IoT для эффективной связи.

Generic Attribute Profile (GATT): Протокол BLE, определяющий структуру и обмен данными между устройствами. GATT организует данные в сервисы и характеристики.

Remote Procedure Call (RPC): Протокол, позволяющий программе выполнять процедуру (подпрограмму) на удаленном устройстве, как если бы это был локальный вызов.

JSON: Легковесный формат обмена данными, используемый для структурирования запросов и ответов RPC.

==== Архитектура BLE RPC в Shelly ====\n Общение с устройствами Shelly через BLE и RPC включает в себя бесшовную интеграцию установления соединения, взаимодействия с конкретными службами и характеристиками GATT, формирования и отправки запросов RPC, а также получения и анализа ответов. Этот унифицированный рабочий процесс обеспечивает эффективную и надежную связь с устройствами Shelly, позволяя осуществлять разнообразную интеграцию с различными системами и языками программирования. Ключевые компоненты GATT в устройствах Shelly

UUID службы Shelly GATT: Идентифицирует основную службу, отвечающую за связь RPC.

BASH

SHELLY_GATT_SERVICE_UUID = "5f6d4f53-5f52-5043-5f53-56435f49445f"

UUID характеристики данных RPC: Обрабатывает передачу данных запроса и ответа RPC.

BASH

RPC_CHAR_DATA_UUID = "5f6d4f53-5f52-5043-5f64-6174615f5f5f"

Уникальный идентификатор характеристики управления передачей RPC: Управляет управлением передачей, в частности, отправкой информации о длине данных на устройство Shelly.

BASH

RPC_CHAR_TX_CTL_UUID = "5f6d4f53-5f52-5043-5f74-785f63746c5f"

Уникальный идентификатор характеристики управления приемом RPC: Обрабатывает управление приемом, в основном для приема информации о длине данных от устройства Shelly.

BASH

RPC_CHAR_RX_CTL_UUID = "5f6d4f53-5f52-5043-5f72-785f63746c5f"

Примечание: Эти UUID специфичны для устройств Shelly. Обратитесь к официальной документации Shelly или используйте инструменты сканирования BLE для определения соответствующих UUID.

==== Ключевые аспекты RPC поверх BLE Shelly ====\n Протокол JSON-RPC 2.0 Устройства Shelly Gen2+ используют JSON-RPC 2.0

протокол для мониторинга и управления функциями. Этот протокол симметричен, позволяя обеим сторонам — клиенту и устройству — вызывать методы и отправлять уведомления друг другу. JSON-RPC 2.0 обеспечивает структурированную и стандартизированную связь, способствуя надежному взаимодействию между клиентским приложением и устройством Shelly.

Соглашения об пространствах имен Shelly организует свои RPC-методы в пространства имен для классификации функций, повышения ясности и удобства сопровождения. Ниже приведены некоторые основные пространства имен и примеры методов:

Пространство имен Shelly: Обрабатывает управление системой, конфигурацию и состояние. Shelly.FactoryReset Shelly.ResetWiFiConfig Shelly.ListTimezones
Пространство имен Switch: Управляет дискретными выходами питания, обычно реле. Switch.Set Switch.GetConfig

Примечание: Приведенные выше пространства имен и методы являются иллюстративными примерами.' Реализация RPC в Shelly включает множество дополнительных методов в различных пространствах имен для поддержки разнообразных функций устройств. Типы фреймов Обмен данными между пользователем и устройством состоит из трех типов фреймов:

Фрейм запроса: Используется для отправки команд устройствам.

Фрейм ответа: Используется для получения ответов от устройств.

Фрейм уведомления: Используется для получения незапрошенных обновлений от устройств.

Структуры фреймов в протоколе RPC Shelly

Фрейм запроса

Фрейм запроса представляет собой объект JSON, используемый для вызова методов на устройствах Shelly. Он содержит следующие атрибуты:

jsonrpc (строка): Указывает используемую версию JSON-RPC, обычно "2.0". Это поле может быть опущено.

id (число или строка): Идентификатор запроса, используемый для сопоставления кадра ответа. Обязательно.
src (строка): Имя источника запроса (например, "user_1"). Обязательно.
method (строка): Имя вызываемой процедуры (например, "Shelly.GetDeviceInfo"). Обязательно.
params (объект): Параметры, которые принимает метод (например, {"id":1}). Необязательно.

Кадр ответа

Кадр ответа — это объект JSON, возвращаемый устройством Shelly в ответ на кадр запроса. Он содержит следующие атрибуты:

id (число или строка): Идентификатор связи. Обязательно.
src (строка): Имя источника ответа (обычно устройство Shelly). Обязательно.
dst (строка): Имя получателя (обычно отправитель запроса). Обязательно.
result (объект): Результат выполнения процедуры, если запрос был успешным. Взаимоисключающе с error.

error (объект): Содержит описание ошибки, возникшей в случае неудачного запроса. Взаимоисключающе с result.

Фрейм уведомления

Фрейм уведомления — это объект JSON, отправляемый устройством Shelly для уведомления клиента о определенных событиях или изменениях статуса без ожидания ответа. Он содержит следующие атрибуты:

src (строка): Имя источника уведомления (например, устройство Shelly). Обязательно.
dst (строка): Имя получателя (например, "user_1"). Обязательно.
method (строка): Вызванный метод (например, "NotifyStatus"). Обязательно.
params (объект): Параметры уведомления, содержащие соответствующие данные. Обязательно.

Пошаговое руководство по взаимодействию с устройствами Shelly

==== 1. Установление BLE-соединения ====\n Цель: Подключиться к устройству Shelly, используя его уникальный BLE-адрес.

Процесс:

Обнаружение устройства: Начните со сканирования ближайших BLE-устройств, чтобы идентифицировать устройство Shelly. Этого можно добиться с помощью инструментов сканирования BLE или библиотек, доступных в выбранной вами среде программирования. Устройство Shelly можно идентифицировать по его имени или BLE-адресу.

Инициирование соединения: После идентификации инициируйте соединение с устройством Shelly, используя его BLE-адрес. Это соединение станет основой для всех последующих взаимодействий. Убедитесь, что BLE-оборудование вашей системы исправно и что устройство Shelly находится в состоянии готовности к приему соединений.

Соображения:

Тайм-ауты соединения: BLE-соединения иногда могут быть нестабильными или занимать больше времени, чем ожидалось. Внедрите механизмы тайм-аутов для обработки сценариев, когда попытка соединения превышает разумное время.

Логика переподключения: В случаях неожиданных разрывов соединения наличие стратегии переподключения гарантирует, что ваше приложение сможет корректно восстановиться без необходимости ручного вмешательства.

==== 2. Взаимодействие со службами и характеристиками GATT ====\n Цель:

Получить доступ и использовать конкретные службы и характеристики GATT, необходимые для связи RPC.

Процесс:

Обнаружение служб: После подключения выполните обнаружение служб, чтобы получить список доступных служб GATT, предлагаемых устройством Shelly. Найдите службу Shelly GATT, используя ее предопределенный UUID.

Обнаружение характеристик: В рамках службы Shelly GATT определите характеристики RPC Data, RPC TX Control и RPC RX Control, используя их соответствующие UUID. Эти характеристики имеют решающее значение для отправки запросов RPC и получения ответов. См. раздел «Ключевые компоненты GATT в устройствах Shelly».

«Соображения:»

«Точность UUID:» Убедитесь, что используются правильные UUID, чтобы предотвратить ошибки связи. Использование неправильных UUID может привести к сбоям при чтении или записи в необходимые характеристики.

«Доступность характеристик:» Некоторые устройства Shelly могут иметь различия в своих профилях GATT в зависимости от модели или версии прошивки. Перед продолжением выполните проверки для подтверждения наличия всех необходимых характеристик.

==== 3. Создание RPC-запросов ====\n «Цель:»

Создать RPC-запросы в правильном формате для передачи необходимых действий устройству Shelly.

Процесс:

Структура JSON: RPC-запросы структурируются как JSON-объекты, содержащие определенные поля:
id : Уникальный идентификатор запроса, обеспечивающий возможность сопоставления ответов с соответствующими запросами.

src : Идентификатор источника, например, «user_1», указывающий на происхождение запроса.

method : Вызываемый RPC-метод, например, «Shelly.GetDeviceInfo».

params : Необязательные параметры, необходимые для RPC-метода.

JSON

{ "id": 123456789, "src": "user_1", "method": "Shelly.GetDeviceInfo", "params": {} }

Кодирование: Преобразует JSON-объект в закодированный в UTF-8 массив байтов. Этот массив байтов будет передаваться по BLE на устройство Shelly.

Вычисление длины: Определяет байтовую длину закодированного RPC-запроса. Эта информация о длине имеет решающее значение для информирования устройства Shelly о размере входящих данных.

Упаковка длины: Преобразует вычисленную длину в 4-байтовое целое число в формате big-endian. Эта упакованная длина записывается в характеристику RPC TX Control для сигнализации размера входящих данных.

Соображения:

Уникальные идентификаторы запросов: Каждый RPC-запрос должен иметь уникальный идентификатор для точного сопоставления ответов с соответствующими запросами.

Проверка параметров: Убедитесь, что параметры, предоставленные методу RPC, являются допустимыми и соответствуют ожидаемому формату. Недопустимые параметры могут привести к некорректным запросам и ошибкам от устройства Shelly.

==== 4. Отправка RPC-запросов ====\n Цель:

Передать сформированный RPC-запрос на устройство Shelly через BLE. Процесс:

Запись длины в характеристику управления передачей: Начните с записи упакованной длины RPC-запроса в характеристику управления передачей RPC. Это информирует устройство Shelly о размере входящих данных, подготавливая его к приему фактического RPC-запроса.

Введение небольшой задержки: После записи длины введите небольшую задержку (например, 1 секунду), чтобы устройство Shelly могло обработать информацию о длине. Это обеспечивает синхронизацию между клиентом и устройством перед отправкой фактических данных.

Запись RPC-запроса в характеристику данных: Запишите закодированные байты RPC-запроса в характеристику данных RPC. Это действие отправляет фактическую команду или запрос устройству Shelly, предлагая ему выполнить указанный метод RPC.

Рекомендации:

Операции записи с ответом: Используйте операции записи, которые ожидают ответа (подтверждения) от устройства Shelly. Это гарантирует, что устройство успешно получило и обработало запрос на запись.

* Обработка ошибок: Реализуйте механизмы для подтверждения успешного выполнения операций записи. Обрабатывайте сценарии, когда запись завершается неудачей, возможно, из-за проблем с подключением или неработоспособности устройства, путем повторной попытки или оповещения пользователя.

==== 5. Получение и анализ ответов RPC ====\n Цель:

Получить ответ от устройства Shelly, обеспечив целостность и корректность данных. Процесс:

Считывание длины ответа из характеристики управления приемом: Начните с считывания длины ответа из характеристики управления приемом RPC. Эта длина указывает размер входящих данных ответа, позволяя клиенту узнать, сколько байтов следует ожидать.

Распаковка длины: Преобразуйте полученное 4-байтовое целое число в формате big-endian в фактическое значение длины в байтах . Длина распакованного блока определяет общий размер данных ответа, которые необходимо прочитать.

Чтение данных ответа по частям: Из-за ограничений MTU (максимального передаваемого блока) BLE, читайте данные ответа из характеристики RPC Data по управляемым частям (обычно 20 байт). Продолжайте чтение до тех пор, пока не будет получен весь ответ, как указано в длине ответа.

Накопление данных ответа: По мере чтения каждой части добавляйте ее в буфер или массив байтов для восстановления полного ответа.

Декодирование и анализ ответа: После получения всех частей декодируйте накопленные байты в строку UTF-8 и проанализируйте объект JSON. Этот проанализированный ответ будет содержать либо результат вызова RPC, либо поле ошибки, указывающее на сбой.

Проверка ответа: Убедитесь, что идентификатор в ответе совпадает с идентификатором исходного запроса. Эта проверка подтверждает, что ответ соответствует правильному RPC-запросу. Кроме того, проверьте наличие поля результата, чтобы подтвердить успешное выполнение или соответствующим образом обработать любые сообщения об ошибках.

Соображения:

Чтение по частям: Ограниченный размер MTU BLE требует чтения данных по частям во избежание усечения или потери данных. Реализуйте логику для обработки частичного чтения и накопления данных до получения полного ответа.

Тайм-ауты: Реализуйте тайм-ауты чтения, чтобы предотвратить неопределенные периоды ожидания в случае, если устройство Shelly не отвечает или соединение прерывается.

Целостность данных: Убедитесь, что весь ответ получен и правильно проанализирован, чтобы обеспечить точную и надежную связь.

==== Решение распространенных проблем ====\n Общение с устройствами Shelly через BLE и RPC — мощный подход, но он сопряжен со своими собственными проблемами. Эффективное их решение обеспечивает надежную и стабильную интеграцию.

Управление размером MTU

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

Решение:

Чтение/запись по частям: Реализуйте логику для разделения больших объемов данных на более мелкие части, соответствующие размеру MTU (обычно 20 байт). Это гарантирует надежную передачу данных без превышения ограничений BLE.

Пример подхода:

Определите общую длину передаваемых данных.

Разделите данные на фрагменты размером не более 20 байт.

Последовательно записывайте каждый фрагмент в соответствующую характеристику.

Динамическая настройка MTU:* Некоторые библиотеки и устройства BLE поддерживают согласование большего размера MTU. Если это поддерживается, отрегулируйте MTU для оптимизации эффективности передачи данных.

Пример рекомендаций:*

Перед началом передачи данных запросите больший размер MTU, если библиотека и устройство поддерживают это.

В случае сбоя согласования вернитесь к стандартным размерам фрагментов.

Рекомендации:*

Определение возможностей MTU:* Убедитесь, что устройство Shelly и клиент BLE поддерживают большие значения MTU для максимальной пропускной способности данных.

Реализуйте механизмы резервного копирования: В случаях, когда динамическое согласование MTU не удается, используйте стандартные размеры блоков по умолчанию для обеспечения совместимости.

Тайм-ауты и повторные попытки

Проблема: BLE-соединения могут быть нестабильными, что приводит к тайм-аутам или разрывам связи, особенно в средах с помехами или при наличии нескольких подключенных устройств.

Решение:

Реализуйте тайм-ауты: Установите соответствующие значения тайм-аута для попыток подключения, операций чтения/записи и этапов обработки данных. Это предотвратит бесконечное ожидание ответов приложением.

Пример подхода:

Определите максимальное время ожидания для каждой операции.

Если операция превышает свой тайм-аут, обработайте ее корректно, повторив попытку или уведомив пользователя.

Логика повторных попыток: Внедрите механизмы повторных попыток для кратковременных сбоев, таких как временные разрывы соединения или неудачные операции записи. Ограничьте количество повторных попыток, чтобы избежать бесконечных циклов и ненужного потребления ресурсов.

Пример подхода:'

После неудачной операции подождите немного, прежде чем пытаться повторить попытку.

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

Рекомендации:

Экспоненциальная задержка: Постепенно увеличивайте время ожидания между повторными попытками, чтобы уменьшить вероятность повторных сбоев, особенно в условиях сильных помех.

Уведомления пользователей: Информируйте пользователей о постоянных сбоях после исчерпания попыток повтора, предоставляя возможность ручного вмешательства при необходимости.

Обработка ошибок

Проблема: В процессе BLE-связи могут возникать различные ошибки, включая недоступность характеристик, некорректные ответы или ошибки, специфичные для RPC.

Решение:

Комплексная обработка исключений: Внедрите надежные механизмы перехвата ошибок на каждом этапе процесса связи. Это включает обработку исключений, связанных с BLE, ошибок парсинга JSON и проблем, специфичных для RPC.

Пример подхода:'

Оберните критически важные операции в блоки try-catch.

Регистрируйте подробные сообщения об ошибках для облегчения отладки и решения проблем.

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

Пример подхода:

После получения ответа проверьте, совпадает ли идентификатор с исходным запросом.

Убедитесь, что ответ содержит либо поле результата, либо поле ошибки, чтобы определить исход.

Рекомендации:

Ведение журналов:* Ведите подробные журналы всех попыток связи, успешных и неудачных попыток. Это помогает в устранении неполадок и понимании поведения системы в различных условиях.

Плавная деградация:* В случаях некритических ошибок обеспечьте продолжение работы системы, плавно обрабатывая сбои без сбоев или нарушения других операций.

Заключение

Связь с устройствами Shelly через BLE и RPC открывает мощные возможности для создания сложных интеграций в систему «умного дома» и решений для автоматизации. Понимая архитектуру BLE, сервисы GATT и механизмы RPC, разработчики могут создавать надежные и эффективные коммуникационные платформы, адаптированные к их конкретным потребностям. Это руководство содержит подробную дорожную карту для налаживания бесперебойной связи, позволяющую вам в полной мере использовать интеллектуальные возможности Shelly на различных языках программирования и платформах.

Мы ценим ваши отзывы!

Спасибо, что уделили время прочтению нашей статьи! Была ли она полезной или интересной? Ваши замечания помогут нам улучшить нашу работу. Мы будем благодарны за любые отзывы. Если у вас есть минутка, пожалуйста, поделитесь ими с нами по следующему адресу электронной почты: Integration@shelly.com