Kontekst AI — dla klienta
Kontekst przeznaczony dla Twojego AI, gdy piszesz aplikację kliencką komunikującą się z urządzeniem MWT.
Zawiera: opis wariantów urządzeń, protokół BLE (Perun Service), ramki danych, komendy SET/GET,
klucze, kody błędów — wszystko czego AI potrzebuje, żeby pomóc Ci napisać parser/handler.
Jak użyć
- Otwórz plik
doc_generated/ai_context.md w edytorze (lub skopiuj z tej strony)
- Wklej jako kontekst w ChatGPT / Claude / Copilot
Wskazówka
Plik jest generowany automatycznie przy każdym buildzie dokumentacji.
Zawiera protokoły komunikacji i pełne tabele API — bez wewnętrznych szczegółów firmware.
Pełna zawartość
MWT API V2.0 — BLE API Reference (auto-generated)
Ten plik jest generowany automatycznie z kodu źródłowego.
Możesz go wrzucić jako kontekst do ChatGPT / Claude / Copilot.
O projekcie
MWT (Modular Wireless Tracker) to rodzina bezprzewodowych modułów
sensorycznych Bluetooth Low Energy produkowanych przez Perun.
Firmware działa na SoC nRF5340 (Nordic Semiconductor) i komunikuje się
z aplikacją kliencką wyłącznie przez BLE.
Jeden firmware kompiluje się do czterech wariantów produktu:
| Wariant |
Opis |
| Base Station |
4× barometry, GNSS z RTK, buzzer, LED RGB. Hub referencyjny GNSS. |
| Body Module |
IMU, magnetometr, fuzja orientacji, barometr, GNSS z RTK. Noszony na torsie. |
| ETU (Electronic Trigger Unit) |
Jak Body + selektor trybu ognia (SAFE/SEMI/AUTO), 2× czujnik spustu (Hall), wyjście kickback. Montowany na replice. |
| Head Module |
IMU, magnetometr, fuzja orientacji, barometr; bez GNSS. Minimalny pobór mocy. Noszony na głowie. |
Sensory
| Sensor |
IC |
Zastosowanie |
| Akcelerometr + Żyroskop |
LSM6DSV32X |
Śledzenie ruchu ±32g / 1000 dps |
| Barometr |
BMP581 |
Wysokość (1–4 szt. na wariant) |
| Magnetometr |
MMC5983MA |
Azymut (heading) |
| GNSS |
u-blox ZED-F9P |
Pozycja/prędkość/heading, RTK, do 20 Hz |
| Hall-effect |
TMAG5273 (A1/B1/C1/D1) |
Czujnik spustu (×2) i selektor trybu (×1) |
| Fuzja orientacji |
Madgwick (software) |
Kwaterniony (Q1.15) z acc/gyro + mag |
Komunikacja BLE
Urządzenie udostępnia custom serwis Perun Service
(457bbb14-9c79-44a8-9810-f17bd358a200) z trzema charakterystykami:
| Charakterystyka |
UUID suffix |
Operacje |
Przeznaczenie |
| Data |
a201 |
Notify |
Strumień danych z sensorów |
| Control |
a202 |
Write + Indicate |
Komendy SET/GET |
| Device Info |
a203 |
Read |
TLV z dostępnymi modułami |
Dodatkowo: standardowy BAS (Battery Service) z procentem baterii.
MTU musi być wynegocjowane na ≥ 247 B (244 payload + 3 ATT overhead).
Protokół Control (SET / GET)
Klient wysyła komendę Write na Control, urządzenie odpowiada Indicate:
- SET:
[transaction_id][module_id][0x01][key][value...]
→ reply: [transaction_id][module_id][0x01][key][status]
- GET:
[transaction_id][module_id][0x02][key]
→ reply: [transaction_id][module_id][0x02][key][status][value...]
transaction_id jest echem — pozwala klientowi sparować zapytanie z odpowiedzią.
Klucze komend dzielą się na zakresy:
- 0x01–0x0F — lifecycle (włącz/wyłącz moduł, info)
- 0x10–0x1F — kalibracja (start/capture/commit/abort/get/set/status)
- 0x20–0x2F — system (wersja FW, uptime, error log, factory reset)
- 0x40–0xFF — moduł-specyficzne (ODR, zakres pomiarowy, czułość itd.)
| Bajt |
Pole |
Opis |
| 0 |
module_id |
Który moduł wyprodukował ramkę |
| 1 |
flags |
bit 7 = ramka błędu (payload = error_t) |
| 2 |
frame_number |
Rolling sequence counter per moduł |
| 3 |
sample_count |
Ile próbek w payload |
| 4–8 |
timestamp_first_us |
40-bit µs timestamp pierwszej próbki |
| 9–11 |
timestamp_last_delta_us |
24-bit delta do ostatniej próbki |
| 12+ |
payload |
Dane sensorowe (do 232B) |
Kalibracja
Uniwersalny protokół kalibracji (działa dla każdego modułu):
1. CALIB_START → wejście w tryb kalibracji
2. CALIB_CAPTURE(step) → zarejestruj punkt
3. CALIB_COMMIT → oblicz, zastosuj, zapisz do pamięci nieulotnej
4. CALIB_ABORT → anuluj, przywróć poprzednie dane
5. CALIB_GET / CALIB_SET → eksport/import surowego bloba
6. CALIB_STATUS → czy moduł jest skalibrowany
Błędy (error_t — 9 bajtów)
| Pole |
Opis |
level |
NONE / WARNING / CRITICAL |
source |
Peryferal lub moduł |
reason |
Co się stało (timeout, communication_failed, sensor_failure...) |
instance |
Indeks magistrali / sensora |
sensor_model |
Konkretny układ (BMP581, LSM6DSV32X, MMC5983MA...) |
detail_type |
Typ dodatkowej informacji (errno, adres I2C, mV, rejestr...) |
detail_value |
24-bit wartość szczegółowa |
Błędy są automatycznie wysyłane przez BLE po połączeniu jako data_frame
z FLAG_ERROR, lub dostępne na żądanie via KEY_SYS_ERROR_LOG /
KEY_SYS_LAST_ERROR.
Referencja API
Moduły (module_id)
| Moduł |
ID |
Opis |
MODULE_SYSTEM |
0 |
|
MODULE_ACC_GYRO |
2 |
|
MODULE_BAROMETER |
3 |
|
MODULE_BATTERY |
4 |
|
MODULE_GNSS |
5 |
|
MODULE_MAGNETOMETER |
6 |
|
MODULE_SELECTOR |
7 |
|
MODULE_TRIGGER |
8 |
|
MODULE_QUATERNION |
9 |
|
MODULE_PLAYER_STATE |
10 |
|
MODULE_UI |
11 |
|
MODULE_KICKBACK |
12 |
|
Typy komend (command)
| Komenda |
Wartość |
Opis |
CONTROL_CMD_SET |
1 |
|
CONTROL_CMD_GET |
2 |
|
Kody statusu (reply)
| Status |
Wartość |
Opis |
CONTROL_STATUS_OK |
1 |
Operacja zakończona sukcesem |
CONTROL_STATUS_UNKNOWN_ERROR |
2 |
Nieznany błąd |
CONTROL_STATUS_NOT_CALIBRATED |
3 |
Moduł nie skalibrowany |
CONTROL_STATUS_UNKNOWN_COMMAND |
4 |
Nieznana komenda |
CONTROL_STATUS_UNSUPPORTED_KEY |
5 |
Moduł nie obsługuje tego klucza |
CONTROL_STATUS_INVALID_VALUE |
6 |
Wartość poza zakresem / niepoprawna |
CONTROL_STATUS_BUSY |
7 |
Operacja w toku (np. kalibracja) |
CONTROL_STATUS_NOT_READY |
8 |
Moduł nie zainicjalizowany |
CONTROL_STATUS_HARDWARE_ERROR |
9 |
Błąd sprzętowy (np. I2C/SPI) |
Klucze uniwersalne (0x01–0x3F)
| Klucz |
Wartość |
Opis |
KEY_MODULE_ENABLE |
0x01 |
SET value=1: włącz moduł, value=0: wyłącz moduł. GET: zwraca bieżący stan (1=włączony, 0=wyłączony). |
KEY_MODULE_INFO |
0x02 |
GET only — zwraca informacje o module (wersja sensora, capabilities). Format odpowiedzi jest zależny od modułu. |
KEY_CALIB_START |
0x10 |
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 |
0x11 |
SET only — przerwij sesję kalibracji, przywróć poprzednią konfigurację. |
KEY_CALIB_CAPTURE |
0x12 |
SET value=step_index — zarejestruj punkt/próbkę kalibracyjną. Dotyczy kalibracji interaktywnej (np. selector: step 0..3). |
KEY_CALIB_COMMIT |
0x13 |
SET only — zakończ sesję kalibracji, oblicz i zastosuj wyniki. Automatycznie zapisuje do NVS. |
KEY_CALIB_GET |
0x14 |
GET only — zwraca pełny blob danych kalibracyjnych. Format zależy od modułu (np. magnetometr: hard_iron + soft_iron). |
KEY_CALIB_SET |
0x15 |
SET value=blob — zapisz pełne dane kalibracyjne (import z zewnątrz). Automatycznie zapisuje do NVS. |
KEY_CALIB_STATUS |
0x16 |
GET only — zwraca status kalibracji. value[0]: 0 = brak kalibracji (defaults), 1 = skalibrowany. Dodatkowe bajty zależne od modułu (np. quality metric). |
KEY_SYS_FW_VERSION |
0x20 |
GET only — wersja firmware (string, null-terminated). |
KEY_SYS_UPTIME |
0x21 |
GET only — uptime w sekundach (uint32_t LE). |
KEY_SYS_LAST_ERROR |
0x22 |
GET only — ostatni błąd (serialized error_t). |
KEY_SYS_FACTORY_RESET |
0x23 |
SET only — factory reset (wymaż NVS, reboot). value[0] = 0xA5 (magic byte, ochrona przed przypadkowym wywołaniem). |
KEY_SYS_ERROR_LOG |
0x24 |
GET only — flush kolejki błędów via NOTIFY. Reply value[0] = liczba błędów w kolejce. Błędy przychodzą jako data_frame z FLAG_ERROR. |
Klucze moduł-specyficzne (0x40–0xFF)
| Klucz |
Wartość |
Moduł |
Opis |
KEY_GNSS_UPDATE_RATE |
0x40 |
GNSS (MODULE_GNSS = 5) |
SET/GET — częstotliwość aktualizacji pozycji [Hz, uint8_t, 1–20]. |
KEY_GNSS_DYNAMIC_MODEL |
0x41 |
GNSS (MODULE_GNSS = 5) |
SET/GET — model dynamiczny UBX (uint8_t, 0=portable…8=bike). |
KEY_AG_RANGE |
0x40 |
Acc/Gyro (MODULE_ACC_GYRO = 2) |
SET/GET — zakres pomiarowy. SET: value[0]=lsm6dsv32x_range_acc_t, value[1]=lsm6dsv32x_range_gyro_t. GET: identyczny format. |
KEY_AG_ODR |
0x41 |
Acc/Gyro (MODULE_ACC_GYRO = 2) |
SET/GET — ODR (Output Data Rate). value[0]=lsm6dsv32x_odr_t, value[1]=lsm6dsv32x_haodr_sel_t. |
KEY_BARO_OSR |
0x40 |
Barometer (MODULE_BAROMETER = 3) |
SET/GET — oversampling (OSR). value[0]=bmp581_osr_t (ciśnienie), value[1]=bmp581_osr_t (temperatura). |
KEY_BARO_IIR |
0x41 |
Barometer (MODULE_BAROMETER = 3) |
SET/GET — filtr IIR. value[0]=bmp581_iir_t. |
KEY_TRIGGER_SENSITIVITY |
0x40 |
Trigger (MODULE_TRIGGER = 8) |
SET/GET — czułość triggera (uint8_t, 1–8). |
KEY_TRIGGER_MODE |
0x41 |
Trigger (MODULE_TRIGGER = 8) |
SET/GET — tryb triggera (uint8_t, trigger_mode_t). |
KEY_TRIGGER_BASES |
0x42 |
Trigger (MODULE_TRIGGER = 8) |
GET only — bazowe wartości Z sensorów (int16_t LE × 2 = 4B). |
KEY_SELECTOR_HYSTERESIS |
0x40 |
Selector (MODULE_SELECTOR = 7) |
SET/GET — próg histerezy Manhattan (uint8_t). |
KEY_KICKBACK_TIMING |
0x40 |
Kickback (MODULE_KICKBACK = 12) |
SET/GET — parametry czasowe kickbacka. value[0]=on_time_ms (uint8_t), value[1]=off_time_ms (uint8_t). |
Stałe Data Frame
| Stała |
Wartość |
Opis |
DATA_FRAME_HEADER_SIZE |
12 |
|
DATA_FRAME_PAYLOAD_MIN |
1 |
|
DATA_FRAME_PAYLOAD_MAX |
232 |
|
DATA_FRAME_MODULE_ID_INDEX |
0 |
|
DATA_FRAME_FLAGS_INDEX |
1 |
|
DATA_FRAME_FRAME_NUMBER_INDEX |
2 |
|
DATA_FRAME_SAMPLE_COUNT_INDEX |
3 |
|
DATA_FRAME_TIMESTAMP_FIRST_INDEX |
4 |
|
DATA_FRAME_TIMESTAMP_LAST_DELTA_INDEX |
9 |
|
DATA_FRAME_PAYLOAD_INDEX |
12 |
|
Błędy — Poziom
| Poziom |
Wartość |
Opis |
ERROR_LEVEL_NONE |
0 |
|
ERROR_LEVEL_WARNING |
1 |
|
ERROR_LEVEL_CRITICAL |
2 |
|
Błędy — Źródło
| Źródło |
Wartość |
Opis |
ERROR_SOURCE_NONE |
0 |
|
ERROR_SOURCE_PERIPHERAL_ADC |
1 |
|
ERROR_SOURCE_PERIPHERAL_BLE |
2 |
|
ERROR_SOURCE_PERIPHERAL_GPIO |
3 |
|
ERROR_SOURCE_PERIPHERAL_GPIOTE |
4 |
|
ERROR_SOURCE_PERIPHERAL_PWM |
5 |
|
ERROR_SOURCE_PERIPHERAL_UART |
6 |
|
ERROR_SOURCE_PERIPHERAL_I2C |
7 |
|
ERROR_SOURCE_PERIPHERAL_SPI |
8 |
|
ERROR_SOURCE_PERIPHERAL_STORAGE |
9 |
|
ERROR_SOURCE_MODULE_ACC_GYRO |
102 |
|
ERROR_SOURCE_MODULE_BAROMETER |
103 |
|
ERROR_SOURCE_MODULE_BATTERY |
104 |
|
ERROR_SOURCE_MODULE_GNSS |
105 |
|
ERROR_SOURCE_MODULE_MAGNETOMETER |
106 |
|
ERROR_SOURCE_MODULE_SELECTOR |
107 |
|
ERROR_SOURCE_MODULE_TRIGGER |
108 |
|
ERROR_SOURCE_MODULE_QUATERNION |
109 |
|
ERROR_SOURCE_MODULE_PLAYER_STATE |
110 |
|
ERROR_SOURCE_MODULE_LED |
111 |
|
ERROR_SOURCE_MODULE_BUZZER |
112 |
|
ERROR_SOURCE_MODULE_KICKBACK |
113 |
|
Błędy — Przyczyna
| Przyczyna |
Wartość |
Opis |
ERROR_REASON_NONE |
0 |
|
ERROR_REASON_COMMUNICATION_FAILED |
1 |
|
ERROR_REASON_EXTERNAL_MAGNETIC_FIELD |
2 |
|
ERROR_REASON_INITIALIZATION_FAILED |
3 |
|
ERROR_REASON_INVALID_CONFIGURATION |
4 |
|
ERROR_REASON_LOW_LEVEL |
5 |
|
ERROR_REASON_OUT_OF_RANGE |
6 |
|
ERROR_REASON_SENSOR_FAILURE |
7 |
|
ERROR_REASON_TIMEOUT |
8 |
|
ERROR_REASON_VOLTAGE_TOO_HIGH |
9 |
|
ERROR_REASON_VOLTAGE_TOO_LOW |
10 |
|
ERROR_REASON_CONFIGURATION_ERROR |
11 |
|
Błędy — Model sensora
| Model sensora |
Wartość |
Opis |
ERROR_SENSOR_MODEL_NONE |
0 |
|
ERROR_SENSOR_MODEL_BMP581 |
1 |
|
ERROR_SENSOR_MODEL_IN_S66TBTRGB |
2 |
|
ERROR_SENSOR_MODEL_LSM6DSV32X |
3 |
|
ERROR_SENSOR_MODEL_MMC5983MA |
4 |
|
ERROR_SENSOR_MODEL_TMAG5273A1 |
5 |
|
ERROR_SENSOR_MODEL_TMAG5273B1 |
6 |
|
ERROR_SENSOR_MODEL_TMAG5273C1 |
7 |
|
ERROR_SENSOR_MODEL_TMAG5273D1 |
8 |
|
ERROR_SENSOR_MODEL_ZED_F9P_05B |
9 |
|
Błędy — Typ szczegółu
| Typ szczegółu |
Wartość |
Opis |
ERROR_DETAIL_NONE |
0 |
|
ERROR_DETAIL_ERRNO |
1 |
value = errno (e.g., EIO, ETIMEDOUT) |
ERROR_DETAIL_I2C_ADDRESS |
2 |
value = 7-bit addr (0..127) |
ERROR_DETAIL_MILLIVOLTS |
3 |
value = mV |
ERROR_DETAIL_NRFX_ERROR_CODE |
4 |
value = nrfx_err_t (as a number) |
ERROR_DETAIL_PERCENT |
5 |
value = 0..100 |
ERROR_DETAIL_RAW_VALUE |
6 |
value = raw |
ERROR_DETAIL_REGISTER |
7 |
value = register address (0..65535) |