ble BLECommand - prosta komunikacja przez BluetoothLE

[H1M4W4R1]

Wstęp

Bluetooth Low Energy pozwala wygodnie sterować urządzeniami z poziomu komputera, telefonu lub własnej aplikacji. Samo przygotowanie usługi BLE, charakterystyk, obsługi pakietów i ponownego uruchamiania transmisji po rozłączeniu potrafi jednak zająć więcej czasu niż właściwa logika projektu.

Biblioteka BLECommand upraszcza ten proces, udostępniając interfejs przypominający komunikację szeregową. Zamiast ręcznie przetwarzać surowe dane BLE, programista może rejestrować polecenia tekstowe i przypisywać im odpowiednie funkcje.

Projekt został przygotowany głównie dla mikrokontrolerów ESP32 korzystających z Arduino Framework i środowiska PlatformIO.

Jak działa BLECommand?

Po uruchomieniu biblioteka tworzy jedną usługę BLE zawierającą trzy charakterystyki:

• TX – odbiera polecenia wysyłane do urządzenia,
• RX – przesyła odpowiedzi na odebrane polecenia,
• NX – wysyła niezależne zdarzenia i powiadomienia generowane przez urządzenie.

Wszystkie dane są przesyłane w czytelnym formacie ASCII. Pojedyncze polecenie ma następującą postać:

POLECENIE:DANE0:DANE1;

Przykładowo polecenie:

Rotate:10;

może oznaczać obrót silnika o określoną wartość. Polecenia niewymagające parametrów można zapisać prościej:

Start;

Biblioteka potrafi obsługiwać polecenia podzielone pomiędzy kilka zapisów BLE, jak również kilka poleceń przesłanych jednocześnie. Nazwy komend nie rozróżniają wielkości liter, chociaż zalecaną konwencją jest zapis PascalCase.

Dodawanie biblioteki do projektu

Folder biblioteki należy umieścić w projekcie PlatformIO pod ścieżką: lib/BLECommand/. Następnie w programie można dołączyć jej plik nagłówkowy i uruchomić usługę BLE:

#include <Arduino.h>

#include <BluetoothCommandAPI.h>

void on_start(const char *
  const * data) {
  BluetoothCommandAPI::send("OK");
}

void setup() {
  if (BluetoothCommandAPI::begin("MyDevice") == bluetooth_command_result_ok) {
    BluetoothCommandAPI::register_command("Start", on_start);
  }
}

void loop() {
  BluetoothCommandAPI::loop();
}

Po odebraniu polecenia Start; zostanie wywołana funkcja on_start(), a urządzenie odeśle odpowiedź OK;. Wywołanie funkcji loop() jest konieczne, ponieważ biblioteka wykorzystuje ją do przetwarzania odebranych danych i wysyłania przygotowanych odpowiedzi.

Odpowiedzi i zdarzenia

Do komunikacji zwrotnej służą dwie funkcje. send() wysyła odpowiedź związaną z poleceniem klienta, natomiast notify() pozwala zgłosić zdarzenie powstałe niezależnie, na przykład zmianę stanu wejścia, zakończenie pomiaru lub wykrycie alarmu.

Przykładowe powiadomienie może wyglądać następująco:

const char *const speed[] = {"10"}; 
BluetoothCommandAPI::notify( "Rotate", speed, 1u );

Domyślnie transmisja odbywa się z częstotliwością do 20 razy na sekundę. Wartość tę można zmienić przed rozpoczęciem właściwej pracy urządzenia:

BluetoothCommandAPI::set_transmit_rate_hz(10u);

Odpowiedzi i zdarzenia są kolejkowane, a następnie łączone w większe powiadomienia BLE. Ogranicza to liczbę wykonywanych transmisji i upraszcza obsługę kilku komunikatów wygenerowanych w krótkim odstępie czasu.

Przewidywalna praca urządzenia

BLECommand korzysta ze statycznego interfejsu i podczas analizowania oraz wysyłania pakietów nie wykonuje dynamicznej alokacji pamięci. Domyślnie obsługuje między innymi:

• 16 zarejestrowanych poleceń,
• pakiety o długości do 256 bajtów,
• 16 pól danych,
• osobne bufory odpowiedzi i zdarzeń o pojemności 512 bajtów.

Wartości te można zmienić za pomocą flag kompilatora w konfiguracji PlatformIO.

build_flags = -D BLUETOOTH_COMMAND_API_MAX_PACKET_LENGTH=512 
  -D BLUETOOTH_COMMAND_API_MAX_COMMANDS=32
  -D BLUETOOTH_COMMAND_API_MAX_TRANSMIT_BUFFER_LENGTH=512
  -D BLUETOOTH_COMMAND_API_MAX_DATA_FIELDS=32

Po rozłączeniu klienta kolejki są czyszczone, dzięki czemu stare komunikaty nie zostaną wysłane do kolejnego połączonego urządzenia. Reklamowanie usługi BLE uruchamia się ponownie automatycznie, więc ESP32 może oczekiwać na następne połączenie bez dodatkowej obsługi w programie użytkownika.

Gdzie można wykorzystać BLECommand?

Biblioteka sprawdzi się przede wszystkim w urządzeniach sterowanych za pomocą prostych komend, takich jak roboty mobilne, sterowniki oświetlenia, panele automatyki, urządzenia pomiarowe czy własne akcesoria do komputerów i gier.

Największą zaletą projektu jest oddzielenie transportu BLE od właściwej logiki urządzenia. Programista definiuje polecenia i reakcje na nie, natomiast biblioteka zajmuje się składaniem pakietów, rozdzielaniem parametrów, wysyłaniem powiadomień oraz obsługą ponownego połączenia.

Kod źródłowy, przykładowy program i instrukcja instalacji są dostępne w repozytorium projektu H1M4W4R1/BLECommand.

Edytowano w piątek o 14:22 przez H1M4W4R1