Klucze komend kontrolnych
Każda komenda SET/GET zawiera pole key identyfikujące parametr.
Klucze dzielą się na:
- Uniwersalne (0x01–0x2F) — wspólna semantyka dla wszystkich modułów
- Moduł-specyficzne (0x80–0xFF) — znaczenie zależy od
module_idw nagłówku
Klucze uniwersalne (0x01–0x2F)
Identyczna semantyka niezależnie od modułu docelowego.
Lifecycle (0x01–0x0F)
Włączanie/wyłączanie modułów, informacje.
Konfiguracja sprzętowa i DSP (0x10–0x1F)
Częstotliwość próbkowania, zakresy pomiarowe, oversampling, filtr.
Kalibracja (0x20–0x2F)
Sekwencja kalibracji interaktywnej:
flowchart LR
A[CALIB_START] --> B[CALIB_CAPTURE × N]
B --> C[CALIB_COMMIT]
A --> D[CALIB_ABORT]Tabela kluczy uniwersalnych
| Klucz | Wartość | Opis |
|---|---|---|
KEY_CTRL_INFO |
0x01 |
GET only — odczyt metadanych modułu. Payload odpowiedzi: null-terminated string (model sensora z KConfig, np. "BMP581\0") + strumień capabilities w formacie TLV. TLV Type = ID klucza konfiguracji (np. 0x10 dla obsługiwanych ODR). |
KEY_CTRL_ENABLE |
0x02 |
SET: value=1: włącz moduł, value=0: wyłącz moduł. GET: zwraca bieżący stan (1=włączony, 0=wyłączony). |
KEY_CFG_ODR |
0x10 |
SET/GET — częstotliwość próbkowania w Hz (uint16_t LE). Firmware tłumaczy wartość fizyczną na rejestry sprzętowe. Nieobsługiwana wartość → CONTROL_STATUS_INVALID_VALUE. |
KEY_CFG_MEASURE_RANGE_1 |
0x11 |
SET/GET — główny zakres pomiarowy, np. wartość w 'g' dla Accel (uint16_t LE). Jednostka zależy od modułu (g, Gauss, hPa, ...). |
KEY_CFG_MEASURE_RANGE_2 |
0x12 |
SET/GET — dodatkowy zakres pomiarowy, np. dps dla Gyro (uint16_t LE). Używany gdy moduł ma dwa niezależne zakresy (np. ACC + GYRO). |
KEY_CFG_OVERSAMPLING |
0x13 |
SET/GET — mnożnik nadpróbkowania: 1, 2, 4, 8, 16, ... (uint8_t). Firmware mapuje mnożnik na tryb OSR sensora. |
KEY_CFG_FILTER |
0x14 |
SET/GET — siła/tryb głównego filtra cyfrowego sensora (uint8_t). 0=Wyłączony, 1=Słaby, 2=Silny (szczegóły w TLV capabilities). |
KEY_CFG_RAW_MODE |
0x15 |
SET/GET — tryb surowych danych (uint8_t). 0 = dane skalibrowane (domyślnie, jeśli kalibracja dostępna), 1 = dane surowe (po bridge offset, bez hard/soft iron). SET value=0 gdy brak kalibracji → CONTROL_STATUS_NOT_READY. |
KEY_CALIB_START |
0x20 |
SET only — rozpocznij interaktywną sesję kalibracji. Moduł przechodzi w stan kalibracji. Sesję kończy COMMIT lub ABORT. Zwraca BUSY jeśli sesja już trwa. |
KEY_CALIB_ABORT |
0x21 |
SET only — przerwij sesję kalibracji, przywróć poprzednią konfigurację. |
KEY_CALIB_CAPTURE |
0x22 |
SET value=step_index — zarejestruj punkt/próbkę kalibracyjną. Dotyczy kalibracji interaktywnej (np. selector: step 0..3). |
KEY_CALIB_COMMIT |
0x23 |
SET only — zakończ sesję kalibracji, oblicz i zastosuj wyniki. Automatycznie zapisuje do NVS. |
KEY_CALIB_GET_BLOB |
0x24 |
GET only — zwraca pełny blob danych kalibracyjnych. Format zależy od modułu (np. magnetometr: hard_iron + soft_iron). |
KEY_CALIB_SET_BLOB |
0x25 |
SET value=blob — zapisz pełne dane kalibracyjne (import z zewnątrz). Automatycznie zapisuje do NVS. |
KEY_CALIB_STATUS |
0x26 |
GET only — zwraca status kalibracji. value[0]: 0 = brak kalibracji (defaults), 1 = skalibrowany. Dodatkowe bajty zależne od modułu (np. quality metric). |
Klucze moduł-specyficzne (0x80–0xFF)
Te same wartości liczbowe mogą oznaczać różne parametry w różnych modułach — rozróżnia je pole module_id w nagłówku ramki.
Przykład
KEY_GNSS_UPDATE_RATE = 0x80 i KEY_TRIGGER_SENSITIVITY = 0x80 mają tę samą wartość,
ale dotyczą różnych modułów (GNSS vs Trigger).
| Klucz | Wartość | Moduł | Opis |
|---|---|---|---|
KEY_SYSTEM_CONN_INTERVAL |
0x80 |
System (MODULE_SYSTEM = 1) | GET only — bieżący interwał połączenia BLE (uint16_t LE, jednostki 1.25 ms). Odczyt przez bt_conn_get_info(). Wymaga aktywnego połączenia. Przykład: 6 = 7.5 ms, 12 = 15 ms. Zwraca CONTROL_STATUS_NOT_READY jeśli brak połączenia. |
KEY_SYSTEM_DEVICE_NAME |
0x81 |
System (MODULE_SYSTEM = 1) | SET/GET — nazwa urządzenia w BLE advertising (UTF-8, max 28 znaków). SET: value[] = bajty UTF-8 bez null-terminatora, value_len = długość. GET: zwraca value[] = bajty UTF-8, value_len = długość. Zapisywana do NVS i wczytywana po restarcie. Zwraca CONTROL_STATUS_INVALID_VALUE jeśli len == 0 lub len > 28. |
KEY_AG_GET_TEMPERATURE |
0x80 |
Acc/Gyro (MODULE_ACC_GYRO = 2) | GET only — bieżąca temperatura chipa IMU (int16_t LE, decidegC = 0.1°C). Przykład: 250 = 25.0°C, 200 = 20.0°C. Dostępna niezależnie od stanu kalibracji. |
KEY_AG_DELETE_CALIB_POINT |
0x81 |
Acc/Gyro (MODULE_ACC_GYRO = 2) | SET only — usuń punkt kalibracyjny o podanej temperaturze. value[0-1] = T (int16_t LE, decidegC). Firmware usuwa punkt z listy i zapisuje do NVS. Jeśli nie znaleziono punktu: CONTROL_STATUS_INVALID_VALUE. |
KEY_GNSS_UPDATE_RATE |
0x80 |
GNSS (MODULE_GNSS = 5) | SET/GET — częstotliwość aktualizacji pozycji [Hz, uint8_t, 1–20]. |
KEY_GNSS_DYNAMIC_MODEL |
0x81 |
GNSS (MODULE_GNSS = 5) | SET/GET — model dynamiczny UBX (uint8_t, 0=portable…8=bike). |
KEY_TRIGGER_SENSITIVITY |
0x80 |
Trigger (MODULE_TRIGGER = 8) | SET/GET — czułość triggera (uint8_t, 1–8). |
KEY_TRIGGER_MODE |
0x81 |
Trigger (MODULE_TRIGGER = 8) | SET/GET — tryb triggera (uint8_t, trigger_mode_t). |
KEY_TRIGGER_BASES |
0x82 |
Trigger (MODULE_TRIGGER = 8) | SET/GET — bazowe wartości Z sensorów (int16_t LE × 2 = 4B). SET zapisuje do NVS. |
KEY_TRIGGER_RAW_DATA |
0x83 |
Trigger (MODULE_TRIGGER = 8) | GET only — bieżąca wartość combined (int16_t LE). Używane do pollingu w kalibracji. |
KEY_TRIGGER_THRESHOLD |
0x84 |
Trigger (MODULE_TRIGGER = 8) | SET/GET — precyzyjny próg wyzwolenia (int16_t LE). SET zapisuje do NVS. |
KEY_TRIGGER_CAPTURE_BASE |
0x85 |
Trigger (MODULE_TRIGGER = 8) | SET only (value_len=0) — przechwytuje bieżące Z1/Z2 jako bazę i zapisuje do NVS. |
KEY_MAG_NORM_TOL |
0x80 |
Magnetometer (MODULE_MAGNETOMETER = 6) | SET/GET — tolerancja normy pola (uint16_t LE nT, default 10000 = 10 µT). Definiuje szerokość okna akceptacji: [norm_ref - tol, norm_ref + tol]. SET zapisuje do NVS. |
KEY_MAG_NORM_REF |
0x81 |
Magnetometer (MODULE_MAGNETOMETER = 6) | GET only — bieżąca norma referencyjna (uint32_t LE nT). Wartość domyślna 50000 (50 µT). Aktualizowana automatycznie po kalibracji (KEY_CALIB_SET_BLOB) z pierwszych 50 skalibrowanych próbek live. |
KEY_SELECTOR_HYSTERESIS |
0x80 |
Selector (MODULE_SELECTOR = 7) | SET/GET — próg histerezy Manhattan (uint8_t). |
KEY_SELECTOR_RAW_DATA |
0x81 |
Selector (MODULE_SELECTOR = 7) | GET only — bieżące surowe wartości Y, Z z TMAG (int8_t × 2). value[0] = y (int8), value[1] = z (int8). Wymaga aktywnego pomiaru (MODULE_ENABLE=true). |
KEY_DISP_RESET |
0x80 |
Displacement (MODULE_DISPLACEMENT = 13) | SET only (value_len=0) — reset KF state: position → 0, velocity → 0, acc bias → 0, reset ZUPT windows. New origin = current position. |
KEY_DISP_SOFT_R |
0x81 |
Displacement (MODULE_DISPLACEMENT = 13) | SET/GET — siła korekcji dryfu predkości (pseudo-velocity soft constraint). value[0-1] = R × 10 (uint16_t LE, jednostka 0.1 m²/s²). 0 = wyłączone (brak soft constraint — czyste całkowanie inercyjne). Przykład: 40 = R 4.0 m²/s² (domyślnie), 10 = silniejsza korekcja. Większe R → słabsza korekcja → lepsze śledzenie długich ruchów. Mniejsze R → silniejsza korekcja → mniej dryfu w spoczynku. Zapisywane do NVS. |
KEY_KICKBACK_TIMING |
0x80 |
Kickback (MODULE_KICKBACK = 12) | SET/GET — parametry czasowe kickbacka. value[0]=on_time_ms (uint8_t), value[1]=off_time_ms (uint8_t). |
KEY_KICKBACK_TEST |
0x81 |
Kickback (MODULE_KICKBACK = 12) | SET only — uruchom jeden cykl testowy (niezależnie od triggera/selectora). Brak value. Jeśli cykl jest w toku: BUSY. |
KEY_UI_LED_COLOR |
0x80 |
UI (MODULE_UI = 11) | SET/GET — kolor LED (uint8_t, led_color_t 0–7). |
KEY_UI_BUZZER_STATE |
0x81 |
UI (MODULE_UI = 11) | SET/GET — stan buzzera (uint8_t, 0=off, 1=on). |
KEY_UI_BUZZER_FREQ |
0x82 |
UI (MODULE_UI = 11) | SET/GET — częstotliwość buzzera w Hz (uint16_t LE, 100–10000). |