diff --git a/.gitea/workflows/check.yml b/.gitea/workflows/check.yml index 638d355..cdf7f21 100644 --- a/.gitea/workflows/check.yml +++ b/.gitea/workflows/check.yml @@ -9,8 +9,8 @@ jobs: runs-on: ubuntu-24.04 container: python:3.12.12-slim-bookworm steps: - # nodejs jest potrzebne akcjom JS (checkout, upload-artifact) i musi być - # zainstalowane przed pierwszym krokiem "uses". + # nodejs is needed by the JS actions (checkout, upload-artifact) and must be + # installed before the first "uses" step. - name: Install build dependencies run: | apt-get update @@ -21,11 +21,12 @@ jobs: - name: All tests without hardware run: bash ./tools/check_all - name: Upload validation reports - # Oficjalny upload-artifact@v4+ odmawia pracy poza github.com (pozostałe - # instancje uznaje za GHES), a GITHUB_SERVER_URL z konteksta zadania nadpisuje - # env kroku, więc obejście przez env nie działa. To fork polecany przez - # społeczność Gitei: kod oficjalnego v4, w którym jedynie isGhes() zwraca - # false. Przypięty do commita gałęzi v4 zamiast do pływającej nazwy. + # The official upload-artifact@v4+ refuses to run outside github.com + # (other instances are treated as GHES), and GITHUB_SERVER_URL from the + # job context overrides the step env, so the env workaround does not + # work. This is a fork recommended by the Gitea community: the official + # v4 code with only isGhes() returning false. Pinned to a commit of the + # v4 branch instead of a floating ref. uses: https://github.com/ChristopherHX/gitea-upload-artifact@81f940d004763f986ba3582c007fd842dd5cb0d7 with: name: validation-reports diff --git a/CHANGELOG.md b/CHANGELOG.md index 12da5ca..ad51a8f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,120 +1,129 @@ # Changelog -## Zmiany robocze po 2.0.0-rc.1 +## Work in progress after 2.0.0-rc.1 -- Mikrodrzemki zamiast jednego długiego snu (`config.h`: `NAP_PERIOD_MS`): - LED miga co ok. 2 s także między wysyłkami, po każdym budzeniu timera jest - widoczne mignięcie (`NAP_AWAKE_MS`). Sen to reszta okresu po czasie - boot + okno; TX ramek pozostaje co interwał (licznik snu w pamięci RTC, - `interval` wchodzi w życie przy następnym cyklu). `power_deep_sleep` - przyjmuje milisekundy. Wcześniej budzenie z timera gasiło LED w tym samym - `loop()` — błysk trwał kilka ms i budzenie było niewidoczne. -- Przycisk: domyślnie przycisk BOOT płytki (`PIN_BUTTON = 0`, GPIO0) — - potwierdzone działanie EXT1 na sprzęcie. Zewnętrzny przycisk na GPIO3 - przez `-DPIN_BUTTON=3`. Uwaga: GPIO0 to pin strapping (trzymany przy - starcie/reset uruchamia bootloader). Każdy gest przycisku daje okno - konsoli 10 s (wg `POWER.md`) — urządzenie nie zasypia natychmiast po - np. wyjściu z LEARN/SINGLE. LEARN/SINGLE nadal nie śpią (bez zmian). -- Kalibracja pola ciśnienia `P` wg wyświetlacza auta: skala rtl_433 - (2,5 kPa/bit) nie jest potwierdzona (nagrania mają `P=0`), a auto pokazywało - 284 kPa dla 260 kPa. Korekta skalująca `TPMS_PRESSURE_KPA100_PER_RAW` - (273 = 2,73 kPa/bit; `P=95` dla 260 kPa) w firmware, modelu Pythona - i oczekiwaniach `verify_rtl433.py`. Potwierdzone na sprzęcie: - 260 kPa → 260 kPa na wyświetlaczu auta. -- Audyt integracji sprzęt–firmware (2026-10-28), spójność ESP32-S2-MINI + - CC1101 SMA + LM317T: - - Budzenie EXT1: pociągnięcia RTC przycisku i LF konfigurowane przed deep - sleep. Pull-up cyfrowy (`pinMode`) nie działa przy wyłączonej domenie - RTC_PERIPH (dokumentacja ESP-IDF), więc piny budzenia pływały i EXT1 - mogło budzić losowo. Zalecany też zewnętrzny 10 kΩ. - - Konsola: parsowanie liczb odrzuca NaN i nieskończoność (wcześniej - `pressure nan` / `rf freq nan` przechodziły walidację; NaN trafiał do NVS - jako ciśnienie, a `rf freq nan` blokował późniejsze zapisy). Logika - parsowania wydzielona do przenośnego modułu `parse` z testami native. - - Zasilanie: dzielnik ADC R2 270 kΩ → 180 kΩ. Poprzedni dzielnik nasycał - ADC (pełna skala 2,5 V) już powyżej ok. 11,8 V i nie mierzył napięcia - instalacji 12 V w warunkach pracy 12,6–14,4 V. - - `tools/package_release.sh`: pełny obraz `merge_bin` z `--flash-freq 80m` - zgodnym z manifestem `lolin_s2_mini`; poprzednie `40m` nadpisywało - nagłówek bootloadera (80 MHz) innym parametrem niż build. - - `tools/tpms_frame.py`: saturacja temperatury do 0–255 zgodna z firmware - (temperatury ≤ −19 °C psuły ramkę w modelu Pythona). - - Testy: ujemny przypadek checksum odwraca całą komórkę Manchester - (poprzednio ćwiczył naruszenie Manchester zamiast sumy); nowy zestaw - `test_parse` (zakresy, NaN/inf); poprawiony diagram bitów w `PROTOCOL.md`. -- Sprzęt docelowy zmieniono na ESP32-S2-MINI (ESP32-S2FN4R2, np. - ARD-ESP32-S2-MINI, płytka `lolin_s2_mini`); zaktualizowano target PlatformIO, - natywne USB CDC, pinout SPI/przycisku/ADC i polaryzację wbudowanej LED - (GPIO15, aktywna HIGH). ADC zasilania na GPIO1, opcjonalny LF na GPIO14. - `btStop()` kompilowane tylko na chipach z Bluetooth — ESP32-S2 go nie ma. -- Moduł radiowy CC1101 433 MHz SPI ze złączem SMA i anteną (ARD-CC1101-ANT). -- Zasilanie zewnętrzne przez regulowany LM317T (TO-220 metal, 1,25–37 V, - 1,5 A): właściwy pinout ADJ–VOUT–IN, TAB = VOUT, dzielnik 240/390 Ω - dający ok. 3,28 V, kondensatory oraz wymagania ochrony i termiki. -- Docelowe zasilanie z gniazda zapalniczki samochodowej: ładowarka USB - (wariant A) albo LM317T (wariant B). Przy gnieździe zasilanym „po stacyjce” - emulator nie pobiera prądu na postoju; brak transmisji parkingowej jest - akceptowalny, bo ECU auta nie odczytuje TPMS przy wyłączonym zapłonie. -- Obrazy release dla ESP32-S2 używają `esptool --chip esp32s2` i bootloadera od - adresu `0x1000`; stare obrazy dla ESP32-C3 i ESP32-WROOM nie są kompatybilne. +- Micro-naps instead of one long sleep (`config.h`: `NAP_PERIOD_MS`): + the LED blinks approximately every 2 s also between transmissions, and after + every timer wake a blink is visible (`NAP_AWAKE_MS`). Sleep is the remainder + of the period after boot time + window; TX of frames remains on the interval + (sleep counter in RTC memory, `interval` takes effect on the next cycle). + `power_deep_sleep` takes milliseconds. Previously, waking from the timer + turned the LED off in the same `loop()` — the blink lasted a few ms and the + wake-up was invisible. +- Button: the board's BOOT button by default (`PIN_BUTTON = 0`, GPIO0) — + EXT1 behaviour confirmed on hardware. An external button on GPIO3 is + selected with `-DPIN_BUTTON=3`. Note: GPIO0 is a strapping pin (held at + power-up/reset it starts the bootloader). Every button gesture opens a 10 s + console window (per `POWER.md`) — the device does not fall asleep + immediately after, e.g., leaving LEARN/SINGLE. LEARN/SINGLE still do not + sleep (unchanged). +- Calibration of the pressure field `P` against the car display: the rtl_433 + scale (2.5 kPa/bit) is not confirmed (the captures have `P=0`), and the car + showed 284 kPa for 260 kPa. The scaling correction + `TPMS_PRESSURE_KPA100_PER_RAW` (273 = 2.73 kPa/bit; `P=95` for 260 kPa) was + applied in the firmware, the Python model, and the `verify_rtl433.py` + expectations. Confirmed on hardware: 260 kPa → 260 kPa on the car display. +- Hardware–firmware integration audit (2026-10-28), consistency of + ESP32-S2-MINI + CC1101 SMA + LM317T: + - EXT1 wake: the RTC pulls for the button and LF are configured before deep + sleep. A digital pull-up (`pinMode`) does not work with the RTC_PERIPH + domain disabled (ESP-IDF documentation), so the wake pins floated and + EXT1 could wake randomly. An external 10 kΩ is also recommended. + - Console: number parsing rejects NaN and infinity (previously + `pressure nan` / `rf freq nan` passed validation; NaN ended up in NVS as + pressure, and `rf freq nan` blocked later writes). The parsing logic was + extracted into the portable `parse` module with native tests. + - Power: ADC divider R2 270 kΩ → 180 kΩ. The previous divider saturated the + ADC (2.5 V full scale) already above about 11.8 V and did not measure the + 12 V installation under a 12.6–14.4 V operating range. + - `tools/package_release.sh`: the full `merge_bin` image uses `--flash-freq + 80m` consistent with the `lolin_s2_mini` manifest; the previous `40m` + overwrote the bootloader header (80 MHz) with a parameter that differed + from the build. + - `tools/tpms_frame.py`: temperature saturation to 0–255 consistent with + the firmware (temperatures ≤ −19 °C corrupted the frame in the Python + model). + - Tests: the negative checksum case now inverts the whole Manchester cell + (previously it exercised a Manchester violation instead of the sum); a new + `test_parse` suite (ranges, NaN/inf); corrected the bit diagram in + `PROTOCOL.md`. +- Target hardware changed to ESP32-S2-MINI (ESP32-S2FN4R2, e.g. + ARD-ESP32-S2-MINI, board `lolin_s2_mini`); updated the PlatformIO target, + native USB CDC, SPI/button/ADC pinout, and built-in LED polarity + (GPIO15, active HIGH). Supply ADC on GPIO1, optional LF on GPIO14. + `btStop()` is compiled only on chips with Bluetooth — the ESP32-S2 has none. +- CC1101 433 MHz SPI radio module with an SMA connector and antenna + (ARD-CC1101-ANT). +- External power through an adjustable LM317T (TO-220 metal, 1.25–37 V, + 1.5 A): the correct ADJ–VOUT–IN pinout, TAB = VOUT, a 240/390 Ω divider + giving about 3.28 V, capacitors, and protection and thermal requirements. +- Target power from the car cigarette-lighter socket: a USB charger (variant + A) or the LM317T (variant B). With an ignition-switched socket the emulator + draws no current while parked; the lack of parking transmission is + acceptable because the car ECU does not read TPMS with the ignition off. +- ESP32-S2 release images use `esptool --chip esp32s2` and a bootloader at + address `0x1000`; older images for ESP32-C3 and ESP32-WROOM are incompatible. ## 2.0.0-rc.1 — 2026-10-27 -Release candidate bez testu fizycznego CC1101 i samochodu. +Release candidate without a physical CC1101 test and a car test. -### Dodane +### Added -- Trwała konfiguracja NVS z wersją, CRC32, walidacją zakresów, unikalnymi ID, - przywracaniem fabrycznym i bezpiecznymi domyślnymi. -- Konsola: Clone IDs, generator nowych ID, ciśnienia/temperatura, interwały, - ograniczone RF, LEARN/SINGLE i diagnostyka bez rekompilacji. -- Przenośna maszyna stanów z fake clock/radio, timeoutami i kolejnością - FL→FR→RR→RL. Testy restartu, ACC, błędów radia i zawinięcia `millis()`. -- Niezależna walidacja czterech nagrań referencyjnych oraz syntetycznych CU8 - przypiętym rtl_433; testy negatywne checksum/Manchester/ucięcie. -- `tools/check_all`, Dockerfile, Gitea Actions, skrypty obrazów i SHA-256. -- Polska dokumentacja użytkownika, sprzętu, zasilania, bezpieczeństwa i HIL. +- Persistent NVS configuration with versioning, CRC32, range validation, + unique IDs, factory reset, and safe defaults. +- Console: Clone IDs, a new-ID generator, pressures/temperature, intervals, + limited RF, LEARN/SINGLE, and diagnostics without recompilation. +- Portable state machine with fake clock/radio, timeouts, and the + FL→FR→RR→RL order. Restart, ACC, radio-failure, and `millis()` wrap tests. +- Independent validation of four reference recordings and synthetic CU8 with + the pinned rtl_433; negative checksum/Manchester/truncation tests. +- `tools/check_all`, Dockerfile, Gitea Actions, image scripts, and SHA-256. +- User, hardware, power, safety, and HIL documentation. -### Zmienione +### Changed -- Domyślnie 260 kPa i −10 dBm, tylko OOK. Zachowany enkoder 30 B Manchester, - który przechodzi niezależne dekodowanie. -- CC1101 czeka na `MARCSTATE=IDLE`, kontroluje underflow i pozostałe bajty, - zamiast polegać wyłącznie na czasie i `TXBYTES=0`. -- Zwykły RTC nie otwiera okna konsoli; transmisja i powrót do snu ograniczają - szacowany pobór. Okno konsoli pozostaje po interakcji użytkownika. -- Pełny build z `-Wall -Wextra -Werror`; cppcheck bez defektów. +- Defaults of 260 kPa and −10 dBm, OOK only. The 30-byte Manchester encoder + is preserved and passes independent decoding. +- The CC1101 waits for `MARCSTATE=IDLE`, checks underflow and leftover bytes, + instead of relying only on timing and `TXBYTES=0`. +- A plain RTC wake does not open the console window; transmission and the + return to sleep limit the estimated consumption. The console window remains + open after user interaction. +- Full build with `-Wall -Wextra -Werror`; cppcheck with zero defects. -### Usunięte / naprawione +### Removed / fixed -- Usunięto zgadywany `TPMS_FLAGS_LOWBAT_MASK` i sprzężenie niskiego zasilania - emulatora z symulowanym sensorem. Zasilanie jest tylko ostrzeżeniem lokalnym. -- Usunięto FSK z głównego flow: brak dowodu dla analizowanego profilu. -- Usunięto `PARKING_SHUTDOWN`; każdy deep sleep ma RTC, więc restart ACC nie - może zostawić urządzenia trwale uśpionego. -- Domyślne, niezwalidowane wejście LF jest wyłączone. Podstawowy LEARN nie - wymaga EL-50448. -- Usunięto rekomendację MCP1703 + TVS 24 V jako ochrony automotive i obietnice - wieloletniej pracy baterii. Zasilanie 12 V ma wymagania projektowe, nie HIL. +- Removed the guessed `TPMS_FLAGS_LOWBAT_MASK` and the coupling between the + emulator's low supply and the simulated sensor. The supply is only a local + warning. +- Removed FSK from the main flow: no evidence for the analysed profile. +- Removed `PARKING_SHUTDOWN`; every deep sleep has an RTC alarm, so an ACC + restart cannot leave the device permanently asleep. +- The default, unvalidated LF input is disabled. Basic LEARN does not require + the EL-50448. +- Removed the recommendation of MCP1703 + 24 V TVS as automotive protection + and the promises of multi-year battery operation. The 12 V supply has + design requirements, not HIL. -### Iteracje audytu +### Audit iterations -1. **Stan początkowy:** 7/7 native i build PASS, ale konfiguracja przez - rekompilację, monolit stanów, lowbat i zasilanie wymagały naprawy. Utworzono - `archive/pre-opencode`. -2. **Model danych:** dodano NVS/CRC/walidację i przenośne tryby. Pierwszy test - wykrył błędne oczekiwania testów dla zaległego tick i natychmiastowego TX; - po korekcji 20/20 native i ESP32 build PASS. -3. **Walidacja RF:** audyt czterech nagrań potwierdził 16 powtórzeń i zmienne - odstępy. Zastąpiono pojedynczy wektor pełnym skryptem; 64/64 referencji, - 3/3 syntetycznych i 3/3 negatywnych PASS. -4. **Energia:** wykryto okno konsoli po każdym RTC; ograniczono je do interakcji. - Pobór nadal wyraźnie oznaczony jako szacowany. -5. **Statycznie:** cppcheck wskazał inicjalizację struktur z float przez memset; - zamieniono na inicjalizację wartości i osiągnięto 0 defektów. +1. **Initial state:** 7/7 native and build PASS, but configuration through + recompilation, a monolithic state machine, lowbat, and power needed + repair. Created `archive/pre-opencode`. +2. **Data model:** added NVS/CRC/validation and portable modes. The first + test caught wrong test expectations for a pending tick and immediate TX; + after correction, 20/20 native and the ESP32 build PASS. +3. **RF validation:** an audit of four recordings confirmed 16 repetitions + and variable gaps. A single vector was replaced with the full script; + 64/64 references, 3/3 synthetic, and 3/3 negative PASS. +4. **Energy:** a console window after every RTC wake was detected; it was + limited to interaction. Consumption is still clearly marked as estimated. +5. **Static analysis:** cppcheck flagged memset-initialised float structs; + replaced with value initialisation and reached 0 defects. -### Niezweryfikowane fizycznie +### Not physically verified -CC1101 na antenie/analizatorze, RTL-SDR z prototypem, pobór, brownout, ACC, -aktualizacja flash, Clone IDs i LEARN z konkretnym Oplem. Brak oznaczenia -„validated”. +CC1101 on an antenna/analyser, RTL-SDR with the prototype, consumption, +brownout, ACC, a flash update, Clone IDs and LEARN with the specific Opel. No +"validated" label. diff --git a/README.md b/README.md index 63af1c8..6a85740 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,89 @@ -# Symulator TPMS Schrader EG53MA4 — ESP32-S2-MINI + CC1101 +# Schrader EG53MA4 TPMS Simulator — ESP32-S2-MINI + CC1101 -**Wersja 2.0.0-rc.1 — release candidate bez walidacji sprzętowej.** +**Version 2.0.0-rc.1 — release candidate without hardware validation.** -Urządzenie warsztatowe nadaje cztery niezależne identyfikatory TPMS profilem -OOK/Manchester Schrader EG53MA4 na 433,92 MHz. Domyślnie każde koło raportuje -**260 kPa (2,6 bar; bajt protokołu `0x68`)**. Docelowy scenariusz to diagnostyka -Opla Astry J Sedan 1.4 LPG (2016, EU), ale **zgodność trzeba potwierdzić dla -konkretnego auta**: przez VIN/wykaz serwisowy, oznaczenia fabrycznych czujników, -odczyt diagnostyczny albo test odbioru. Numer OE 13506028, numery powiązane ani -ogłoszenie sprzedażowe same w sobie nie potwierdzają profilu radiowego. +A workshop device that transmits four independent TPMS identifiers with the +OOK/Manchester Schrader EG53MA4 profile on 433.92 MHz. By default each wheel +reports **260 kPa (2.6 bar; protocol byte `0x68`)**. The target scenario is +diagnostics of an Opel Astra J Sedan 1.4 LPG (2016, EU), but **compatibility +must be confirmed for the specific car**: via VIN/service listings, markings of +factory sensors, a diagnostic readout, or a reception test. OE number +13506028, related part numbers, or a listing offer alone do not confirm the +radio profile. -> **Nie jest to homologowany czujnik ani zamiennik sprawnego TPMS. Nie używać -> w jeździe drogowej.** Sztuczne ciśnienie może ukryć przebitą lub niedopompowaną -> oponę i opóźnić ostrzeżenie. Przed i po teście sprawdź wszystkie opony -> niezależnym manometrem. Zobacz [SAFETY](docs/SAFETY.md). +> **This is not a homologated sensor nor a replacement for a working TPMS. +> Do not use while driving.** Synthetic pressure can hide a punctured or +> underinflated tyre and delay the warning. Before and after the test, check +> all tyres with an independent gauge. See [SAFETY](docs/SAFETY.md). -## Co jest gotowe, a czego nie +## What is done, and what is not -- Gotowe: build ESP32, testy ramek/NVS/maszyny stanów, syntetyczny CU8 dekodowany - przez niezależny `rtl_433`, trwała konfiguracja z konsoli, Clone IDs i LEARN. -- **Niewykonane:** pomiar rzeczywistego CC1101, RTL-SDR z anteną, test z samochodem, - pomiar prądu i testy automotive. Dlatego wynik jest RC, nie „validated”. -- Jedyny profil podstawowy to **OOK**. Nie przełączaj na FSK „na próbę”. -- ESP32 nie generuje nośnej 433 MHz — wymagany jest osobny CC1101 433 MHz. +- Done: ESP32 build, frame/NVS/state-machine tests, synthetic CU8 decoded by + an independent `rtl_433`, persistent configuration from the console, Clone + IDs and LEARN. +- **Not done:** measurement of a real CC1101, RTL-SDR with an antenna, a test + with a car, current measurement, and automotive tests. That is why the + result is RC, not "validated". +- The only base profile is **OOK**. Do not switch to FSK "just to try it". +- The ESP32 does not generate the 433 MHz carrier — a separate CC1101 433 MHz + is required. -## Schemat ideowy +## Concept sketch ```text - Prototyp na biurku: - USB-C ──> [ESP32-S2-MINI] ── SPI ──> [CC1101 433 MHz] ──> antena SMA - │ │ │ - │ └── GPIO0: przycisk (BOOT) └── wspólna GND, tylko 3,3 V - └── GPIO15: wbudowana LED (aktywna HIGH) + Bench prototype: + USB-C ──> [ESP32-S2-MINI] ── SPI ──> [CC1101 433 MHz] ──> SMA antenna + │ │ │ + │ └── GPIO0: button (BOOT) └── common GND, 3.3 V only + └── GPIO15: built-in LED (active HIGH) - Zasilanie docelowe z gniazda zapalniczki samochodowej: - wariant A: gniazdo ──> [ładowarka samochodowa USB] ──> USB-C płytki - wariant B: gniazdo ──> bezpiecznik/TVS ──> [LM317T 3,3 V] ──> 3V3 + VCC CC1101 + Target supply from the car cigarette-lighter socket: + variant A: socket ──> [USB car charger] ──> board USB-C + variant B: socket ──> fuse/TVS ──> [LM317T 3.3 V] ──> 3V3 + CC1101 VCC - Konfiguracja: USB CDC 115200 → NVS → 4 × {ID, ciśnienie, temperatura} + Configuration: USB CDC 115200 → NVS → 4 × {ID, pressure, temperature} ``` -Wyjście LM317T ustaw dzielnikiem na **3,3 V i podłącz do 3V3, nie do 5V**. Nie -podłączaj 12 V do GPIO, 3V3 ani 5V. Przy zasilaniu zewnętrznym 3,3 V odłącz -USB, chyba że separacja źródeł została sprawdzona w dokumentacji konkretnego -egzemplarza płytki. Gniazdo zapalniczki w większości aut jest zasilane tylko -po przekręceniu stacyjki — **sprawdź to w swoim aucie**. Wtedy emulator nie -pobiera prądu na postoju; komputer samochodowy i tak nie odczytuje stanu TPMS -przy wyłączonym zapłonie, więc brak nadawania parkingowego nie ma znaczenia. -Pełny pinout, dzielnik LM317T i kondensatory: [HARDWARE](docs/HARDWARE.md). +Set the LM317T output with the divider to **3.3 V and connect it to 3V3, not +to 5V**. Do not connect 12 V to GPIO, 3V3, or 5V. When powering from an +external 3.3 V source, disconnect USB unless source separation has been +verified for the specific board revision. In most cars the cigarette-lighter +socket is powered only after the ignition is switched on — **check this in +your own car**. Then the emulator draws no current while parked; the car +computer does not read TPMS state with the ignition off anyway, so lacking +parking transmission does not matter. Full pinout, the LM317T divider, and +capacitors: [HARDWARE](docs/HARDWARE.md). ## Quick Start -### 1. Złóż prototyp +### 1. Assemble the prototype -Kup elementy z [BOM](docs/HARDWARE.md#bom-prototypu-laboratoryjnego). Podłącz -CC1101 i przycisk zgodnie z tabelą pinów; LED jest już na płytce S2 Mini. -Na biurku zasil układ przez sprawdzony kabel USB-C z danymi. Nie montuj jeszcze -niczego w samochodzie. +Buy the parts from the [BOM](docs/HARDWARE.md#laboratory-prototype-bom). +Connect the CC1101 and the button according to the pin table; the LED is +already on the S2 Mini board. On the bench, power the device through a tested +USB-C cable that carries data. Do not install anything in the car yet. -### 2. Zainstaluj narzędzia i sprawdź projekt +### 2. Install the tools and verify the project -Wymagane: Python 3, Git, CMake, kompilator C/C++, `pkg-config` oraz nagłówki -libusb i librtlsdr. -Najprościej użyć Dockera: +Required: Python 3, Git, CMake, a C/C++ compiler, `pkg-config`, and the +libusb and librtlsdr headers. The easiest way is Docker: ```bash docker build -t tpms-rc . docker run --rm -v "$PWD/artifacts:/work/artifacts" tpms-rc ``` -Bez Dockera skrypt utworzy `.venv` z PlatformIO, pobierze przypięty `rtl_433` -i referencyjne nagrania: +Without Docker, the script creates a `.venv` with PlatformIO, fetches the +pinned `rtl_433`, and the reference recordings: ```bash bash tools/check_all ``` -Ostatni komunikat musi brzmieć `PASS: wszystkie testy bez sprzetu...`. -To nie jest test fizycznego radia. +The last message must read `PASS: all hardware-free tests...`. +It is not a test of physical radio. -### 3. Skompiluj i wgraj +### 3. Build and flash ```bash .venv/bin/pio run -e esp32s2mini @@ -87,20 +91,22 @@ To nie jest test fizycznego radia. .venv/bin/pio device monitor --baud 115200 ``` -Jeżeli port nie jest wykrywany automatycznie, dodaj `--upload-port /dev/ttyACM0` -(przy `run`) albo `--port /dev/ttyACM0` (przy `device monitor`). Zależnie od -systemu i trybu USB może to być również `/dev/ttyUSB0`. W monitorze PlatformIO -wyjście to zwykle `Ctrl+]`. Jeśli upload nie startuje, przytrzymaj **BOOT**, -naciśnij i puść **RESET**, następnie puść BOOT. +If the port is not detected automatically, add `--upload-port /dev/ttyACM0` +(for `run`) or `--port /dev/ttyACM0` (for `device monitor`). Depending on the +system and USB mode it may also be `/dev/ttyUSB0`. In the PlatformIO monitor, +the exit shortcut is usually `Ctrl+]`. If the upload does not start, hold +**BOOT**, press and release **RESET**, then release BOOT. -Po uruchomieniu wpisz `stay 300` i Enter. Masz 5 minut na konfigurację; polecenie -`info` pokazuje aktywne wartości. Każda zmiana konfiguracji jest od razu zapisywana -w NVS i zachowuje się po restarcie — **nie edytuj ID w kodzie**. +After startup, type `stay 300` and press Enter. You have 5 minutes to +configure; the `info` command shows active values. Every configuration change +is saved to NVS immediately and survives a restart — **do not edit IDs in +code**. -### 4A. Preferowane: Clone IDs +### 4A. Preferred: Clone IDs -Jeśli znasz oryginalne 24-bit ID (np. z wcześniejszego odczytu `rtl_433`), wpisz -je w kolejności FL, FR, RR, RL. Przykład — zastąp wartości własnymi: +If you know the original 24-bit IDs (e.g. from an earlier `rtl_433` readout), +enter them in FL, FR, RR, RL order. Example — replace the values with your +own: ```text stay 300 @@ -113,60 +119,63 @@ info send ``` -ID musi mieć sześć cyfr hex, być niezerowe, różne od `FFFFFF` i unikalne. -Urządzenie wróci do NORMAL i będzie nadawało znane ID. **Nauka może być -niepotrzebna, ale nie jest to gwarantowane.** Potwierdź odbiór diagnostycznie; -nie zaczynaj od jazdy. +An ID must have six hex digits, be non-zero, differ from `FFFFFF`, and be +unique. The device returns to NORMAL and transmits the known IDs. **Learning +may be unnecessary, but that is not guaranteed.** Confirm reception +diagnostically; do not start with a road drive. -### 4B. Alternatywa: New IDs + LEARN +### 4B. Alternative: New IDs + LEARN -1. Wpisz `ids new`, następnie `info` i zapisz wygenerowane ID. -2. Uruchom właściwą dla swojej wersji auta procedurę nauki TPMS zgodnie z jej - instrukcją serwisową. Nie zgaduj sekwencji menu/pedałów. -3. Wpisz `mode learn`. Nadaje wyłącznie FL, co 2 s. LED wskaże 1 mrugnięcie. -4. `send` wymusza bieżące koło bez zmiany. Po potwierdzeniu kroku w aucie wpisz - `next`: FR → RR → RL. Krótki przycisk robi to samo; po RL wraca do NORMAL. -5. Jeśli minie 60 s na kole, LEARN przerwie się do NORMAL. Cała sesja ma limit - 15 min. Po zakończeniu sprawdź ID i kody diagnostyczne. +1. Type `ids new`, then `info`, and write down the generated IDs. +2. Start the TPMS learning procedure appropriate for your car model/version + according to its service instructions. Do not guess menu/pedal sequences. +3. Type `mode learn`. It transmits FL only, every 2 s. The LED shows 1 blink. +4. `send` forces the current wheel without changing it. After confirming the + step in the car, type `next`: FR → RR → RL. A short button press does the + same; after RL it returns to NORMAL. +5. If 60 s passes on a wheel, LEARN interrupts to NORMAL. The whole session + has a 15 min limit. When finished, verify the IDs and diagnostic codes. -EL-50448/OEC-T5 jest aktywatorem LF 125 kHz, **nie programatorem ESP32**. Ta -procedura nie wymaga go. Szczegóły: [SETUP](docs/SETUP.md). +EL-50448/OEC-T5 is a 125 kHz LF activator, **not an ESP32 programmer**. This +procedure does not require it. Details: [SETUP](docs/SETUP.md). -## Sterowanie — jedna tabela +## Controls — one table -LED działa tylko podczas czuwania; w deep sleep jest zgaszona. Po zmianie koła -seria 1–4 mrugnięć wskazuje FL/FR/RR/RL. +The LED works only while awake; in deep sleep it is off. After a wheel change, +a series of 1–4 blinks indicates FL/FR/RR/RL. -| Tryb | Wzorzec LED | Krótki przycisk | Długi ≥1,5 s | Bardzo długi ≥4 s | +| Mode | LED pattern | Short button | Long ≥1.5 s | Very long ≥4 s | |---|---|---|---|---| -| NORMAL | 1 mrugnięcie / 2 s | burst wszystkich 4 | wejście LEARN | wejście SINGLE | -| LEARN | 3 mrugnięcia / 0,5 s; po zmianie numer koła | następne koło + TX; po RL koniec | wyjście NORMAL | wejście SINGLE | -| SINGLE | 2 mrugnięcia / 0,5 s; po zmianie numer koła | następne koło + TX | wejście LEARN | wyjście NORMAL | +| NORMAL | 1 blink / 2 s | burst of all 4 | enter LEARN | enter SINGLE | +| LEARN | 3 blinks / 0.5 s; changes with wheel number | next wheel + TX; after RL done | exit to NORMAL | enter SINGLE | +| SINGLE | 2 blinks / 0.5 s; changes with wheel number | next wheel + TX | enter LEARN | exit to NORMAL | -W konsoli `send` w NORMAL nadaje wszystkie, a w LEARN/SINGLE tylko bieżące koło. -`send 1`…`send 4` wybiera koło jawnie; `send all` nadaje cztery. SINGLE wyłącza -się po 5 min. +In the console, `send` in NORMAL transmits all wheels, and in LEARN/SINGLE +only the current one. `send 1`…`send 4` select a wheel explicitly; `send all` +transmits four. SINGLE shuts off after 5 min. -## Najczęstsze problemy +## Most common problems -- **`BLAD: brak CC1101`**: sprawdź 3,3 V, wspólną masę oraz SCK/MISO/MOSI/CS - na GPIO4/5/6/7 i GDO0 na GPIO10; nie używaj 5 V na CC1101. -- **Konsola znika przed wpisaniem komend**: po restarcie od razu `stay 300`; - zwykłe wybudzenie RTC celowo nie otwiera okna konsoli. -- **NVS zgłasza błąd**: urządzenie używa bezpiecznych domyślnych; wpisz `info`. - `factory YES` kasuje własne ID i przywraca konfigurację fabryczną. -- **Auto nie odbiera**: najpierw zweryfikuj profil auta i odbiór RTL-SDR; nie - zmieniaj losowo modulacji, flag ani interwałów. Zobacz +- **`ERROR: no CC1101`**: check 3.3 V, common ground, and SCK/MISO/MOSI/CS + on GPIO4/5/6/7 and GDO0 on GPIO10; do not use 5 V on the CC1101. +- **Console disappears before you enter commands**: right after restart type + `stay 300`; a plain RTC wake deliberately does not open the console window. +- **NVS reports an error**: the device uses safe defaults; type `info`. + `factory YES` erases your IDs and restores the factory configuration. +- **The car does not receive**: first verify the car profile and RTL-SDR + reception; do not randomly change modulation, flags, or intervals. See [TROUBLESHOOTING](docs/TROUBLESHOOTING.md). -## Walidacja, zasilanie i release +## Validation, power, and release -- Protokół i niewiadome: [PROTOCOL](docs/PROTOCOL.md) -- Dokładne wyniki i checklista HIL: [VALIDATION](docs/VALIDATION.md) -- Pobór (na razie szacunki): [POWER](docs/POWER.md) -- LM317T i zasilanie z gniazda zapalniczki: [HARDWARE](docs/HARDWARE.md#wariant-z-gniazda-zapalniczki--wymagania-niezwalidowany-projekt) -- Zmiany: [CHANGELOG](CHANGELOG.md) +- Protocol and unknowns: [PROTOCOL](docs/PROTOCOL.md) +- Detailed results and the HIL checklist: [VALIDATION](docs/VALIDATION.md) +- Consumption (estimates so far): [POWER](docs/POWER.md) +- LM317T and power from the cigarette-lighter socket: + [HARDWARE](docs/HARDWARE.md#cigarette-lighter-socket-variant--requirements-unvalidated-design) +- Changes: [CHANGELOG](CHANGELOG.md) -Gotowe obrazy tworzy `bash tools/package_release.sh`. Pliki i adresy opisano w -[VALIDATION](docs/VALIDATION.md#artefakty-i-wgrywanie). Release candidate nie -zawiera wyniku testu CC1101 ani samochodu. +Release images are produced by `bash tools/package_release.sh`. The files and +addresses are described in +[VALIDATION](docs/VALIDATION.md#artifacts-and-flashing). The release candidate +does not include a CC1101 test result or a car test. diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 3ca60d2..9041737 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,59 +1,66 @@ # TPMS EG53MA4 Simulator 2.0.0-rc.1 -**Release candidate — 2026-10-27. Nie jest to release „validated”.** +**Release candidate — 2026-10-27. This is not a "validated" release.** -Diagnostyczny symulator czterech czujników Schrader EG53MA4 dla ESP32-S2-MINI -(ESP32-S2FN4R2) + CC1101 433 MHz z anteną SMA. Profil docelowy obejmuje testy z Oplem Astra J Sedan 2016, -ale zgodność konkretnego auta trzeba potwierdzić. Sztuczne dane mogą ukryć usterkę -opony; nie używać w jeździe drogowej. +A diagnostic simulator of four Schrader EG53MA4 sensors for the ESP32-S2-MINI +(ESP32-S2FN4R2) + CC1101 433 MHz with an SMA antenna. The target profile +includes tests with an Opel Astra J Sedan 2016, but compatibility of the +specific car must be confirmed. Synthetic data can hide a tyre fault; do not +use while driving. -## Funkcje +## Features -- cztery trwałe, niezależne 24-bit ID; domyślnie 260 kPa dla każdego koła; -- OOK/Manchester 433,92 MHz, niska konfigurowalna moc od −10 dBm; -- Clone IDs oraz New IDs + LEARN FL→FR→RR→RL, SINGLE/diagnostics; -- konfiguracja NVS przez UART bez rekompilacji, wersja/CRC/walidacja/factory reset; -- przycisk, LED, timeouty, deep sleep z RTC i opcjonalne sprzętowe ACC; -- automatyczne testy native/RF/build, Docker i artefakty SHA-256. +- four persistent, independent 24-bit IDs; 260 kPa by default for every wheel; +- OOK/Manchester 433.92 MHz, low configurable power from −10 dBm; +- Clone IDs and New IDs + LEARN FL→FR→RR→RL, SINGLE/diagnostics; +- NVS configuration over UART without recompilation, version/CRC/ + validation/factory reset; +- button, LED, timeouts, deep sleep with RTC and optional hardware ACC; +- automated native/RF/build tests, Docker, and SHA-256 artifacts. -## Wymagany sprzęt +## Required hardware -ESP32-S2-MINI (ESP32-S2FN4R2), CC1101 **433 MHz** 3,3 V ze złączem SMA -(np. ARD-CC1101-ANT), antena, przycisk i odsprzężenie. LED jest wbudowana. -Zasilanie docelowe z gniazda zapalniczki: ładowarka samochodowa USB albo -LM317T z dzielnikiem 240/390 Ω i właściwymi kondensatorami; wariant 12 V -wymaga ochrony wejścia i testów. Pełny BOM/pinout: HARDWARE. S2 Mini ani -LM317T nie są samodzielnym, zwalidowanym rozwiązaniem automotive. +ESP32-S2-MINI (ESP32-S2FN4R2), a CC1101 **433 MHz** 3.3 V module with an SMA +connector (e.g. ARD-CC1101-ANT), an antenna, a button, and decoupling. The LED +is built in. Target power from the cigarette-lighter socket: a car USB charger +or an LM317T with a 240/390 Ω divider and proper capacitors; the 12 V variant +requires input protection and tests. Full BOM/pinout: HARDWARE. Neither the +S2 Mini nor the LM317T is a validated automotive solution on its own. -## Instalacja i aktualizacja +## Installation and update -Nowa instalacja: `bash tools/check_all`, potem +New installation: `bash tools/check_all`, then `pio run -e esp32s2mini -t upload`. -Gotowe obrazy: `bash tools/package_release.sh`; adresy i flash opisano w VALIDATION. -Przed pełnym flashem zapisz ID — partycja NVS może zostać skasowana. Konfigurację -sprawdź po restarcie przez `info`. Migracji z wersji 1.0 bez NVS nie ma; należy -wpisać ID w konsoli jeden raz. +Release images: `bash tools/package_release.sh`; addresses and flashing are +described in VALIDATION. Before a full flash, write down your IDs — the NVS +partition may be erased. Verify the configuration after a restart with `info`. +There is no migration from version 1.0 without NVS; enter the IDs in the +console once. -## Wyniki testów bez sprzętu (2026-10-28) +## Test results without hardware (2026-10-28) -- native: 24/24 PASS (po audycie integracji sprzęt–firmware); -- pełny ESP32 build z `-Werror`: PASS; -- cppcheck: PASS, 0 defektów; -- rtl_433: 64/64 rekordy referencyjne, 3/3 syntetyczne, 3/3 negatywne: PASS. +- native: 24/24 PASS (after the hardware–firmware integration audit); +- full ESP32 build with `-Werror`: PASS; +- cppcheck: PASS, 0 defects; +- rtl_433: 64/64 reference records, 3/3 synthetic, 3/3 negative: PASS. -Dokładne komendy i przypięte commity: VALIDATION/PROTOCOL. +Exact commands and pinned commits: VALIDATION/PROTOCOL. -## Znane ograniczenia +## Known limitations -- Nie zmierzono rzeczywistej emisji CC1101, ogona, mocy ani częstotliwości. -- Nie wykonano RTL-SDR z anteną, pomiaru poboru, brownout ani testu ACC. -- Nie wykonano Clone IDs/LEARN z samochodem; nie potwierdzono OE 13506028 dla - konkretnego VIN. -- Znaczenie wszystkich flags pozostaje nieznane; brak zgadywanego low battery. -- Harmonogram jest eksperymentalny, nie potwierdzony OE. -- LM317T i zasilanie z gniazda zapalniczki nie są zwalidowanym projektem - automotive; przy zasilaniu wyłącznie z gniazda „po stacyjce” nie ma - transmisji po wyłączeniu zapłonu — ECU auta wtedy i tak nie nasłuchuje. -- Gitea Actions wymaga działającego runnera; lokalne wyniki nie oznaczają CI PASS. +- The real CC1101 emission, tail, power, and frequency were not measured. +- RTL-SDR with an antenna, consumption measurement, brownout, and the ACC + test were not performed. +- Clone IDs/LEARN with a car were not performed; OE 13506028 was not confirmed + for a specific VIN. +- The meaning of all flags remains unknown; there is no guessed low-battery + bit. +- The schedule is experimental, not confirmed as OE. +- The LM317T and power from the cigarette-lighter socket are not a validated + automotive design; with power only from an ignition-switched socket there + is no transmission after the ignition goes off — the car ECU does not + listen then anyway. +- Gitea Actions requires a working runner; local results do not mean CI PASS. -Do czasu odhaczenia HIL w VALIDATION wynik pozostaje release candidate. +Until the HIL items in VALIDATION are checked off, the result remains a +release candidate. diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md index 17f3ab4..6901937 100644 --- a/THIRD_PARTY_NOTICES.md +++ b/THIRD_PARTY_NOTICES.md @@ -1,23 +1,25 @@ -# Licencje i źródła +# Licenses and sources -Projekt jest rozpowszechniany na GPL-2.0-or-later (`LICENSE`). Wybór jest -zgodny z wykorzystaniem w historii modelu algorytmu slicera z rtl_433. Nie -przypisujemy sobie praw do kodu autorów zewnętrznych. +The project is distributed under GPL-2.0-or-later (`LICENSE`). The choice is +consistent with prior use of the slicer algorithm from rtl_433 in the model's +history. We do not claim rights to external authors' code. -- **rtl_433** — GPL-2.0-or-later; dekoder `schraeder.c`, Copyright Benjamin - Larsson, Christian W. Zuckschwerdt i kolejni autorzy. Używany jako niezależny - program do testów. Źródło i pełna historia: . - Referencja testów: commit `406f9a33550a2b6b3d0d8a8a486417ce5b3f13ab`. -- **rtl_433_tests** — nagrania i metadane należą do ich autorów; nie są kopiowane - do artefaktu firmware ani release. Skrypt pobiera przypięty commit - `1aa8c29d6b9383739d1aeed495dbc5069b704392`. -- **SmartRC-CC1101-Driver-Lib** — zewnętrzna biblioteka pobierana przez PlatformIO; - zachowane są jej oryginalne nagłówki i licencja. Użyty commit +- **rtl_433** — GPL-2.0-or-later; the `schraeder.c` decoder, Copyright + Benjamin Larsson, Christian W. Zuckschwerdt and subsequent authors. Used as + an independent decoding program for testing. Source and full history: + . Test reference: commit + `406f9a33550a2b6b3d0d8a8a486417ce5b3f13ab`. +- **rtl_433_tests** — the recordings and metadata belong to their authors; + they are not copied into the firmware artifact or the release. The script + fetches the pinned commit `1aa8c29d6b9383739d1aeed495dbc5069b704392`. +- **SmartRC-CC1101-Driver-Lib** — an external library fetched by PlatformIO; + its original headers and license are preserved. Commit used: `de6757ef633b3e626dae5c7835cdb66ab53f9a1d`. -- **Arduino ESP32 / ESP-IDF / PlatformIO / Unity** — zależności build/test na ich - własnych licencjach; nie są objęte deklaracją autorstwa tego projektu. -- Issue rtl_433 #2978 służył wyłącznie jako wzorzec integracji CC1101. Kod - protokołu Renault nie jest kodem EG53MA4 i nie został użyty jako protokół. +- **Arduino ESP32 / ESP-IDF / PlatformIO / Unity** — build/test dependencies + under their own licenses; they are not covered by the attribution of this + project. +- rtl_433 issue #2978 served only as a CC1101 integration pattern. The + Renault protocol code is not EG53MA4 code and was not used as the protocol. -Pełne teksty licencji zależności znajdują się w ich źródłach pobieranych podczas -buildu. Ten plik nie zawęża ich praw ani licencji. +The full license texts of the dependencies are in their sources, fetched +during the build. This file does not narrow their rights or licenses. diff --git a/docs/AUDIT.md b/docs/AUDIT.md index 748ffdd..cfe3f65 100644 --- a/docs/AUDIT.md +++ b/docs/AUDIT.md @@ -1,33 +1,34 @@ -# Rejestr audytu release-v2 +# Release-v2 audit register -| Priorytet | Problem początkowy | Kryterium naprawy | Stan / dowód | +| Priority | Original problem | Repair criteria | Status / evidence | |---|---|---|---| -| P0 | Zgadywany bit low battery zależny od zasilania emulatora | brak maski i sprzężenia; test flags | naprawione; grep kodu i 20/20 native | -| P0 | MCP1703 + TVS 24 V opisane jako ochrona automotive | usunąć rekomendację; wymagania i przykład z datasheet | naprawione w HARDWARE | -| P0 | Brak fizycznego dowodu zgodności z autem przedstawiany zbyt pewnie | RC, jawne HIL, weryfikacja VIN/oznaczeń | naprawiona dokumentacja; HIL nadal otwarte | -| P1 | ID/ciśnienia/RF tylko przez rekompilację | NVS z konsolą, walidacja, wersja/CRC | naprawione; test_settings i build | -| P1 | Monolit uniemożliwiał test timeoutów/ACC | przenośny state-machine, fake clock/radio | naprawione; test_app_state | -| P1 | FSK w podstawowym flow bez dowodu | tylko OOK w firmware/generatorze | naprawione | -| P1 | PARKING_SHUTDOWN bez gwarantowanego ACC wake | usunąć albo zapewnić budzenie | usunięty; każdy sen ma RTC | -| P1 | TX kończone czasem i TXBYTES, ryzyko ogona | MARCSTATE/underflow/limit | poprawione; wymaga potwierdzenia HIL | -| P1 | Wektory głównie własne | cztery prawdziwe nagrania + niezależny rtl_433 | 64/64 PASS | -| P2 | Domyślne LF bez zwalidowanego front-endu | wyłączyć domyślnie, LEARN bez LF | naprawione | -| P2 | Interwały przedstawiane jak OE | jawnie eksperymentalne | PROTOCOL/SETUP/POWER | -| P2 | Brak pełnego jednego check/build artefaktów | check_all, CI, Docker, package_release | dodane; wyniki VALIDATION | -| P2 | Okno konsoli po każdym RTC zwiększa pobór | sen od razu po cyklu RTC | poprawione; pomiar HIL otwarty | -| P2 | README niezgodne z zachowaniem | nowy Quick Start, jedna tabela UI | przepisane | -| P1 | Pull-up cyfrowy przycisku/LF nie działa w deep sleep (EXT1, RTC_PERIPH off) | pociągnięcia RTC + HOLD przed snem | naprawione w power.cpp; HIL budzenia otwarte | -| P1 | `nan` przechodził walidację konsoli (cisnienie/RF) i trafiał do NVS | odrzucanie NaN/inf + testy native | naprawione; `parse` + test_parse | -| P2 | Dzielnik ADC nasycany powyżej ~11,8 V — brak odczytu 12–14,4 V | zakres do ~16 V | naprawione config.h (R2 180 kΩ); wymaga pomiaru | -| P2 | Pełny obraz release z `40m` vs nagłówek builda `80m` | zgodność parametrów flash | naprawione package_release.sh; weryfikacja headera | -| P2 | Model Pythona bez saturacji temperatury (roznica z C++) | clamp 0–255 + self-test | naprawione tpms_frame.py | -| P3 | Ujemny test checksum ćwiczył Manchester zamiast sumy | odwrócenie całej komórki | naprawione test_tpms_frame | -| P3 | Błędne offsety bitów w diagramie PROTOCOL.md | poprawne 72/96/104/112/120 | naprawione | -| P1 | Skala pola ciśnienia `P` (2,5 kPa/bit) niezweryfikowana — wszystkie nagrania mają `P=0`, auto pokazuje 284 kPa dla 260 kPa | kalibracja z wyświetlaczem auta, poprawa przelicznika i testów | naprawione; korekta skalująca 2,73 kPa/bit (`P=95` dla 260 kPa), HIL: 260 kPa → 260 kPa na wyświetlaczu; drugi punkt pomiarowy (np. 300 kPa) potwierdziłby liniowość w zakresie | +| P0 | Guessed low-battery bit dependent on the emulator supply | no mask and no coupling; flags test | fixed; code grep and 20/20 native | +| P0 | MCP1703 + 24 V TVS described as automotive protection | remove the recommendation; requirements and a datasheet example | fixed in HARDWARE | +| P0 | Lack of physical compatibility evidence with the car presented too confidently | RC, explicit HIL, VIN/marking verification | documentation fixed; HIL still open | +| P1 | IDs/pressures/RF only via recompilation | NVS with a console, validation, version/CRC | fixed; test_settings and build | +| P1 | Monolith prevented testing timeouts/ACC | portable state machine, fake clock/radio | fixed; test_app_state | +| P1 | FSK in the base flow without evidence | OOK only in firmware/generator | fixed | +| P1 | PARKING_SHUTDOWN without a guaranteed ACC wake | remove it or guarantee waking | removed; every sleep has RTC | +| P1 | TX ended on time and TXBYTES, tail risk | MARCSTATE/underflow/limit | improved; requires HIL confirmation | +| P1 | Vectors mostly self-authored | four real recordings + independent rtl_433 | 64/64 PASS | +| P2 | Default LF without a validated front end | disabled by default, LEARN without LF | fixed | +| P2 | Intervals presented as OE | explicitly experimental | PROTOCOL/SETUP/POWER | +| P2 | No full single check/build artifacts | check_all, CI, Docker, package_release | added; results in VALIDATION | +| P2 | A console window after every RTC wake raises consumption | sleep right after the RTC cycle | improved; HIL measurement open | +| P2 | README inconsistent with behaviour | new Quick Start, one UI table | rewritten | +| P1 | Digital pull-up of button/LF does not work in deep sleep (EXT1, RTC_PERIPH off) | RTC pulls + HOLD before sleep | fixed in power.cpp; HIL wake still open | +| P1 | `nan` passed console validation (pressure/RF) and reached NVS | rejecting NaN/inf + native tests | fixed; `parse` + test_parse | +| P2 | ADC divider saturating above ~11.8 V — no 12–14.4 V reading | range up to ~16 V | fixed in config.h (R2 180 kΩ); requires measurement | +| P2 | Full release image with `40m` vs build header `80m` | flash parameter consistency | fixed in package_release.sh; header verification | +| P2 | Python model without temperature saturation (discrepancy with C++) | clamp 0–255 + self-test | fixed in tpms_frame.py | +| P3 | Negative checksum test exercised Manchester instead of the sum | invert the whole cell | fixed in test_tpms_frame | +| P3 | Wrong bit offsets in the PROTOCOL.md diagram | correct 72/96/104/112/120 | fixed | +| P1 | Scale of the pressure field `P` (2.5 kPa/bit) unverified — all captures have `P=0`, the car shows 284 kPa for 260 kPa | calibrate against the car display, fix the conversion and tests | fixed; scaling correction 2.73 kPa/bit (`P=95` for 260 kPa), HIL: 260 kPa → 260 kPa on the display; a second measurement point (e.g. 300 kPa) would confirm linearity in range | -## Otwarte, wymagające sprzętu +## Open, requiring hardware -Nie można ich zamknąć deklaracją: pomiar CC1101/ogon/moc/częstotliwość, test -RTL-SDR z anteną, pobór i brownout, zabezpieczone ACC, test Clone IDs/LEARN z -konkretną Astrą oraz projekt i test zasilania automotive. Są checklistą w -`VALIDATION.md` i blokują status „validated”. +These cannot be closed by declaration: CC1101/tail/power/frequency +measurement, an RTL-SDR test with an antenna, consumption and brownout, +protected ACC, a Clone IDs/LEARN test with the specific Astra, and the design +and testing of automotive power. They are the checklist in `VALIDATION.md` +and they block the "validated" status. diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md index 412faa1..8a9ce45 100644 --- a/docs/HARDWARE.md +++ b/docs/HARDWARE.md @@ -1,173 +1,184 @@ -# Sprzęt i montaż +# Hardware and assembly -## Zakres +## Scope -Podstawowy release opisuje **prototyp laboratoryjny na ESP32-S2-MINI** -(ESP32-S2FN4R2). Przewody prototypowe i LM317T nie są gotowym zestawem do -trwałego montażu w samochodzie. Wariant z gniazdem zapalniczki poniżej jest -listą połączeń i wymagań projektowych, nie zwalidowanym schematem automotive. +The base release describes a **laboratory prototype on the ESP32-S2-MINI** +(ESP32-S2FN4R2). Prototype wires and the LM317T are not a ready kit for +permanent installation in a car. The cigarette-lighter socket variant below +is a list of connections and design requirements, not a validated automotive +schematic. -## BOM prototypu laboratoryjnego +## Laboratory prototype BOM -| Element | Wymaganie | Uwagi | +| Item | Requirement | Notes | |---|---|---| -| ESP32-S2-MINI | ESP32-S2FN4R2 (4 MB flash, 2 MB PSRAM), natywne USB do flash/konsoli; płytka typu Lolin/Wemos S2 Mini, np. ARD-ESP32-S2-MINI | sprzedawana z MicroPythonem — wgrywamy własny firmware; klon trzeba sprawdzić przed zasileniem | -| CC1101 | moduł **433 MHz**, SPI, 3,3 V, ze złączem SMA i anteną, np. ARD-CC1101-ANT | nie kupuj wersji 868/915 MHz | -| Antena 433 MHz | dołączona do modułu SMA; na biurko monopol λ/4 ≈ 17 cm | uziemienie/przeciwwaga zgodnie z konstrukcją modułu | -| Przycisk NO (opcjonalny) | monostabilny | GPIO3 do GND; bez dodatkowego przycisku służy przycisk BOOT płytki (GPIO0) | -| LED | wbudowana na GPIO15 | aktywna stanem wysokim; zewnętrzna LED nie jest potrzebna | -| Ładowarka samochodowa USB | gniazdo zapalniczki → USB 5 V | wariant A zasilania; sprawdzona, z kablem USB-C z danymi | -| LM317T | TO-220 (metal), regulowany 1,25–37 V, 1,5 A | tylko dla wariantu B; nie jest potrzebny przy zasilaniu z USB | -| Rezystory LM317T | R1 = 240 Ω (VOUT–ADJ), R2 = 390 Ω (ADJ–GND) | dają ok. 3,28 V; 1% metalizowane, blisko układu | -| Kondensatory LM317T | 100 nF na wejściu i min. 1 µF na wyjściu | praktycznie 10 µF; blisko układu | -| Radiator | dla LM317T przy zasilaniu z 12–14,4 V | patrz obliczenia termiczne niżej | -| Odsprzężenie modułów | 100 nF przy każdym module + 47–100 µF przy CC1101 | możliwie blisko pinów zasilania | -| Przewody | krótkie, wspólna masa | SPI najlepiej <10 cm | -| Zasilanie laboratoryjne | USB 5 V albo LM317T z bezpiecznego VIN | nie podawaj jednocześnie rywalizujących źródeł 3,3 V | +| ESP32-S2-MINI | ESP32-S2FN4R2 (4 MB flash, 2 MB PSRAM), native USB for flash/console; a Lolin/Wemos S2 Mini type board, e.g. ARD-ESP32-S2-MINI | sold with MicroPython — we flash our own firmware; verify a clone before powering it | +| CC1101 | **433 MHz** module, SPI, 3.3 V, with an SMA connector and antenna, e.g. ARD-CC1101-ANT | do not buy the 868/915 MHz version | +| 433 MHz antenna | supplied with the SMA module; for a bench, a λ/4 monopole ≈ 17 cm | ground plane/counterweight per the module's design | +| NO button (optional) | momentary | GPIO3 to GND; without an extra button the board's BOOT button (GPIO0) is used | +| LED | built-in on GPIO15 | active high; an external LED is not needed | +| Car USB charger | cigarette-lighter socket → USB 5 V | power variant A; tested, with a USB-C cable that carries data | +| LM317T | TO-220 (metal), adjustable 1.25–37 V, 1.5 A | only for variant B; not needed when powering from USB | +| LM317T resistors | R1 = 240 Ω (VOUT–ADJ), R2 = 390 Ω (ADJ–GND) | give about 3.28 V; 1% metal-film, close to the device | +| LM317T capacitors | 100 nF on the input and at least 1 µF on the output | practically 10 µF; close to the device | +| Heatsink | for the LM317T when fed from 12–14.4 V | see the thermal calculations below | +| Module decoupling | 100 nF at each module + 47–100 µF at the CC1101 | as close to the supply pins as possible | +| Wires | short, common ground | SPI best under 10 cm | +| Laboratory supply | USB 5 V or the LM317T from a safe VIN | do not feed competing 3.3 V sources at the same time | -Do diagnozy RF przydaje się RTL-SDR, ale nie jest częścią emulatora. Standardowy -S2 Mini ma niebieską LED na GPIO15 i przycisk BOOT na GPIO0; przed montażem -sprawdź konkretny klon, bo nazwy handlowe bywają używane dla różnych płytek. +RTL-SDR is useful for RF diagnosis but is not part of the emulator. The +standard S2 Mini has a blue LED on GPIO15 and a BOOT button on GPIO0; before +assembly verify the specific clone, because trade names are sometimes used +for different boards. -## Pinout i połączenia +## Pinout and connections -| ESP32-S2-MINI | CC1101 / element | Zasada | +| ESP32-S2-MINI | CC1101 / item | Rule | |---|---|---| -| 3V3 | CC1101 VCC; wyjście LM317T przy zasilaniu zewnętrznym | **tylko 3,3 V**, nigdy wyjście 5 V ani LM317T ustawionego wyżej | -| GND | CC1101 GND, przycisk, dzielnik LM317T | wspólna masa | +| 3V3 | CC1101 VCC; LM317T output when externally powered | **3.3 V only**, never the 5 V pin nor an LM317T set higher | +| GND | CC1101 GND, button, LM317T divider | common ground | | GPIO4 | SCK/SCLK | SPI | | GPIO5 | MISO/SO | SPI | | GPIO6 | MOSI/SI | SPI | | GPIO7 | CS/CSn/SS | SPI | -| GPIO10 | GDO0 | diagnostyka biblioteki; GDO2 niepodłączony | -| GPIO3 | alternatywny przycisk NO do GND (`-DPIN_BUTTON=3`) | pull-up RTC włączany przez firmware przed deep sleep (pull-up cyfrowy nie działa w deep sleep); RTC GPIO wakeup, zalecany zewnętrzny 10 kΩ | -| GPIO15 | wbudowana LED | aktywna HIGH, firmware steruje właściwą polaryzacją | -| GPIO1 | opcjonalny ADC zasilania przez dzielnik | `PIN_VBAT_ADC`, ADC1_CH0; dzielnik 1 MΩ/180 kΩ (`config.h`), zakres do ok. 16 V; nigdy 12 V wprost | -| GPIO2 | opcjonalne ACC po zmianie `PIN_ACC` i zabezpieczeniu | nigdy 12 V wprost | -| GPIO14 | opcjonalny detektor LF po zmianie `PIN_LF_TRIGGER` | aktywny LOW; RTC GPIO wakeup, domyślnie wyłączone | -| GPIO0 | przycisk BOOT płytki = przycisk sterujący i budzenie RTC (domyślne `PIN_BUTTON`) | pin strapping: trzymany przy zasilaniu/reset uruchamia bootloader zamiast firmware (potwierdzone działanie budzenia na sprzęcie); nie używać do CC1101 | +| GPIO10 | GDO0 | library diagnostics; GDO2 unconnected | +| GPIO3 | alternative NO button to GND (`-DPIN_BUTTON=3`) | RTC pull-up enabled by the firmware before deep sleep (a digital pull-up does not work in deep sleep); RTC GPIO wakeup, an external 10 kΩ recommended | +| GPIO15 | built-in LED | active HIGH; the firmware drives the correct polarity | +| GPIO1 | optional supply ADC through a divider | `PIN_VBAT_ADC`, ADC1_CH0; 1 MΩ/180 kΩ divider (`config.h`), range up to about 16 V; never 12 V directly | +| GPIO2 | optional ACC after changing `PIN_ACC` and protecting it | never 12 V directly | +| GPIO14 | optional LF detector after changing `PIN_LF_TRIGGER` | active LOW; RTC GPIO wakeup, disabled by default | +| GPIO0 | the board's BOOT button = the control button and RTC wake (default `PIN_BUTTON`) | strapping pin: held at power-up/reset it starts the bootloader instead of the firmware (wake behaviour confirmed on hardware); do not use for the CC1101 | -GPIO0, GPIO45 i GPIO46 są pinami strapping. Nie dokładaj do nich zewnętrznych -rezystorów ani układów wymuszających stan podczas resetu. GPIO19/20 obsługują -natywne USB, a GPIO26–32 w ESP32-S2FN4R2 obsługują flash i PSRAM w obudowie — -nie używaj ich. GPIO33–40 pozostają wolne; konsola korzysta z natywnego USB, -więc zewnętrzny mostek USB-UART nie jest potrzebny. +GPIO0, GPIO45 and GPIO46 are strapping pins. Do not add external resistors or +state-forcing circuits to them during reset. GPIO19/20 carry native USB, and +GPIO26–32 in the ESP32-S2FN4R2 serve the in-package flash and PSRAM — do not +use them. GPIO33–40 remain free; the console uses native USB, so an external +USB-UART bridge is not needed. -Przy laboratoryjnym zasilaniu 3,3 V przez LM317T: zacznij od VIN = 5–9 V, ustaw -limit np. 0,5 A, sprawdź polaryzację i napięcie wyjściowe bez podłączonego -S2 Mini. Połącz GND, a na czas zasilania zewnętrznego odłącz USB. Prąd -szczytowy zależy od płytki i ustawionego PA. +With a laboratory 3.3 V supply from the LM317T: start with VIN = 5–9 V, set a +limit of e.g. 0.5 A, check the polarity and output voltage without the S2 +Mini connected. Join the grounds, and disconnect USB while externally powered. +Peak current depends on the board and the configured PA. -## LM317T — wyprowadzenia, dzielnik i kondensatory +## LM317T — pinout, divider, and capacitors -Dla **LM317T w TO-220**, patrząc na oznaczenia od przodu z nóżkami w dół: +For the **LM317T in TO-220**, looking at the markings from the front with the +legs pointing down: -| Nóżka | Funkcja | Połączenie | +| Leg | Function | Connection | |---:|---|---| -| 1 | ADJ | dzielnik: R1 do VOUT, R2 do GND | -| 2 | VOUT | 3V3 S2 Mini + VCC CC1101 | -| 3 | VIN | zabezpieczone napięcie wejściowe | +| 1 | ADJ | divider: R1 to VOUT, R2 to GND | +| 2 | VOUT | 3V3 of the S2 Mini + CC1101 VCC | +| 3 | VIN | protected input voltage | -Metalowy TAB jest połączony z **VOUT** — nie z GND jak w LF33CV czy 7805. -Radiator i obudowa TAB nie mogą dotykać masy ani innych potencjałów. -**Nie stosuj schematu nóżek 7805** — tutaj kolejność to ADJ–VOUT–IN. +The metal TAB is connected to **VOUT** — not to GND as in the LF33CV or +7805. The heatsink and TAB enclosure must not touch ground or any other +potential. **Do not use the 7805 leg scheme** — the order here is +ADJ–VOUT–IN. -Napięcie wyjściowe ustawia dzielnik: `VOUT = 1,25 V × (1 + R2/R1)`. R1 = 240 Ω -między VOUT a ADJ oraz R2 = 390 Ω między ADJ a GND dają ok. **3,28 V** i -jednocześnie obciążenie ok. 5 mA, zbliżone do minimalnego prądu obciążenia -LM317 — przy większych wartościach rezystorów zmierz VOUT bez obciążenia. -Między VIN a GND daj 100 nF. Między VOUT a GND daj min. 1 µF; praktyczny -punkt startowy to 10 µF. LM317 nie wymaga szczególnego ESR jak LDO, ale -kondensatory mają być blisko układu. Dodatkowe 100 nF przy modułach -i 47–100 µF przy CC1101 pozostają potrzebne. +The output voltage is set by the divider: `VOUT = 1.25 V × (1 + R2/R1)`. +R1 = 240 Ω between VOUT and ADJ, and R2 = 390 Ω between ADJ and GND give +about **3.28 V**, while drawing about 5 mA, close to the LM317's minimum load +current — with larger resistor values measure VOUT unloaded. Place 100 nF +between VIN and GND. Place at least 1 µF between VOUT and GND; a practical +starting point is 10 µF. The LM317 does not require special ESR like an LDO, +but the capacitors should sit close to the device. An extra 100 nF at the +modules and 47–100 µF at the CC1101 remain necessary. -Nie podłączaj VOUT LM317T do pinu **5V** S2 Mini. Pin 5V zasila wbudowany -regulator płytki, natomiast zewnętrzne, stabilizowane 3,3 V należy doprowadzić -do **3V3**. Nie zasilaj jednocześnie z USB i LM317T bez sprawdzonej separacji -źródeł, ponieważ konstrukcje klonów różnią się połączeniami zasilania. +Do not connect the LM317T VOUT to the S2 Mini's **5V** pin. The 5V pin feeds +the board's built-in regulator, whereas external, regulated 3.3 V must be +brought to **3V3**. Do not power from USB and the LM317T at the same time +without verified source separation, because clone designs differ in their +power connections. -## Antena i test położenia +## Antenna and position test -Nie zgadujemy położenia odbiornika TPMS w Astrze J. Test zasięgu wykonaj na -postoju, z niską mocą, porównując odczyt RTL-SDR/diagnostykę dla kilku pozycji: -konsola środkowa, okolica za schowkiem, ewentualnie bagażnik. Wynik dla jednego -egzemplarza nie jest dowodem lokalizacji odbiornika. +We do not guess the TPMS receiver location in the Astra J. Perform the range +test while parked, at low power, comparing RTL-SDR readings/diagnostics for a +few positions: centre console, near the glovebox, possibly the boot. A result +for a single unit is not proof of the receiver location. -Urządzenie mocuj mechanicznie, z dala od poduszek powietrznych i ich wiązek, -strefy pedałów, ruchomych części, wilgoci, źródeł ciepła i metalowych ekranów. -Nie owijaj anteny wiązką, nie prowadź jej przy żarówce/rozdzielaczu LPG ani przy -przewodach zapłonowych. Obudowa prototypu powinna być nieprzewodząca; otwór na -złącze SMA i konieczność ekranowania trzeba ocenić pomiarowo. +Mount the device mechanically, away from airbags and their harnesses, the +pedal area, moving parts, moisture, heat sources, and metal shielding. Do not +wrap the antenna in a harness, do not route it near an LPG bulb/regulator or +ignition wiring. The prototype enclosure should be non-conductive; the hole +for the SMA connector and any need for shielding must be assessed by +measurement. -## Wariant „z gniazda zapalniczki” — wymagania, niezwalidowany projekt +## Cigarette lighter socket variant — requirements, unvalidated design -Docelowe zasilanie pochodzi z gniazda zapalniczki samochodowej, na dwa sposoby: +The target power comes from the car cigarette-lighter socket, in two ways: ```text -Wariant A (prostszy): -gniazdo zapalniczki → ładowarka samochodowa USB (5 V) → kabel USB-C → USB S2 Mini +Variant A (simpler): +cigarette-lighter socket → car USB charger (5 V) → USB-C cable → S2 Mini USB -Wariant B (stabilizator): -gniazdo zapalniczki 12 V → bezpiecznik przy źródle → ochrona przed odwrotną -polaryzacją → ograniczenie energii + właściwie dobrany TVS -→ VIN LM317T → VOUT 3,3 V → 3V3 S2 Mini + VCC CC1101 +Variant B (regulator): +cigarette-lighter socket 12 V → fuse at the source → reverse-polarity +protection → energy limitation + properly rated TVS +→ LM317T VIN → VOUT 3.3 V → S2 Mini 3V3 + CC1101 VCC ``` -W większości aut gniazdo zapalniczki jest zasilane tylko po przekręceniu -stacyjki — **zweryfikuj to w swoim pojeździe**, bo część aut ma gniazdo -zasilane na stałe. Przy gnieździe „po stacyjce” emulator nie pobiera prądu, -gdy samochód jest wyłączony. Komputer samochodowy i tak zwykle nie odczytuje -wtedy stanu TPMS, więc brak transmisji parkingowej nie ma znaczenia. +In most cars the cigarette-lighter socket is powered only after the ignition +is switched on — **verify this in your vehicle**, because some cars have a +socket powered permanently. With an ignition-switched socket the emulator +draws no current while the car is off. The car computer usually does not read +TPMS state then anyway, so the lack of parking transmission does not matter. -Samo wyjście gniazda nadal ma przepięcia i zakłócenia instalacji pojazdu. -**Nie podłączaj go wprost do VIN LM317T jako gotowej instalacji samochodowej.** -LM317T znosi różnicę VIN−VOUT do 37–40 V, więc jest odporniejszy na przepięcia -niż LF33CV (16 V), ale ochrona nadal musi ograniczać napięcie z marginesem. -TVS o progu powyżej dopuszczalnego VIN nie stanowi ochrony LM317T. +The socket output itself still has transients and noise of the vehicle +installation. **Do not connect it directly to the LM317T VIN as a finished +car installation.** The LM317T tolerates a VIN−VOUT difference up to 37–40 V, +so it is more tolerant of transients than the LF33CV (16 V), but protection +still has to limit the voltage with margin. A TVS with a threshold above the +maximum VIN provides no protection for the LM317T. -Wymagania przed montażem (wariant B): +Requirements before installation (variant B): -- bezpiecznik dobrany do przewodów i poboru, blisko źródła; nie zastępuje TVS; -- ochrona przed odwrotną polaryzacją i ujemnymi przepięciami; -- TVS i ograniczenie energii dobrane do rzeczywistego profilu przepięć, bez - przewodzenia przy normalnym 14,4–14,8 V i bez przekraczania VIN LM317T; -- kondensatory zgodne z kartą LM317, krótkie pętle prądowe; -- pomiar szczytów prądu S2 Mini + CC1101 i sprawdzenie stabilności 3,3 V; -- obliczenia termiczne dla najwyższej temperatury oraz testy brownout/crank/load - dump, EMC i ESD na docelowej płytce. +- a fuse matched to the wiring and consumption, close to the source; it does + not replace a TVS; +- reverse-polarity and negative-transient protection; +- TVS and energy limitation matched to the real transient profile, without + conducting at a normal 14.4–14.8 V and without exceeding the LM317T VIN; +- capacitors per the LM317 datasheet, short current loops; +- a measurement of the current peaks of the S2 Mini + CC1101 and a check of + 3.3 V stability; +- thermal calculations for the highest temperature and tests of + brownout/crank/load dump, EMC, and ESD on the target board. -LM317T jest regulatorem liniowym: `P = (VIN − 3,3 V) × I`. Już przy 14,4 V -i 300 mA trzeba odprowadzić ok. **3,3 W**. Bez obliczenia i radiatora TO-220 -może się przegrzewać; samo „do 1,5 A” z karty nie gwarantuje zasilania szczytów -ESP32-S2 w każdych warunkach. Zmierz prąd i temperaturę przy nadawaniu. +The LM317T is a linear regulator: `P = (VIN − 3.3 V) × I`. Already at 14.4 V +and 300 mA you must dissipate about **3.3 W**. Without a calculation and a +TO-220 heatsink it can overheat; the "up to 1.5 A" from the datasheet alone +does not guarantee ESP32-S2 peak supply in all conditions. Measure current +and temperature while transmitting. -**Konsekwencja zasilania wyłącznie z gniazda zapalniczki:** po wyłączeniu -zapłonu cały emulator traci zasilanie. Nie wykonuje wtedy deep sleep ani -transmisji parkingowych, RTC nie odlicza interwału, a ustawienie -`interval parking` nie ma znaczenia. Wejście `PIN_ACC` nie jest potrzebne. -Po przekręceniu stacyjki urządzenie po prostu startuje i nadaje. Jeżeli -urządzenie ma nadawać również na postoju, potrzebne jest stale zasilane, -zabezpieczone wejście oraz osobny, zabezpieczony sygnał ACC na GPIO2. Wtedy -trzeba też zmierzyć pobór całego układu: dzielnik LM317T pobiera stale ok. -5 mA, do tego S2 Mini, CC1101 i dzielniki — może być istotny przy długim -postoju. +**Consequence of powering only from the cigarette-lighter socket:** when the +ignition goes off, the whole emulator loses power. It then performs no deep +sleep or parking transmission, the RTC does not count the interval, and the +`interval parking` setting has no effect. The `PIN_ACC` input is not needed. +After the ignition is switched on, the device simply starts and transmits. If +the device is to transmit while parked too, a permanently powered, protected +input and a separate, protected ACC signal on GPIO2 are required. Then the +consumption of the whole assembly also has to be measured: the LM317T divider +draws a constant ~5 mA, plus the S2 Mini, the CC1101, and the dividers — it +may matter on a long park. -Parametry LM317T i wymagane kondensatory: karta ST -[LM317](https://www.st.com/resource/en/datasheet/lm317.pdf), schemat -typowej aplikacji i rysunek połączeń TO-220. Dostęp: 2026-10-28. +LM317T parameters and required capacitors: the ST datasheet +[LM317](https://www.st.com/resource/en/datasheet/lm317.pdf), the typical +application schematic and the TO-220 pinout drawing. Accessed 2026-10-28. -## Zasilanie bateryjne +## Battery power -Ogniwo 18650 w kabinie **nie jest rekomendowane**: temperatura w samochodzie może -przekraczać bezpieczne warunki ogniwa, a zainstalowane ogniwo wymaga ochrony, -właściwego ładowania i obudowy. ESP32 z radiem i okresowym czuwaniem zwykle daje -krótki czas pracy; deklaracje wieloletniej pracy byłyby nieuzasadnione. Wieloletni -wariant bateryjny wymaga innej architektury low-power i nie należy do tego release. +An 18650 cell in the cabin is **not recommended**: the temperature in a car +can exceed the cell's safe conditions, and an installed cell requires +protection, proper charging, and an enclosure. An ESP32 with a radio and +periodic duty cycling usually gives short runtime; claims of multi-year +operation would be unfounded. A multi-year battery variant requires a +different low-power architecture and is not part of this release. -## Opcjonalny LF +## Optional LF -RC działa bez EL-50448. Nie ma w nim zwalidowanego odbiornika LF. Przyszły moduł -wymaga osobnego schematu rezonansu/detekcji 125 kHz, progu komparatora, filtracji, -testu odporności na zakłócenia i udowodnionego budzenia. Wyjście front-endu na -GPIO14 ma być aktywne stanem niskim i w spoczynku wysokim. Sam aktywator nie -wpisuje ID do emulatora. +The RC works without the EL-50448. It contains no validated LF receiver. A +future module requires a separate 125 kHz resonance/detection schematic, a +comparator threshold, filtering, an interference-immunity test, and proven +waking. The front-end output on GPIO14 is to be active-low and high at rest. +The activator itself does not enter IDs into the emulator. diff --git a/docs/POWER.md b/docs/POWER.md index 672a4ef..e26a89d 100644 --- a/docs/POWER.md +++ b/docs/POWER.md @@ -1,76 +1,88 @@ -# Energia i zachowanie na postoju +# Energy and parking behaviour -## Status pomiarów +## Measurement status -**Nie wykonano pomiarów prądu fizycznego prototypu.** Liczby poniżej są -szacunkami budżetu, nie wynikiem walidacji. S2 Mini nie nadaje się do deklaracji -poboru µA bez pomiaru: wbudowany regulator, LED i obwody pomocnicze zwiększają -pobór. Sam LM317T obciąża zasilanie prądem dzielnika ok. 5 mA (R1 = 240 Ω) -plus prąd własny, więc zasilanie stałe wymaga osobnego bilansu energetycznego. -Docelowe zasilanie z gniazda zapalniczki „po stacyjce” zdejmuje ten problem: -przy wyłączonym zapłonie emulator nie pobiera prądu wcale. +**No current measurements of the physical prototype have been performed.** +The numbers below are budget estimates, not validated results. The S2 Mini +is not suitable for declaring µA consumption without measurement: the built-in +regulator, LED, and auxiliary circuits add consumption. The LM317T itself +loads the supply with a divider current of about 5 mA (R1 = 240 Ω) plus its +own quiescent current, so a permanent supply needs a separate energy budget. +The target supply from an ignition-switched cigarette-lighter socket removes +this problem: with the ignition off the emulator draws no current at all. -## Harmonogram firmware +## Firmware schedule -- NORMAL po wybudzeniu RTC: inicjalizacja, burst czterech kół, wyjście z TX i deep - sleep. Nie ma 10-sekundowego okna konsoli po zwykłym budziku. -- Mikrodrzemki: sen jest dzielony na kawałki tak, żeby dioda migała co ok. 2 s - także między wysyłkami (`NAP_PERIOD_MS` w `config.h`). Po budzeniu timera - urządzenie pokazuje jedno widoczne mignięcie i śpi resztę okresu po czasie - boot + okno (`NAP_AWAKE_MS`). Przycisk budzi natychmiast (EXT1) niezależnie - od mikrodrzemek. -- TX ramek pozostaje co interwał (domyślnie 30 s): licznik snu w pamięci RTC - zlicza przespane kawałki od ostatniego cyklu TX; `interval` wchodzi w życie - przy następnym cyklu. Po dłuższym czuwaniu (np. `stay`) pierwszy kawałek - jest pełny. -- **Mikrodrzemki zwiększają pobór** (boot co ok. 2 s zamiast jednego snu na - interwał) — liczby poniżej opisują stary model i wymagają pomiaru HIL. -- Po power-on, przycisku lub LF: okno konsoli 10 s; `stay N` wydłuża je. -- LEARN: TX jednego koła co 2 s, bez deep sleep, maks. 60 s na koło/15 min sesji. -- SINGLE: TX jednego koła co 2 s, bez deep sleep, maks. 5 min. -- CC1101 przechodzi w SPWD przed snem; CS jest wysoki, SCK/MOSI niskie, LED off. -- Każdy sen ma budzik RTC. `PARKING_SHUTDOWN` usunięto — urządzenie nie może - pozostać uśpione do czasu wyłącznie ręcznego wybudzenia. -- ACC (opcjonalny sprzętowo) wybiera interwał ignition/parking. Nie jest potrzebne - jako jedyne źródło wybudzenia, ponieważ RTC zawsze działa. Jeżeli cały układ - zasilany jest tylko z gniazda zapalniczki „po stacyjce” lub z ACC, po ACC OFF - nie ma zasilania, RTC ani transmisji — i jest to docelowy scenariusz. +- NORMAL after the RTC wake: initialisation, a burst of four wheels, exit of + TX, and deep sleep. There is no 10-second console window after a plain wake. +- Micro-naps: sleep is split into pieces so that the LED blinks about every + 2 s, also between transmissions (`NAP_PERIOD_MS` in `config.h`). After a + timer wake the device shows one visible blink and sleeps the rest of the + period after boot time + window (`NAP_AWAKE_MS`). The button wakes + immediately (EXT1) regardless of the micro-naps. +- TX of frames remains on the interval (default 30 s): the sleep counter in + RTC memory counts the slept pieces since the last TX cycle; `interval` + takes effect on the next cycle. After a longer awake period (e.g. `stay`), + the first piece is a full one. +- **Micro-naps raise consumption** (a boot about every 2 s instead of one + sleep per interval) — the numbers below describe the old model and require + HIL measurement. +- After power-on, a button, or LF: a 10 s console window; `stay N` extends it. +- LEARN: TX of one wheel every 2 s, without deep sleep, max 60 s per wheel/ + 15 min per session. +- SINGLE: TX of one wheel every 2 s, without deep sleep, max 5 min. +- The CC1101 enters SPWD before sleep; CS is high, SCK/MOSI low, LED off. +- Every sleep has an RTC alarm. `PARKING_SHUTDOWN` was removed — the device + cannot remain asleep until a purely manual wake. +- ACC (optional in hardware) selects the ignition/parking interval. It is not + needed as the only wake source, because the RTC always runs. If the whole + assembly is powered only from an ignition-switched lighter socket or from + ACC, then with ACC off there is no power, no RTC, and no transmission — + and that is the target scenario. -## Szacunek ładunku dla ustawień domyślnych +## Charge estimate for the default settings -Jedna ramka to 240 × 120 µs = 28,8 ms na antenie. Dla 4 kół × 3 ramki: -345,6 ms samej transmisji plus 8 × 50 ms przerw wewnątrz burstów. Do tego dochodzi -boot, konfiguracja, SPI i logi. Do obliczeń energii trzeba zmierzyć cały cykl, -a nie tylko czas OOK. +One frame is 240 × 120 µs = 28.8 ms on air. For 4 wheels × 3 frames: +345.6 ms of transmission plus 8 × 50 ms gaps inside the bursts. On top of +that come boot, configuration, SPI, and logging. For energy calculations you +must measure the whole cycle, not just the OOK time. -Przykładowy model (do zastąpienia pomiarem): jeżeli aktywność ESP32 wyniesie 1,0 s -przy 80 mA co 30 s, sam ESP32 uśrednia ok. 2,7 mA na 3,3 V. CC1101, boot i prąd snu -dodają kolejne składniki. Przy interwale 120 s udział aktywności spada ok. czterokrotnie, -ale stały Iq zasilacza i dzielników pozostaje. Nie są to zmierzone 2,7 mA ani -obietnica poboru z akumulatora 12 V. +An example model (to be replaced by measurement): if ESP32 activity is 1.0 s +at 80 mA every 30 s, the ESP32 alone averages about 2.7 mA at 3.3 V. The +CC1101, boot, and sleep current add further terms. With a 120 s interval the +activity share falls about fourfold, but the constant Iq of the regulator and +the dividers remains. These are not measured 2.7 mA nor a promise of +consumption from a 12 V battery. -## Metoda pomiaru wymagana przed „validated” +## Measurement method required before "validated" -1. **Cały S2 Mini w sleep:** miernik µA szeregowo na wejściu, nie przez USB. - Odczekać do końca TX i zanotować minimum/stan stabilny oraz model płytki. -2. **S2 Mini + LM317T:** powtórzyć pomiar na zabezpieczonym wejściu VIN i na - szynie 3,3 V. Uwzględnić prąd dzielnika regulatora, TVS, pozostałe dzielniki - i pull-upy. -3. **Cykl NORMAL:** bocznik + oscyloskop albo logger z odpowiednim pasmem. - Zarejestrować boot, 12 ramek, przerwy, wejście w sen przez co najmniej 10 cykli. -4. **Średnia:** całkować ładunek co najmniej 15 min przy 30 s i 120 s. Podawać - warunki: napięcie, temperatura, PA, wersja płytki i firmware. -5. **LEARN/SINGLE:** osobno zmierzyć prąd ciągłego czuwania. -6. **ACC/brownout/crank:** sprawdzić restart, powrót do nadawania i integralność - NVS. Nie wykonywać na GPIO bez potwierdzonej ochrony wejścia. +1. **The whole S2 Mini in sleep:** a µA meter in series at the input, not + through USB. Wait until TX ends and record the minimum/steady state and + the board model. +2. **S2 Mini + LM317T:** repeat the measurement on the protected VIN input + and on the 3.3 V rail. Include the regulator divider current, TVS, the + other dividers, and pull-ups. +3. **NORMAL cycle:** a shunt + oscilloscope or a logger with sufficient + bandwidth. Record boot, 12 frames, gaps, and entering sleep over at least + 10 cycles. +4. **Average:** integrate the charge for at least 15 min at 30 s and 120 s. + State the conditions: voltage, temperature, PA, board and firmware + version. +5. **LEARN/SINGLE:** measure the continuous-awake current separately. +6. **ACC/brownout/crank:** check restart, the return to transmission, and NVS + integrity. Do not test on GPIO without confirmed input protection. -## Wnioski dopuszczalne przed pomiarem +## Conclusions allowed before measurement -- Największy wpływ mają interwał, czas czuwania, PA i Iq całej płytki. -- Do wersji energooszczędnej trzeba zmierzyć cały S2 Mini i LM317T; przy - zasilaniu wyłącznie z gniazda zapalniczki „po stacyjce” układ nie pobiera - prądu po wyłączeniu zapłonu, ale wtedy również nie nadaje w trybie - parkingowym — co jest zgodne z założeniem, bo ECU auta wtedy nie nasłuchuje. -- Nie rekomendujemy 18650 w kabinie ani wieloletniej pracy bateryjnej z ESP32. -- Stały pobór emulatora trzeba uwzględnić przy długim postoju pojazdu; nie podajemy - czasu „bezpiecznego dla akumulatora” bez pomiaru całego samochodu. +- The interval, awake time, PA, and the whole board's Iq have the largest + impact. +- A power-saving version requires measuring the whole S2 Mini and LM317T; + with power only from an ignition-switched lighter socket the assembly draws + no current after the ignition goes off, but then it also transmits no + parking mode — which matches the assumption, because the car ECU does not + listen then. +- We do not recommend an 18650 in the cabin, nor multi-year battery operation + with an ESP32. +- The emulator's constant consumption must be accounted for during a long + park; we do not give a "safe for the battery" time without measuring the + whole car. diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.md index de8ee2d..07b5a1e 100644 --- a/docs/PROTOCOL.md +++ b/docs/PROTOCOL.md @@ -1,99 +1,109 @@ -# Protokół Schrader EG53MA4 — fakty i niewiadome +# Schrader EG53MA4 protocol — facts and unknowns -## Przypięte źródła +## Pinned sources -| Źródło | Wersja użyta do walidacji | Zakres | +| Source | Version used for validation | Scope | |---|---|---| -| `rtl_433/src/devices/schraeder.c` | commit `406f9a33550a2b6b3d0d8a8a486417ce5b3f13ab` | dekoder i parametry slicera | -| `rtl_433_tests/tests/Schrader_EG53MA4_TPMS/01` | commit `1aa8c29d6b9383739d1aeed495dbc5069b704392` | cztery nagrania CU8 + JSON | +| `rtl_433/src/devices/schraeder.c` | commit `406f9a33550a2b6b3d0d8a8a486417ce5b3f13ab` | decoder and slicer parameters | +| `rtl_433_tests/tests/Schrader_EG53MA4_TPMS/01` | commit `1aa8c29d6b9383739d1aeed495dbc5069b704392` | four CU8 recordings + JSON | | PlatformIO | 6.1.18 | build/test | -| `espressif32` | 8.0.0 | toolchain/platforma ESP32 | -| SmartRC-CC1101-Driver-Lib | `de6757ef633b3e626dae5c7835cdb66ab53f9a1d` (3.0.2) | konfiguracja CC1101 | -| Praktyczna analiza odbioru | | kontekst; nie źródło pól ramki | -| Wzorzec integracji ESP32+CC1101 | | integracja, nie protokół EG53MA4 | +| `espressif32` | 8.0.0 | toolchain/ESP32 platform | +| SmartRC-CC1101-Driver-Lib | `de6757ef633b3e626dae5c7835cdb66ab53f9a1d` (3.0.2) | CC1101 configuration | +| Practical receiver analysis | | context; not a source of frame fields | +| ESP32+CC1101 integration pattern | | integration, not the EG53MA4 protocol | -Nie używamy nieoznaczonego `master` jako referencji reprodukowalnej. Komercyjny -emulator potwierdza -jedynie istnienie takiej klasy urządzenia, nie zgodność tego projektu. +We do not use the unlabelled `master` as a reproducible reference. The +commercial emulator +only confirms that such a class of device exists, not this project's +compatibility. -## Potwierdzony format po dekodowaniu Manchester +## Confirmed format after Manchester decoding -Dekoder wymaga dokładnie 120 bitów: 40 bitów synchronizacji i 80 bitów danych. +The decoder requires exactly 120 bits: 40 bits of synchronisation and 80 data +bits. ```text 0 40 72 96 104 112 120 | 40 × sync (0) | flags 4 B | ID 3 B | P 1 B | T 1 B | sum 1 B | - 4C 90 00 70 2F C8 71 68 49 65 + 4C 90 00 70 2F C8 71 68 49 65 ``` -- `flags`: 32 bity; znaczenie pól nie jest w pełni znane. -- `ID`: 24 bity; firmware odrzuca 0, `FFFFFF` i duplikaty między kołami. -- `P`: 2,5 kPa/bit **wg dekodera rtl_433, ale skala nie jest potwierdzona** — - wszystkie cztery nagrania mają `P = 0`, więc żadne prawdziwe ciśnienie nie - zweryfikowało przelicznika (w źródle dekodera to „probable"). Pomiar z auta: - `P = 104` (260 kPa wg skali rtl_433) pokazuje się jako **284 kPa**, więc - firmware koryguje skalę stałą `TPMS_PRESSURE_KPA100_PER_RAW` - (`tpms_frame.h`, domyślnie 273 = 2,73 kPa/bit; `P = 95` dla 260 kPa). - Kwantyzacja: `(kPa×100 + 136) / 273`. Kalibracja potwierdzona na sprzęcie: - 260 kPa → 260 kPa na wyświetlaczu auta (`AUDIT.md`). -- `T`: bajt w °F zgodnie z dekoderem, nie °C. 23 °C → 73 °F. -- `sum`: suma dziewięciu poprzednich bajtów modulo 256; to nie CRC-8. -- Wartość `4c900070` występuje we wszystkich 64 rekordach czterech nagrań. - Nie dowodzi to, że każdy czujnik/tryb auta używa zawsze tej wartości. +- `flags`: 32 bits; the field meanings are not fully known. +- `ID`: 24 bits; the firmware rejects 0, `FFFFFF`, and duplicates between + wheels. +- `P`: 2.5 kPa/bit **according to the rtl_433 decoder, but the scale is not + confirmed** — all four captures have `P = 0`, so no real pressure verified + the conversion (in the decoder source it is "probable"). A car measurement: + `P = 104` (260 kPa on the rtl_433 scale) shows up as **284 kPa**, so the + firmware corrects the scale with the constant + `TPMS_PRESSURE_KPA100_PER_RAW` (`tpms_frame.h`, default 273 = 2.73 kPa/bit; + `P = 95` for 260 kPa). Quantisation: `(kPa×100 + 136) / 273`. Calibration + confirmed on hardware: 260 kPa → 260 kPa on the car display (`AUDIT.md`). +- `T`: byte in °F per the decoder, not °C. 23 °C → 73 °F. +- `sum`: the sum of the nine preceding bytes modulo 256; it is not CRC-8. +- The value `4c900070` occurs in all 64 records of the four captures. That + does not prove that every sensor/car mode always uses this value. -## Polaryzacja, preambuła i ogon +## Polarity, preamble, and tail -Nagrania i slicer `OOK_PULSE_MANCHESTER_ZEROBIT` potwierdzają G.E.T. Manchester: -`0 → 01`, `1 → 10`. Slicer dopisuje pierwszy zerowy bit. Bufor CC1101 zawiera: +The recordings and the `OOK_PULSE_MANCHESTER_ZEROBIT` slicer confirm G.E.T. +Manchester: `0 → 01`, `1 → 10`. The slicer prepends the first zero bit. The +CC1101 buffer contains: ```text -1 chip startowy + 39 komórek sync + 80 komórek danych + 1 chip OFF dopełnienia -= 240 chipów = 30 bajtów, MSB first. +1 starting chip + 39 sync cells + 80 data cells + 1 OFF padding chip += 240 chips = 30 bytes, MSB first. ``` -Ostatni chip dopełnienia jest zerem OOK (cisza). Test sprawdza dokładnie tę -długość, polaryzację i odrzuca ucięty/uszkodony bufor. +The last padding chip is an OOK zero (silence). The test checks exactly this +length and polarity and rejects a truncated/corrupted buffer. -## Timing i powtórzenia +## Timing and repetitions -- Dekoder ma `short_width=123 µs`, `reset_limit=300 µs`. -- Analiza `gfile001` pokazuje typowy okres pulse+gap ok. 236 µs, czyli chip - ok. **118 µs**; szerokości impulsów różnią się od szerokości przerw. Firmware - używa eksperymentalnie **120 µs**, co przechodzi dekodowanie niezależnym - `rtl_433`. Dokładny zegar fizycznego CC1101 wymaga pomiaru HIL. -- Każde z czterech nagrań zawiera **16 poprawnych powtórzeń**. W `gfile001` - odstępy początków dekodowań wahają się ok. 115–172 ms; nie są stałe. -- Domyślne **3 ramki, przerwa 50 ms, cykl 30 s** są eksperymentalnymi - ustawieniami emulatora, a nie potwierdzonym harmonogramem OE. Interwały - ACC/parking również nie mają statusu zgodności z OE. +- The decoder has `short_width=123 µs`, `reset_limit=300 µs`. +- Analysis of `gfile001` shows a typical pulse+gap period of about 236 µs, + i.e. a chip of about **118 µs**; pulse widths differ from gap widths. The + firmware uses **120 µs** experimentally, which decodes on an independent + `rtl_433`. The exact clock of a physical CC1101 requires an HIL measurement. +- Each of the four recordings contains **16 valid repetitions**. In + `gfile001` the gaps between decode starts vary roughly 115–172 ms; they are + not constant. +- The defaults of **3 frames, a 50 ms gap, a 30 s cycle** are experimental + emulator settings, not a confirmed OE schedule. The ACC/parking intervals + also have no OE-compatibility status. -## Nośna i modulacja +## Carrier and modulation -Podstawowy profil: **433,92 MHz, ASK/OOK**. Nagrania są zdekodowane przy tej -częstotliwości. README zestawu zawiera też dane produktu 315 MHz i wzmiankę -ASK+FSK; to nie jest dowód FSK w analizowanych plikach ani zgodności z konkretną -Astrą. FSK nie jest dostępny w podstawowym firmware/generatorze. +The base profile: **433.92 MHz, ASK/OOK**. The recordings are decoded at this +frequency. The kit's README also contains 315 MHz product data and a mention +of ASK+FSK; that is no evidence of FSK in the analysed files nor of +compatibility with the specific Astra. FSK is not available in the base +firmware/generator. ## CC1101 packet engine -Firmware ustawia fixed-length 30 B, normal FIFO, MSB first oraz wyłącza sprzętowe: -preambułę/sync (`SYNC_MODE=0`), Manchester, whitening, FEC, CRC, address check, -append status. Cała preambuła i suma protokołu są w naszych 30 B. Koniec TX jest -oczekiwany przez `MARCSTATE=IDLE` z limitem; `TXFIFO_UNDERFLOW` i pozostałe bajty -są błędem. To zapobiega obcięciu ogona przez samo `TXBYTES=0`. +The firmware sets fixed-length 30 B, a normal FIFO, MSB first, and disables +the hardware preamble/sync (`SYNC_MODE=0`), Manchester, whitening, FEC, CRC, +address check, and append status. The whole preamble and the protocol's sum +are inside our 30 bytes. End of TX is expected via `MARCSTATE=IDLE` with a +limit; `TXFIFO_UNDERFLOW` and leftover bytes are errors. This prevents the +tail from being truncated by `TXBYTES=0` alone. -Konfiguracja została audytowana, ale syntetyczny CU8 omija CC1101. Brak dodatkowych -bajtów i dokładny ogon trzeba jeszcze potwierdzić na logic analyzer/RTL-SDR w HIL. +The configuration has been audited, but the synthetic CU8 bypasses the +CC1101. The absence of extra bytes and the exact tail still have to be +confirmed on a logic analyser/RTL-SDR in HIL. -## Niewiadome — nie wolno ich „dostrajać” losowo +## Unknowns — they must not be "tuned" randomly -1. Znaczenie poszczególnych bitów `flags`, w tym jakiegokolwiek bitu niskiej - baterii czujnika. **`TPMS_FLAGS_LOWBAT_MASK` nie istnieje w firmware.** -2. Zależność flags od nauki, ruchu, LF i stanu baterii oryginalnego czujnika. -3. Wymagany przez konkretne ECU interwał i minimalna liczba powtórzeń. -4. Zgodność OE 13506028/numera powiązanego z konkretnym egzemplarzem bez VIN, - oznaczeń, odczytu albo testu. -5. Fizyczna dokładność częstotliwości, moc i ogon generowanego CC1101 przed HIL. +1. The meaning of individual `flags` bits, including any sensor low-battery + bit. **`TPMS_FLAGS_LOWBAT_MASK` does not exist in the firmware.** +2. The dependence of flags on learning, motion, LF, and the original sensor's + battery state. +3. The interval and minimal number of repetitions required by a specific ECU. +4. The compatibility of OE 13506028/a related part number with a specific + unit without a VIN, markings, a readout, or a test. +5. The physical accuracy of frequency, power, and the tail of the generated + CC1101 transmission before HIL. -Niskie zasilanie emulatora jest wyłącznie ostrzeżeniem w konsoli i nie zmienia -żadnego pola symulowanego czujnika. +Low emulator supply is only a console warning and does not change any field +of the simulated sensor. diff --git a/docs/SAFETY.md b/docs/SAFETY.md index cdf7a08..016662b 100644 --- a/docs/SAFETY.md +++ b/docs/SAFETY.md @@ -1,42 +1,47 @@ -# Bezpieczeństwo i ograniczenia +# Safety and limitations -## Sztuczne dane mogą ukryć usterkę +## Synthetic data can hide a fault -To urządzenie generuje dane, których nie mierzy w oponach. Domyślne 260 kPa jest -wartością testową, nie potwierdzeniem ciśnienia. Symulator może spowodować, że -kontrolka nie ostrzeże o realnym przebiciu, utracie ciśnienia lub uszkodzeniu opony. +This device generates data it does not measure in the tyres. The default +260 kPa is a test value, not confirmation of pressure. The simulator may cause +the warning light not to alert about a real puncture, pressure loss or tyre +damage. -- Projekt wyłącznie diagnostyczno-warsztatowy, na postoju i pod kontrolą osoby - wykonującej test. -- Nie jest homologowanym czujnikiem ani zamiennikiem sprawnego TPMS. -- Nie używaj w jeździe drogowej i nie przedstawiaj jako bezpiecznego do tego celu. -- Przed i po teście sprawdź wszystkie opony niezależnym manometrem oraz ich stan. -- Po diagnozie przywróć sprawne, właściwie dobrane czujniki i wykonaj wymaganą - procedurę pojazdu. +- A diagnostic and workshop project only, on a parked car and under the + control of the person running the test. +- It is not a homologated sensor nor a replacement for a working TPMS. +- Do not use while driving and do not present it as safe for that purpose. +- Before and after the test, check all tyres with an independent gauge and + inspect their condition. +- After the diagnosis, restore working, correctly matched sensors and perform + the vehicle's required procedure. -## Radio i zgodność pojazdu +## Radio and vehicle compatibility -Profil EG53MA4/OOK 433,92 MHz jest hipotezą roboczą dla wskazanego pojazdu do -potwierdzenia. OE 13506028, numer powiązany lub oferta zamiennika nie wystarcza. -Użyj VIN, oznaczeń fabrycznych czujników, diagnostyki albo kontrolowanego testu. -Nie nadawaj z maksymalną mocą „dla pewności”. Zacznij od −10 dBm, ogranicz czas -transmisji i przestrzegaj lokalnych przepisów dotyczących 433 MHz oraz ingerencji -w elektronikę pojazdu. Urządzenie może być odbierane przez inne odbiorniki w pobliżu. +The EG53MA4/OOK 433.92 MHz profile is a working hypothesis for the vehicle +indicated, to be confirmed. OE 13506028, a related part number, or a +replacement offer is not enough. Use the VIN, factory sensor markings, +diagnostics, or a controlled test. Do not transmit at maximum power "to be +sure". Start at −10 dBm, limit transmission time, and follow local 433 MHz +regulations and rules about interfering with vehicle electronics. The device +may be received by other receivers nearby. -## Montaż +## Installation -- Tylko prototyp laboratoryjny jest opisany jako gotowy do złożenia. Wersja 12 V - wymaga osobnego projektu i testów automotive. -- Nie podawaj 12 V na GPIO/ADC ani 5 V na CC1101. -- Nie umieszczaj urządzenia w strefie poduszek, pedałów, ruchomych elementów, - wilgoci, wysokiej temperatury ani przy instalacji LPG. -- Zabezpiecz obudowę i przewody przed poluzowaniem. Unikaj ekranowania anteny. -- Nie używaj 18650 jako rekomendowanego zasilania w kabinie. +- Only the laboratory prototype is described as ready to assemble. The 12 V + version requires a separate design and automotive tests. +- Do not apply 12 V to GPIO/ADC or 5 V to the CC1101. +- Do not place the device near airbags, pedals, moving parts, moisture, high + temperature, or the LPG installation. +- Secure the enclosure and cables against loosening. Avoid shielding the + antenna. +- Do not use an 18650 cell as the recommended power source in the cabin. -## Diagnostyka bez fałszywej pewności +## Diagnostics without false confidence -Poprawne dekodowanie przez rtl_433 nie dowodzi odbioru przez samochód. Zielone CI -nie zastępuje pomiaru CC1101, testu HIL ani kontroli opon. Zgaśnięcie kontrolki -również nie dowodzi, że opony są sprawne. Zapisuj pomiary i nie zmieniaj wielu -parametrów naraz. Brak potwierdzonego bitu niskiej baterii czujnika; niskie -zasilanie emulatora nie jest kodowane jako usterka symulowanego czujnika. +Correct decoding by rtl_433 does not prove reception by the car. Green CI does +not replace a CC1101 measurement, an HIL test, or a tyre check. The warning +light going out also does not prove the tyres are sound. Record measurements +and do not change several parameters at once. There is no confirmed low +battery bit of the sensor; low emulator supply is not encoded as a fault of +the simulated sensor. diff --git a/docs/SETUP.md b/docs/SETUP.md index a5c6193..8999939 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -1,23 +1,26 @@ -# Konfiguracja i uruchomienie +# Configuration and startup -## Przed rozpoczęciem +## Before you start -1. Sprawdź zgodność konkretnego auta (VIN, oznaczenia czujników, diagnostyka lub - odbiór). Nie polegaj wyłącznie na numerze z ogłoszenia. -2. Zmontuj prototyp z `HARDWARE.md`, wgraj firmware i otwórz UART 115200. -3. Wpisz `stay 300`. `info` pokazuje konfigurację aktywną, nie tylko zapisaną. -4. Pracuj na postoju. Sztuczne 260 kPa nie opisuje rzeczywistych opon. +1. Verify compatibility of the specific car (VIN, sensor markings, + diagnostics, or reception). Do not rely solely on a number from a listing. +2. Assemble the prototype per `HARDWARE.md`, flash the firmware, and open a + 115200 UART. +3. Type `stay 300`. `info` shows the active configuration, not just the saved + one. +4. Work on a parked car. The synthetic 260 kPa does not describe the real + tyres. -Koła: `1=FL` przód lewy, `2=FR` przód prawy, `3=RR` tył prawy, `4=RL` tył lewy. -Komendy konfiguracyjne automatycznie zapisują NVS i weryfikują odczyt. Błąd NVS -trzeba rozwiązać przed dalszym testem, nie ignorować. +Wheels: `1=FL` front left, `2=FR` front right, `3=RR` rear right, `4=RL` rear +left. Configuration commands save to NVS automatically and verify the read +back. An NVS error must be resolved before further testing, not ignored. -## Ścieżka A — Clone IDs (preferowana) +## Path A — Clone IDs (preferred) -Użyj jej, jeśli wcześniej odczytano oryginalne ID i auto nadal je zna. +Use it when the original IDs were read earlier and the car still knows them. -1. Zapisz cztery ID w postaci sześciu cyfr hex. -2. Wpisz kolejno (przykładowe wartości zastąp własnymi): +1. Write down four IDs as six-digit hex. +2. Enter in turn (replace the example values with your own): ```text id 1 2FC871 @@ -28,75 +31,81 @@ Użyj jej, jeśli wcześniej odczytano oryginalne ID i auto nadal je zna. info ``` -3. Sprawdź w `info`, że wszystkie ID i przypisania kół są właściwe. Duplikat, - `000000`, `FFFFFF` lub wartość poza 24 bitami zostanie odrzucona. -4. Opcjonalnie `send` wymusi cykl wszystkich kół. W NORMAL urządzenie robi to - również automatycznie; po restarcie konfiguracja pozostaje. -5. Potwierdź odbiór zewnętrznie. Znane ID **mogą** wyeliminować naukę, ale nie - obiecujemy tego dla każdego stanu ECU. +3. Check in `info` that all IDs and wheel assignments are correct. A + duplicate, `000000`, `FFFFFF`, or a value beyond 24 bits will be rejected. +4. Optionally, `send` forces a cycle of all wheels. In NORMAL the device does + it automatically as well; after a restart the configuration remains. +5. Confirm reception externally. Known IDs **may** eliminate learning, but we + do not promise that for every ECU state. -Nie używaj przykładowych ID w pojeździe, jeśli mogą pokrywać się z innym -urządzeniem w pobliżu. +Do not use the example IDs in a vehicle if they may coincide with another +device nearby. -## Ścieżka B — New IDs + LEARN +## Path B — New IDs + LEARN -### Przygotowanie +### Preparation -1. `ids new` generuje cztery unikalne ID. Można zamiast tego użyć czterech `id`. -2. `info` — zapisz ID na kartce. -3. Zapoznaj się z procedurą nauki dla konkretnej wersji nadwozia/wyposażenia. - Ten dokument nie zgaduje menu, sekwencji pedałów ani położenia odbiornika. -4. Rozpocznij procedurę nauki w aucie zgodnie z instrukcją serwisową. +1. `ids new` generates four unique IDs. You can use four `id` commands + instead. +2. `info` — write the IDs down on paper. +3. Read the learning procedure for the specific model/equipment version. This + document does not guess menus, pedal sequences, or the receiver location. +4. Start the learning procedure in the car according to its service + instructions. -### Nauka z konsoli +### Learning from the console -1. `mode learn` — start od FL; tylko FL nadaje co 2 s. -2. `send` — natychmiastowy burst FL, bez zmiany koła. -3. Po wykonaniu kroku dla FL: `next` — FR; LED wskaże 2 mrugnięcia. -4. Powtórz `send`, potem `next` — RR, następnie `next` — RL. -5. Po ostatnim `next` urządzenie wraca do NORMAL. Kolejność to zawsze +1. `mode learn` — starts at FL; only FL transmits every 2 s. +2. `send` — immediate FL burst, without changing the wheel. +3. After completing the step for FL: `next` — FR; the LED shows 2 blinks. +4. Repeat `send`, then `next` — RR, then `next` — RL. +5. After the last `next` the device returns to NORMAL. The order is always **FL → FR → RR → RL**. -6. Zakończ procedurę auta zgodnie z jej instrukcją i sprawdź odczyt diagnostyczny. +6. Finish the car procedure according to its instructions and check the + diagnostic readout. -### Nauka jednym przyciskiem +### Learning with one button -- wejście: przytrzymaj ≥1,5 s; -- krótkie naciśnięcie: następne koło i natychmiastowy burst; -- wymuszenie bez zmiany koła: konsola `send`; -- wyjście przed końcem: ponownie ≥1,5 s albo `mode normal`. +- enter: hold ≥1.5 s; +- short press: next wheel and an immediate burst; +- force without changing the wheel: console `send`; +- exit before the end: hold ≥1.5 s again or `mode normal`. -Timeout 60 s na koło przerywa LEARN do NORMAL; limit całej sesji to 15 min. -Nie jest to automatyczny sukces nauki — trzeba zacząć od właściwego koła ponownie. +A 60 s timeout per wheel aborts LEARN to NORMAL; the whole session limit is +15 min. This is not an automatic learning success — you have to start again +from the right wheel. -## SINGLE / diagnostyka +## SINGLE / diagnostics -`mode single 2` nadaje tylko FR co 2 s. `send` wymusza FR, `next` przechodzi dalej. -`mode normal` kończy; automatyczny limit wynosi 5 min. Tryb nie zapisuje wyboru -koła w NVS i po utracie zasilania startuje bezpiecznie w NORMAL. +`mode single 2` transmits only FR every 2 s. `send` forces FR, `next` moves +on. `mode normal` ends it; the automatic limit is 5 min. The mode does not +save the wheel selection in NVS and starts safely in NORMAL after a power +loss. -## Pozostałe ustawienia +## Other settings -| Komenda | Zakres / skutek | +| Command | Range / effect | |---|---| -| `pressure all 260` | 0–637,5 kPa, krok bajtu P ≈ 2,73 kPa (kalibracja wg auta, `PROTOCOL.md`) | -| `temp all 23` | −40…85 °C; w ramce °F | -| `interval normal 30` | interwał bez ACC, 5–86400 s | -| `interval ignition 30` | z aktywnym sprzętowym ACC | -| `interval parking 120` | bez aktywnego ACC | -| `rf freq 433.92` | 433,05–434,79 MHz; zmiana wymaga uzasadnienia | +| `pressure all 260` | 0–637.5 kPa, P byte step ≈ 2.73 kPa (calibrated per the car, `PROTOCOL.md`) | +| `temp all 23` | −40…85 °C; °F in the frame | +| `interval normal 30` | interval without ACC, 5–86400 s | +| `interval ignition 30` | with hardware ACC active | +| `interval parking 120` | without active ACC | +| `rf freq 433.92` | 433.05–434.79 MHz; changes require justification | | `rf power -10` | −30, −20, −15, −10, −6, 0, 5 dBm | -| `rf burst 3` | 1–8 ramek na koło | -| `rf gap 50` | 20–500 ms między ramkami | -| `flags 4C900070` | eksperyment; znaczenie bitów nie jest znane | -| `factory YES` | kasuje własną konfigurację i przywraca domyślną | +| `rf burst 3` | 1–8 frames per wheel | +| `rf gap 50` | 20–500 ms between frames | +| `flags 4C900070` | experiment; bit meanings are unknown | +| `factory YES` | erases your configuration and restores defaults | -Parametry harmonogramu są eksperymentalne. Moc zaczyna się od −10 dBm; zwiększaj -tylko po pomiarze i z uwzględnieniem przepisów. Niski poziom zasilania emulatora -nie ustawia żadnej flagi czujnika. +Schedule parameters are experimental. Power starts at −10 dBm; increase it +only after a measurement and with the regulations in mind. Low emulator +supply sets no sensor flag. -## Po restarcie lub brownout +## After a restart or brownout -Firmware ponownie czyta NVS. Poprawna wersja/CRC i zakresy są wymagane. Uszkodzony -lub niezgodny wpis powoduje komunikat i powrót do domyślnych, a nie wysyłanie -częściowo uszkodzonej konfiguracji. Każdy deep sleep ma budzik; nie ma trybu -`PARKING_SHUTDOWN`, który mógłby zostawić auto bez transmisji do ręcznego wybudzenia. +The firmware reads NVS again. A correct version/CRC and ranges are required. +A damaged or incompatible entry produces a message and a return to defaults, +rather than transmitting a partly corrupted configuration. Every deep sleep +has an alarm; there is no `PARKING_SHUTDOWN` mode that could leave the car +without transmission until a manual wake. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 7c8de0a..ba885b8 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -1,37 +1,38 @@ -# Rozwiązywanie problemów +# Troubleshooting -Pracuj po jednej zmianie i zapisuj pomiar. Nie przełączaj losowo OOK/FSK, flags, -ID ani interwałów. Podstawowy firmware nie ma trybu FSK. +Work one change at a time and record the measurement. Do not switch OOK/FSK, +flags, IDs, or intervals randomly. The base firmware has no FSK mode. -| Objaw | Możliwa przyczyna | Pomiar / sprawdzenie | Naprawa | +| Symptom | Possible cause | Measurement / check | Repair | |---|---|---|---| -| `BLAD: brak CC1101` | złe zasilanie, CS/SPI, moduł nie 433 MHz | 3,3 V na VCC-GND; ciągłość SCK/MISO/MOSI/CS = 4/5/6/7; oznaczenie modułu | popraw okablowanie, skróć SPI, użyj właściwego modułu | -| Reset przy TX | spadek 3,3 V, słabe przewody | napięcie przy ESP32/CC1101 podczas `send`, log brownout | popraw zasilacz i 47–100 µF przy module; nie zwiększaj PA | -| `TX-ERR` | underflow, niezakończony TX, zła konfiguracja CC1101 | log dla każdego koła; MARCSTATE/rejestry w HIL | sprawdź SPI i zasilanie; zapisz log do analizy, nie maskuj błędu | -| USB/UART nie odpowiada | za krótkie okno konsoli, zły baud/port, kabel tylko do ładowania | 115200 8N1, reset, właściwy `/dev/ttyACM*` lub `/dev/ttyUSB*` | wpisz `stay 300` od razu po starcie; użyj kabla z danymi | -| Zmiana ID znika | błąd zapisu NVS, pełny flash | komunikat `OK: zapisano`, restart i `info` | nie kontynuuj przy błędzie NVS; sprawdź flash/zasilanie | -| ID odrzucone | duplikat, 0, FFFFFF, zła długość | sześć cyfr hex i `info` | nadaj cztery unikalne ID z 000001–FFFFFE | -| rtl_433 nic nie dekoduje | antena, częstotliwość, zły tor RF, zbyt mała moc | `send 1`; odbiornik 433,92 MHz blisko; pomiar ANT/GDO0 | popraw antenę/zasilanie; stopniowo testuj niskie moce; nie zmieniaj na FSK | -| rtl_433 widzi złe dane | stara konfiguracja, sąsiedni czujnik | `info`, `hex 1`, filtrowanie ID w odbiorniku | porównaj ID i wymuś `send 1` w izolowanym miejscu | -| Auto nie widzi znanych ID | niepotwierdzony profil, ECU wymaga nauki, zasięg | VIN/oznaczenia/DTC; odbiór RTL-SDR przy aucie | potwierdź profil; wykonaj LEARN; zmień położenie po pomiarze | -| LEARN stoi na jednym kole | użyto `send` zamiast `next` | `info` pokazuje aktywne koło | `next` po potwierdzeniu kroku; `send` tylko wymusza TX | -| LEARN wróciło do NORMAL | 60 s na kole / 15 min sesji | czas od wejścia, komunikat i LED | uruchom `mode learn 1` i powtórz świadomie od FL | -| Po RL nie ma następnego koła | sekwencja została zakończona | NORMAL w `info` | zakończ procedurę auta i sprawdź DTC | -| Kontrolka nie gaśnie mimo RTL-SDR OK | ECU nie zna ID, inny profil/flags/procedura | odczyt ID i DTC z diagnostyki, nie tylko SDR | Clone IDs albo LEARN; potwierdź profil auta; nie zgaduj flags | -| Pobór snu duży | S2 Mini, LM317T, LED, dzielniki | pomiar całej płytki i regulatora wg `POWER.md` | popraw zasilanie; nie zmieniaj protokołu | -| Po postoju brak TX | zasilanie tylko z gniazda zapalniczki/ACC, brownout, błąd NVS/CC1101 | czy po wyłączeniu zapłonu zostaje 3,3 V; log po restarcie, `batt`, `info` | przy zasilaniu tylko z gniazda „po stacyjce” brak TX jest oczekiwany; w innym układzie popraw zasilanie | -| ACC nie zmienia interwału | funkcja domyślnie wyłączona lub zły próg | `PIN_ACC`, napięcie na GPIO OFF/ON | zmontuj zabezpieczone wejście; nigdy 12 V na GPIO | +| `ERROR: no CC1101` | poor supply, CS/SPI, module is not 433 MHz | 3.3 V across VCC-GND; continuity SCK/MISO/MOSI/CS = 4/5/6/7; module marking | fix wiring, shorten SPI, use the correct module | +| Reset during TX | 3.3 V droop, weak wires | voltage at the ESP32/CC1101 during `send`, brownout log | fix the supply and 47–100 µF at the module; do not raise the PA | +| `TX-ERR` | underflow, unfinished TX, wrong CC1101 configuration | log for each wheel; MARCSTATE/registers in HIL | check SPI and supply; save the log for analysis, do not mask the error | +| USB/UART does not respond | console window too short, wrong baud/port, charge-only cable | 115200 8N1, reset, correct `/dev/ttyACM*` or `/dev/ttyUSB*` | type `stay 300` right after startup; use a data cable | +| ID change disappears | NVS write error, full flash | `OK: saved` message, restart and `info` | do not continue on an NVS error; check flash/supply | +| ID rejected | duplicate, 0, FFFFFF, wrong length | six hex digits and `info` | transmit four unique IDs from 000001–FFFFFE | +| rtl_433 decodes nothing | antenna, frequency, wrong RF path, too little power | `send 1`; 433.92 MHz receiver close by; ANT/GDO0 measurement | fix antenna/supply; step through low powers gradually; do not switch to FSK | +| rtl_433 sees wrong data | stale configuration, neighbouring sensor | `info`, `hex 1`, ID filtering in the receiver | compare IDs and force `send 1` in an isolated spot | +| Car does not see known IDs | unconfirmed profile, ECU requires learning, range | VIN/markings/DTC; RTL-SDR reception at the car | confirm the profile; perform LEARN; change position after measuring | +| LEARN stuck on one wheel | used `send` instead of `next` | `info` shows the active wheel | `next` after confirming the step; `send` only forces TX | +| LEARN returned to NORMAL | 60 s per wheel / 15 min session | elapsed time, message and LED | run `mode learn 1` and consciously repeat from FL | +| After RL there is no next wheel | the sequence completed | NORMAL in `info` | finish the car procedure and check DTC | +| Warning light stays on although RTL-SDR is OK | ECU does not know the IDs, other profile/flags/procedure | read IDs and DTC from diagnostics, not only SDR | Clone IDs or LEARN; confirm the car profile; do not guess flags | +| High sleep consumption | S2 Mini, LM317T, LED, dividers | measure the whole board and regulator per `POWER.md` | fix the supply; do not change the protocol | +| No TX after parking | supply only from the lighter socket/ACC, brownout, NVS/CC1101 error | does 3.3 V remain after the ignition goes off; log after restart, `batt`, `info` | with an ignition-switched socket supply the lack of TX is expected; otherwise fix the supply | +| ACC does not change the interval | feature disabled by default or wrong threshold | `PIN_ACC`, voltage on GPIO OFF/ON | build a protected input; never 12 V on GPIO | -## Gdy brak odbioru w samochodzie +## When the car does not receive -Kolejność diagnostyczna: +Diagnostic sequence: -1. **Udowodnij lokalny TX:** `send 1` + RTL-SDR/analizator. -2. **Udowodnij właściwy profil:** VIN, oznaczenia czujników, odczyt auta. -3. **Sprawdź ID i kolejność:** `info`, Clone IDs albo jeden aktywny w LEARN. -4. **Sprawdź zasięg:** niska moc najpierw, konsola/za schowkiem, ewentualnie - bagażnik; bez demontażu poduszek i zgadywania lokalizacji ECU. -5. **Dopiero analizuj flags:** porównaj z nagraniem oryginalnego czujnika tego - samego trybu. Brak potwierdzonego bitu low battery — nie ustawiaj go. -6. Jeśli nie ma pomiaru lub danych, zatrzymaj test. Losowe zmiany tworzą nowe - zmienne i nie stanowią diagnozy. +1. **Prove local TX:** `send 1` + RTL-SDR/analyser. +2. **Prove the correct profile:** VIN, sensor markings, car readout. +3. **Check IDs and order:** `info`, Clone IDs, or one active wheel in LEARN. +4. **Check range:** low power first, console/behind the glovebox, possibly the + boot; without disassembling airbags or guessing the ECU location. +5. **Only then analyse flags:** compare with a recording of the original + sensor in the same mode. There is no confirmed low-battery bit — do not + set it. +6. If there is no measurement or data, stop the test. Random changes add new + variables and are not a diagnosis. diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md index 2e26c1f..65caeb3 100644 --- a/docs/VALIDATION.md +++ b/docs/VALIDATION.md @@ -1,125 +1,130 @@ -# Walidacja +# Validation -## Jedno polecenie bez sprzętu +## One command without hardware ```bash bash tools/check_all ``` -Skrypt wykonuje self-test Pythona, testy native, pełny build ESP32, cppcheck, -pobranie przypiętych źródeł (przy pierwszym uruchomieniu) oraz dekodowanie CU8 -przez prawdziwy `rtl_433`. Logi: `artifacts/validation/`. Każdy etap ma `pipefail`, -a błąd kończy skrypt kodem niezerowym. +The script runs the Python self-test, native tests, the full ESP32 build, +cppcheck, fetching the pinned sources (on first run), and CU8 decoding by the +real `rtl_433`. Logs: `artifacts/validation/`. Every stage has `pipefail`, +and an error ends the script with a non-zero code. -Alternatywa reprodukowalna: +A reproducible alternative: ```bash docker build -t tpms-rc . docker run --rm -v "$PWD/artifacts:/work/artifacts" tpms-rc ``` -## Wyniki z 2026-10-28 +## Results from 2026-10-28 -Środowisko: Linux, Python 3.14.4 przy teście hosta; PlatformIO 6.1.18; +Environment: Linux, Python 3.14.4 on the host test; PlatformIO 6.1.18; espressif32 8.0.0; Arduino ESP32 3.3.12; SmartRC CC1101 commit `de6757ef633b3e626dae5c7835cdb66ab53f9a1d`; rtl_433 commit `406f9a3…`; -rtl_433_tests commit `1aa8c29…`. Pełne SHA znajdują się w `PROTOCOL.md`. +rtl_433_tests commit `1aa8c29…`. Full SHAs are in `PROTOCOL.md`. -| Komenda | Wynik | +| Command | Result | |---|---| -| `pio test -e native` | **24/24 PASS** — ramka, cztery niezależne wektory, negatywne, NVS, parsowanie konsoli (NaN/zakresy), fake clock/radio, Clone IDs, LEARN, SINGLE, ACC, restart | -| `pio run -e esp32s2mini` | **PASS**, własne ostrzeżenia traktowane jako błędy (`-Werror`) | -| `pio check -e native ... --fail-on-defect=low` | **PASS**, 0 defektów po poprawce inicjalizacji struktur | -| `python3 tools/tpms_frame.py --self-test` | **PASS**, nagranie + 500 ramek | -| `tools/verify_rtl433.sh` | **PASS**, 64/64 rekordy referencyjne; 3/3 syntetyczne; 3/3 negatywne odrzucone | +| `pio test -e native` | **24/24 PASS** — frame, four independent vectors, negative tests, NVS, console parsing (NaN/ranges), fake clock/radio, Clone IDs, LEARN, SINGLE, ACC, restart | +| `pio run -e esp32s2mini` | **PASS**, own warnings treated as errors (`-Werror`) | +| `pio check -e native ... --fail-on-defect=low` | **PASS**, 0 defects after the struct initialisation fix | +| `python3 tools/tpms_frame.py --self-test` | **PASS**, capture + 500 frames | +| `tools/verify_rtl433.sh` | **PASS**, 64/64 reference records; 3/3 synthetic; 3/3 negative rejected | | `git diff --check` | **PASS** | -| `bash tools/package_release.sh` | **PASS**, obraz ESP32-S2 z bootloaderem od `0x1000` i manifestem SHA-256 | +| `bash tools/package_release.sh` | **PASS**, ESP32-S2 image with the bootloader at `0x1000` and a SHA-256 manifest | -Dane referencyjne: każdy z `gfile001`…`gfile004` dał dokładnie 16 zgodnych -rekordów, z oczekiwanym ID/flags/ciśnieniem/temperaturą. Syntetyczne ramki -2FC871/260 kPa/73 F, 3495AC/220 kPa/23 F i ABCDEE/262,5 kPa/75 F zostały -zdekodowane przez niezależny `rtl_433`. Uszkodzony Manchester, zła suma i ucięcie -nie dały rekordu EG53MA4. +Reference data: each of `gfile001`…`gfile004` produced exactly 16 matching +records, with the expected ID/flags/pressure/temperature. The synthetic frames +2FC871/260 kPa/73 F, 3495AC/220 kPa/23 F and ABCDEE/262.5 kPa/75 F were +decoded by an independent `rtl_433`. Damaged Manchester, a wrong sum, and +truncation produced no EG53MA4 record. -## Macierz pokrycia +## Coverage matrix -| Warstwa | Automatyczne | RTL-SDR fizyczny | CC1101 fizyczny | Samochód | +| Layer | Automated | Physical RTL-SDR | Physical CC1101 | Car | |---|---|---|---|---| -| pola, checksum, kwantyzacja | wykonane | niepotrzebne do pola | niepotrzebne | potwierdzenie interpretacji ECU | -| Manchester/preambuła/długość | wykonane | **niewykonane** | **niewykonane** | niewykonane | -| prawdziwe nagrania → rtl_433 | wykonane, 64/64 | nie dotyczy | nie dotyczy | nie dotyczy | -| syntetyczne CU8 → rtl_433 | wykonane | nie dotyczy | omija hardware | nie dotyczy | -| rejestry CC1101/ogon/moc/częstotliwość | audyt kodu | wymagane | **wymagane** | wymagane | -| NVS, ID, interwały, tryby | wykonane; NVS emulowane blobem | wymagany test restartu | wymagany | wymagany | -| LEARN FL→FR→RR→RL | state-machine PASS | pomocnicze | wymagane | **niewykonane** | -| pobór/brownout/ACC | state-machine ACC; brak pomiarów | nie dotyczy | wymagane | wymagane | +| fields, checksum, quantisation | done | not needed for the field | not needed | confirmation of ECU interpretation | +| Manchester/preamble/length | done | **not done** | **not done** | not done | +| real recordings → rtl_433 | done, 64/64 | n/a | n/a | n/a | +| synthetic CU8 → rtl_433 | done | n/a | bypasses hardware | n/a | +| CC1101 registers/tail/power/frequency | code audit | required | **required** | required | +| NVS, IDs, intervals, modes | done; NVS emulated with a blob | a restart test is required | required | required | +| LEARN FL→FR→RR→RL | state machine PASS | auxiliary | required | **not done** | +| consumption/brownout/ACC | ACC in the state machine; no measurements | n/a | required | required | -**Brak podstaw do oznaczenia „validated”.** Gitea Actions ma workflow, ale stan -runnera i wynik zdalnego CI należy sprawdzić; lokalny PASS nie jest udawanym CI. +**There is no basis for a "validated" label.** Gitea Actions has a workflow, +but the runner state and the remote CI result must be checked; a local PASS +is not pretend CI. -## Checklista HIL — wymaga użytkownika i sprzętu +## HIL checklist — requires a user and hardware -### CC1101 + analizator/RTL-SDR +### CC1101 + analyser/RTL-SDR -- [ ] Odczytać rejestry po inicjalizacji: OOK, 433,92 MHz, fixed 30 B, - `SYNC_MODE=0`, brak CRC/Manchester/whitening/FEC/append. -- [ ] Na GDO0/ANT potwierdzić dokładnie 30 B, chip ~120 µs, pełny ostatni chip - i brak sprzętowej preambuły/sync/CRC/dodatkowych bajtów. -- [ ] Zanotować TX-ERR/underflow; przy prawidłowym torze ma ich nie być. -- [ ] Zmierzyć częstotliwość i względną moc dla −10 dBm; nie zakładać kalibracji - taniego modułu. Nie zwiększać PA bez potrzeby. -- [ ] `send 1`…`send 4`: RTL-SDR dekoduje właściwe ID, 260 kPa i flags. -- [ ] Powtórzyć po resecie i 10 cyklach deep sleep. +- [ ] Read the registers after initialisation: OOK, 433.92 MHz, fixed 30 B, + `SYNC_MODE=0`, no CRC/Manchester/whitening/FEC/append. +- [ ] On GDO0/ANT confirm exactly 30 B, a ~120 µs chip, a full last chip, and + no hardware preamble/sync/CRC/extra bytes. +- [ ] Record TX-ERR/underflow; there should be none on a correct RF path. +- [ ] Measure the frequency and relative power at −10 dBm; do not assume the + calibration of a cheap module. Do not raise the PA unnecessarily. +- [ ] `send 1`…`send 4`: RTL-SDR decodes the correct IDs, 260 kPa and flags. +- [ ] Repeat after a reset and 10 deep sleep cycles. -### NVS i wejścia +### NVS and inputs -- [ ] Ustawić własne ID/ciśnienia/RF, odłączyć zasilanie na >1 min, ponownie - sprawdzić `info` i transmisję. -- [ ] Sprawdzić odrzucenie duplikatu ID, złej mocy i złego interwału. -- [ ] `factory YES` przywraca 260 kPa i domyślne RF. -- [ ] Brownout/crank na zabezpieczonym zasilaczu: brak zawieszenia i uszkodzenia - konfiguracji; zapis wykonywać tylko po stabilizacji zasilania. -- [ ] Jeśli ACC jest montowane: zmierzyć napięcie na GPIO dla OFF/ON/przepięcia, - sprawdzić interwały i samoczynne wznowienie po ACC ON. Bez ACC pominąć. +- [ ] Set your own IDs/pressures/RF, disconnect power for >1 min, and re-check + `info` and transmission. +- [ ] Verify rejection of a duplicate ID, a bad power, and a bad interval. +- [ ] `factory YES` restores 260 kPa and the default RF. +- [ ] Brownout/crank on a protected supply: no hang or configuration damage; + write settings only after the supply stabilises. +- [ ] If ACC is installed: measure the GPIO voltage for OFF/ON/transients, + check the intervals and automatic resumption after ACC ON. Skip without + ACC. -### Konkretny Opel Astra J +### The specific Opel Astra J -- [ ] Potwierdzić profil przez VIN/oznaczenia/diagnostykę przed nadawaniem. -- [ ] Clone IDs: odbiór czterech znanych ID bez zakładania, że nauka zniknie. -- [ ] New IDs: pełna nauka FL→FR→RR→RL z jednym aktywnym kołem. -- [ ] Odczyt DTC i danych TPMS przed/po; zapisać wersję ECU i procedurę. -- [ ] Test położenia: konsola środkowa/za schowkiem, ewentualnie bagażnik; - na postoju, bez zgadywania lokalizacji odbiornika. -- [ ] Kontrola manometrem wszystkich opon przed i po. Nie wykonywać testu jako - jazdy drogowej z symulatorem zamiast sprawnego TPMS. +- [ ] Confirm the profile via VIN/markings/diagnostics before transmitting. +- [ ] Clone IDs: reception of the four known IDs without assuming learning + will vanish. +- [ ] New IDs: full learning FL→FR→RR→RL with one active wheel. +- [ ] DTC and TPMS data read before/after; record the ECU version and + procedure. +- [ ] Position test: centre console/behind the glovebox, possibly the boot; + while parked, without guessing the receiver location. +- [ ] A tyre gauge check of all wheels before and after. Do not perform the + test as a road drive with the simulator in place of a working TPMS. -## Artefakty i wgrywanie +## Artifacts and flashing ```bash bash tools/package_release.sh ``` -Katalog `artifacts/release/`: +The `artifacts/release/` directory: -| Plik | Adres | +| File | Address | |---|---:| -| `bootloader.bin` | `0x1000` — adres dla ESP32-S2, nie `0x0` jak w ESP32-C3 | +| `bootloader.bin` | `0x1000` — the address for ESP32-S2, not `0x0` as in ESP32-C3 | | `partitions.bin` | `0x8000` | | `boot_app0.bin` | `0xE000` | | `firmware.bin` | `0x10000` | -| `firmware-full.bin` | `0x0` — pełny obraz 4 MB | -| `firmware.elf` | debug/symbole, nie wgrywać jako flash | -| `SHA256SUMS`, `BUILD-INFO.txt` | kontrola integralności i wersji | +| `firmware-full.bin` | `0x0` — the full 4 MB image | +| `firmware.elf` | debug/symbols, do not flash it | +| `SHA256SUMS`, `BUILD-INFO.txt` | integrity and version check | -Pełny obraz kasuje poprzedni flash przy zapisie całego obszaru; NVS w partycji -może zostać utracone — zapisz ID przed aktualizacją pełnym obrazem. Aktualizacja -samej aplikacji `firmware.bin` pod `0x10000` zwykle zachowuje NVS, ale przed -release użytkownik powinien wykonać test na własnym module. +The full image erases the previous flash while writing the whole area; NVS in +that partition may be lost — write down your IDs before updating with the +full image. Updating only the application `firmware.bin` at `0x10000` +usually preserves NVS, but before a release the user should test it on their +own module. ```bash PORT=/dev/ttyACM0 bash tools/flash_release.sh (cd artifacts/release && sha256sum -c SHA256SUMS) ``` -Nie wgrywaj obrazu z innego toolchaina na ślepo. RC nie zawiera fizycznego testu -update ani samochodu. +Do not flash an image from another toolchain blindly. The RC contains no +physical update test or car test. diff --git a/platformio.ini b/platformio.ini index 13c47b2..5e3b677 100644 --- a/platformio.ini +++ b/platformio.ini @@ -1,40 +1,40 @@ -; PlatformIO - symulator czujnikow TPMS Schrader EG53MA4 (ESP32 + CC1101) +; PlatformIO - Schrader EG53MA4 TPMS sensor simulator (ESP32 + CC1101) ; -; Kompilacja: pio run -e esp32s2mini -; Testy: pio test -e native -; Upload: pio run -e esp32s2mini -t upload -; Monitor: pio device monitor +; Build: pio run -e esp32s2mini +; Tests: pio test -e native +; Upload: pio run -e esp32s2mini -t upload +; Monitor: pio device monitor ; -; Zastrzezenie: projekt diagnostyczny/testowy - symulator generuje -; sztuczne dane cisnienia, nie zastepuje prawdziwych czujnikow TPMS. +; Disclaimer: diagnostic/test project - the simulator generates +; synthetic pressure data and does not replace real TPMS sensors. [platformio] default_envs = esp32s2mini [env:esp32s2mini] -; Wersje przypiete do zweryfikowanego buildu (espressif32 8.0.0, +; Versions pinned to the verified build (espressif32 8.0.0, ; SmartRC-CC1101-Driver-Lib 3.0.2 = commit de6757e) platform = espressif32@8.0.0 -; ESP32-S2-MINI (ESP32-S2FN4R2, np. ARD-ESP32-S2-MINI): płytka typu -; Lolin/Wemos S2 Mini; sprzedawana z MicroPythonem, wgrywamy wlasny firmware. +; ESP32-S2-MINI (ESP32-S2FN4R2, e.g. ARD-ESP32-S2-MINI): a Lolin/Wemos +; S2 Mini type board; sold with MicroPython, we flash our own firmware. board = lolin_s2_mini framework = arduino monitor_speed = 115200 -; Biblioteka CC1101 (ELECHOUSE_CC1101_SRC_DRV / SmartRC): -; wymagana wersja >= 2.5.7 (wspolne API setSpiPin/setGDO0 dla 2.5.x i 3.x). +; CC1101 library (ELECHOUSE_CC1101_SRC_DRV / SmartRC): +; version >= 2.5.7 required (shared setSpiPin/setGDO0 API for 2.5.x and 3.x). lib_deps = https://github.com/LSatan/SmartRC-CC1101-Driver-Lib.git#de6757ef633b3e626dae5c7835cdb66ab53f9a1d build_flags = -Wall -Wextra -Werror - ; Natywne USB ESP32-S2: konsola Serial i programowanie bez mostka UART. - ; ARDUINO_USB_MODE pozostaje domyslny dla lolin_s2_mini (=0). + ; Native ESP32-S2 USB: Serial console and flashing without a UART bridge. + ; ARDUINO_USB_MODE remains the default for lolin_s2_mini (=0). -DARDUINO_USB_CDC_ON_BOOT=1 [env:native] -; Przenosna logika: ramka, NVS, parsowanie konsoli i maszyna stanow -; (PIN_ACC wlaczony w testach). +; Portable logic: frame, NVS, console parsing and the state machine +; (PIN_ACC enabled in tests). platform = native build_flags = -std=gnu++17 -Wall -Wextra -Werror -DPIN_ACC=2 build_src_filter = -<*> + + + + diff --git a/src/app_state.h b/src/app_state.h index 08bf403..79a96b3 100644 --- a/src/app_state.h +++ b/src/app_state.h @@ -1,4 +1,4 @@ -/* Przenosna maszyna stanow NORMAL/LEARN/SINGLE (fake clock/radio w testach). */ +/* Portable NORMAL/LEARN/SINGLE state machine (fake clock/radio in tests). */ #ifndef TPMS_APP_STATE_H #define TPMS_APP_STATE_H diff --git a/src/config.h b/src/config.h index 17a832b..b2b40b9 100644 --- a/src/config.h +++ b/src/config.h @@ -1,37 +1,37 @@ -/* Konfiguracja sprzetu. Dane czujnikow i RF sa w NVS, nie wymagaja rekompilacji. */ +/* Hardware configuration. Sensor and RF data live in NVS, no recompile needed. */ #ifndef TPMS_CONFIG_H #define TPMS_CONFIG_H #define FW_VERSION "2.0.0-rc.1" -/* ESP32-S2-MINI (ESP32-S2FN4R2) + CC1101 433 MHz (3,3 V). - * GPIO19/20 to natywne USB, GPIO26-32 obsluguja flash/PSRAM w obudowie, - * GPIO45/46 to piny strapping - nie uzywac ich do CC1101. */ +/* ESP32-S2-MINI (ESP32-S2FN4R2) + CC1101 433 MHz (3.3 V). + * GPIO19/20 are native USB, GPIO26-32 serve in-package flash/PSRAM, + * GPIO45/46 are strapping pins - do not use them for the CC1101. */ #define PIN_CC1101_SCK 4 #define PIN_CC1101_MISO 5 #define PIN_CC1101_MOSI 6 #define PIN_CC1101_CS 7 #define PIN_CC1101_GDO0 10 -/* Przycisk sterujacy i budzenie z deep sleep: przycisk BOOT plytki - * (GPIO0 do GND), potwierdzony testem na sprzecie. GPIO0 to pin strapping: - * przytrzymany podczas zasilania/reset uruchamia bootloader zamiast firmware. - * Zewnetrzny przycisk monostabilny mozna podlaczyc zamiast tego pod GPIO3 - * i przelaczyc -DPIN_BUTTON=3 w build_flags. */ +/* Control button and wake from deep sleep: the board's BOOT button + * (GPIO0 to GND), confirmed by a bench test. GPIO0 is a strapping pin: + * held during power-up/reset it starts the bootloader instead of the firmware. + * An external momentary button can be wired to GPIO3 instead, selecting + * -DPIN_BUTTON=3 in build_flags. */ #ifndef PIN_BUTTON #define PIN_BUTTON 0 #endif #define BTN_ACTIVE_LEVEL 0 -/* Wbudowana niebieska LED S2 Mini na GPIO15 jest aktywna stanem wysokim. */ +/* The S2 Mini's built-in blue LED on GPIO15 is active-high. */ #define PIN_LED 15 #define LED_ACTIVE_LEVEL 1 -/* Opcje wylaczone do czasu zmontowania i przetestowania sprzetu. */ +/* Options disabled until the hardware is assembled and tested. */ #ifndef PIN_LF_TRIGGER #define PIN_LF_TRIGGER -1 #endif -/* LF dzieli z przyciskiem GPIO wakeup LOW; na ESP32-S2 wakeup wymaga pinu - * RTC (GPIO0-21). Proponowane GPIO14, bo GPIO1 zajmuje ADC zasilania. */ +/* LF shares the button's GPIO wakeup LOW; on ESP32-S2 wakeup requires an + * RTC pin (GPIO0-21). GPIO14 is suggested because GPIO1 holds the supply ADC. */ #define LF_ACTIVE_LEVEL 0 #ifndef PIN_ACC #define PIN_ACC -1 @@ -39,28 +39,29 @@ #ifndef PIN_VBAT_ADC #define PIN_VBAT_ADC 1 #endif -/* Dzielnik mierzy zasilanie 12 V (prog LOWBATT 11,5 V). R2 = 180 kOhm - * daje pelny zakres ADC ok. 16,4 V przy pelnej skali 2,5 V (11 dB): - * 14,8 V ladowania daje 2,25 V na pinie, wiec odczyt nie nasyci sie. - * Wczesniejsze 270 kOhm nasycale ADC juz przy ok. 11,8 V. */ +/* Divider measures the 12 V supply (LOWBATT threshold 11.5 V). R2 = 180 kOhm + * gives the ADC a full-scale range of about 16.4 V at 2.5 V full scale (11 dB): + * a 14.8 V charge voltage yields 2.25 V at the pin, so the reading saturates + * no earlier. The previous 270 kOhm divider saturated the ADC at ~11.8 V. */ #define VBAT_DIVIDER_R1 1000000.0f #define VBAT_DIVIDER_R2 180000.0f #define VBAT_CAL 1.000f #define VBAT_SAMPLES 16 #define LOWBATT_THRESHOLD_MV 11500 -/* Jedyny profil produkcyjny: OOK, Manchester 0->01, 1->10. */ +/* The only production profile: OOK, Manchester 0->01, 1->10. */ #define TPMS_CHIP_US 120u -/* Harmonogram i moc poczatkowa: settings_defaults() w settings.cpp. - * Sa to parametry eksperymentalne, a nie potwierdzony harmonogram OE. */ +/* Schedule and initial power: settings_defaults() in settings.cpp. + * These are experimental parameters, not a confirmed OE schedule. */ #define BOOT_STAY_AWAKE_MS 10000u -/* Mikrodrzemki: zamiast jednego dlugiego snu LED miga co NAP_PERIOD_MS takze - * miedzy wysylkami. Sen to reszta okresu po czasie boot + okno, a TX ramek - * TPMS pozostaje co interwal (licznik w pamieci RTC). */ +/* Micro-naps: instead of one long sleep the LED blinks every NAP_PERIOD_MS, + * also between transmissions. Sleep is the remainder of the period after + * boot time + window, and TPMS frame TX remains on the interval (counter + * in RTC memory). */ #define NAP_PERIOD_MS 2000u -#define NAP_AWAKE_MS 400u /* widoczne migniecie LED po budziku timera */ +#define NAP_AWAKE_MS 400u /* visible LED blink after the timer wake */ #define NAP_MIN_SLEEP_MS 200u #define SERIAL_BAUD 115200 diff --git a/src/console.cpp b/src/console.cpp index 7014da0..64e20be 100644 --- a/src/console.cpp +++ b/src/console.cpp @@ -1,4 +1,4 @@ -/* Konsola szeregowa: konfiguracja zapisywana w NVS, bez rekompilacji. */ +/* Serial console: configuration stored in NVS, no recompilation needed. */ #include #include #include @@ -29,18 +29,18 @@ static bool parse_wheel(const char *text, uint8_t *wheel, bool allow_all = false static void cmd_help(void) { - Serial.println(F("POMOC (zmiany konfiguracji zapisuja sie automatycznie):")); + Serial.println(F("HELP (configuration changes are saved automatically):")); Serial.println(F(" info | hex [1-4|all] | send [1-4|all] | batt")); Serial.println(F(" mode normal | mode learn [1-4] | mode single 1-4 | next")); - Serial.println(F(" id 1-4 XXXXXX - ustaw 24-bit ID (hex)")); - Serial.println(F(" ids new - wygeneruj 4 unikalne ID")); - Serial.println(F(" pressure 1-4|all KPA - np. pressure all 260")); - Serial.println(F(" temp 1-4|all C - temperatura -40..85 C")); + Serial.println(F(" id 1-4 XXXXXX - set 24-bit ID (hex)")); + Serial.println(F(" ids new - generate 4 unique IDs")); + Serial.println(F(" pressure 1-4|all KPA - e.g. pressure all 260")); + Serial.println(F(" temp 1-4|all C - temperature -40..85 C")); Serial.println(F(" interval normal|ignition|parking 5-86400")); Serial.println(F(" rf freq 433.05-434.79 | rf power -30..5 | rf burst 1-8")); - Serial.println(F(" rf gap 20-500 - odstep miedzy ramkami [ms]")); - Serial.println(F(" flags HEX - 32-bit flags (znaczenie nie w pelni znane)")); - Serial.println(F(" factory YES - przywroc fabryczne | save | stay [s] | sleep")); + Serial.println(F(" rf gap 20-500 - gap between frames [ms]")); + Serial.println(F(" flags HEX - 32-bit flags (meaning not fully known)")); + Serial.println(F(" factory YES - restore factory | save | stay [s] | sleep")); } static void cmd_send(const char *arg) @@ -52,21 +52,21 @@ static void cmd_send(const char *arg) } else if (parse_wheel(arg, &wheel, true)) { ok = wheel == 0xFFu ? g_app->send_all() : g_app->send_wheel(wheel); } else { - Serial.println(F("BLAD: send [1-4|all]")); + Serial.println(F("ERROR: send [1-4|all]")); return; } - Serial.println(ok ? F("OK") : F("BLAD TX")); + Serial.println(ok ? F("OK") : F("TX ERROR")); } static void cmd_mode(const char *arg1, const char *arg2) { if (arg1 == NULL) { - Serial.println(F("BLAD: mode normal|learn|single [1-4]")); + Serial.println(F("ERROR: mode normal|learn|single [1-4]")); return; } uint8_t wheel = WHEEL_FL; if (arg2 != NULL && !parse_wheel(arg2, &wheel)) { - Serial.println(F("BLAD: kolo 1-4")); + Serial.println(F("ERROR: wheel 1-4")); return; } if (strcmp(arg1, "normal") == 0) { @@ -76,7 +76,7 @@ static void cmd_mode(const char *arg1, const char *arg2) } else if (strcmp(arg1, "single") == 0 && arg2 != NULL) { g_app->set_mode(AppMode::SINGLE, wheel, millis()); } else { - Serial.println(F("BLAD: mode normal|learn [1-4]|single 1-4")); + Serial.println(F("ERROR: mode normal|learn [1-4]|single 1-4")); return; } Serial.println(F("OK")); @@ -88,7 +88,7 @@ static void cmd_id(const char *wheel_text, const char *id_text) uint32_t id; if (!parse_wheel(wheel_text, &wheel) || !parse_u32(id_text, 1u, 0xFFFFFEu, &id, 16) || !settings_set_id(&g_settings, wheel, id)) { - Serial.println(F("BLAD: id 1-4 000001..FFFFFE; ID musza byc unikalne")); + Serial.println(F("ERROR: id 1-4 000001..FFFFFE; IDs must be unique")); return; } app_save_and_apply(); @@ -99,7 +99,7 @@ static void cmd_pressure_temp(const char *which, const char *wheel_text, { uint8_t wheel; if (!parse_wheel(wheel_text, &wheel, true)) { - Serial.println(F("BLAD: kolo 1-4 lub all")); + Serial.println(F("ERROR: wheel 1-4 or all")); return; } uint8_t first = wheel == 0xFFu ? 0u : wheel; @@ -107,7 +107,7 @@ static void cmd_pressure_temp(const char *which, const char *wheel_text, if (strcmp(which, "pressure") == 0) { float kpa; if (!parse_float(value_text, 0.0f, 637.5f, &kpa)) { - Serial.println(F("BLAD: cisnienie 0..637.5 kPa")); + Serial.println(F("ERROR: pressure 0..637.5 kPa")); return; } uint16_t value = (uint16_t)(kpa * 10.0f + 0.5f); @@ -117,7 +117,7 @@ static void cmd_pressure_temp(const char *which, const char *wheel_text, } else { int32_t value; if (!parse_i32(value_text, -40, 85, &value)) { - Serial.println(F("BLAD: temperatura -40..85 C")); + Serial.println(F("ERROR: temperature -40..85 C")); return; } for (uint8_t i = first; i < last; ++i) { @@ -132,7 +132,7 @@ static void cmd_interval(const char *which, const char *value_text) uint32_t value; if (which == NULL || !parse_u32(value_text, SETTINGS_INTERVAL_MIN_S, SETTINGS_INTERVAL_MAX_S, &value)) { - Serial.println(F("BLAD: interval normal|ignition|parking 5-86400")); + Serial.println(F("ERROR: interval normal|ignition|parking 5-86400")); return; } if (strcmp(which, "normal") == 0) { @@ -142,7 +142,7 @@ static void cmd_interval(const char *which, const char *value_text) } else if (strcmp(which, "parking") == 0) { g_settings.parking_interval_s = value; } else { - Serial.println(F("BLAD: rodzaj interwalu")); + Serial.println(F("ERROR: interval kind")); return; } app_save_and_apply(); @@ -154,7 +154,7 @@ static void cmd_rf(const char *which, const char *value_text) int32_t signed_value; float frequency; if (which == NULL) { - Serial.println(F("BLAD: rf freq|power|burst|gap")); + Serial.println(F("ERROR: rf freq|power|burst|gap")); return; } if (strcmp(which, "freq") == 0 && parse_float(value_text, 433.05f, 434.79f, &frequency)) { @@ -168,7 +168,7 @@ static void cmd_rf(const char *which, const char *value_text) } else if (strcmp(which, "gap") == 0 && parse_u32(value_text, 20u, 500u, &value)) { g_settings.frame_gap_ms = (uint16_t)value; } else { - Serial.println(F("BLAD: parametr RF poza dozwolonym zakresem")); + Serial.println(F("ERROR: RF parameter out of the allowed range")); return; } app_save_and_apply(); @@ -199,7 +199,7 @@ static void handle_line(char *text) app_print_frame(wheel); } } else { - Serial.println(F("BLAD: hex [1-4|all]")); + Serial.println(F("ERROR: hex [1-4|all]")); } } else if (strcmp(cmd, "send") == 0) { cmd_send(arg1); @@ -208,7 +208,7 @@ static void handle_line(char *text) } else if (strcmp(cmd, "mode") == 0) { cmd_mode(arg1, arg2); } else if (strcmp(cmd, "next") == 0) { - Serial.println(g_app->next_wheel(millis()) ? F("OK") : F("BLAD: tylko LEARN/SINGLE")); + Serial.println(g_app->next_wheel(millis()) ? F("OK") : F("ERROR: LEARN/SINGLE only")); } else if (strcmp(cmd, "id") == 0) { cmd_id(arg1, arg2); } else if (strcmp(cmd, "ids") == 0 && arg1 != NULL && strcmp(arg1, "new") == 0) { @@ -222,7 +222,7 @@ static void handle_line(char *text) cmd_rf(arg1, arg2); } else if (strcmp(cmd, "flags") == 0) { if (!parse_u32(arg1, 0u, 0xFFFFFFFFu, &value, 16)) { - Serial.println(F("BLAD: flags HEX")); + Serial.println(F("ERROR: flags HEX")); return; } g_settings.flags = value; @@ -238,13 +238,13 @@ static void handle_line(char *text) } else if (strcmp(cmd, "stay") == 0) { value = 60u; if (arg1 != NULL && !parse_u32(arg1, 1u, 3600u, &value)) { - Serial.println(F("BLAD: stay 1-3600")); + Serial.println(F("ERROR: stay 1-3600")); return; } app_stay_awake(value * 1000u); Serial.println(F("OK")); } else { - Serial.println(F("Nieznana komenda; help")); + Serial.println(F("Unknown command; help")); } } @@ -260,7 +260,7 @@ void console_poll(void) char c = (char)Serial.read(); if (c == '\r' || c == '\n') { if (line_overflow) { - Serial.println(F("BLAD: linia za dluga")); + Serial.println(F("ERROR: line too long")); } else if (line_len > 0u) { line[line_len] = '\0'; handle_line(line); diff --git a/src/console.h b/src/console.h index 2c18808..64ceb25 100644 --- a/src/console.h +++ b/src/console.h @@ -1,5 +1,5 @@ /* - * console.h - debugowa konsola szeregowa (bez String, stalobuforowa) + * console.h - debug serial console (no String, fixed buffer) */ #ifndef TPMS_CONSOLE_H #define TPMS_CONSOLE_H @@ -9,7 +9,7 @@ extern "C" { #endif void console_init(void); -void console_poll(void); // nieblokujaca obsluga linii - wywolywac w petli +void console_poll(void); // non-blocking line handling - call in the loop #ifdef __cplusplus } diff --git a/src/main.cpp b/src/main.cpp index 653c6fa..c56546a 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -1,4 +1,4 @@ -/* Symulator diagnostyczny TPMS. Sztuczne cisnienie moze ukryc usterke opony. */ +/* TPMS diagnostic simulator. Synthetic pressure can mask a tyre fault. */ #include #include #include @@ -19,8 +19,8 @@ static const char *const WHEEL_NAMES[WHEEL_COUNT] = {"FL", "FR", "RR", "RL"}; static uint32_t stay_awake_until; static bool request_sleep; static uint32_t supply_mv; -/* Mikrodrzemki: czas przespany od ostatniego cyklu TX i dlugosc ostatniego - * kawalka snu przetrwaja deep sleep w pamieci RTC (kasowane przez power-on). */ +/* Micro-naps: time slept since the last TX cycle and the length of the last + * sleep slice survive deep sleep in RTC memory (cleared by power-on). */ RTC_DATA_ATTR static uint32_t slept_ms; RTC_DATA_ATTR static uint32_t last_slice_ms; #if PIN_LF_TRIGGER >= 0 @@ -79,13 +79,13 @@ void app_request_sleep(void) bool app_save_and_apply(void) { if (!settings_store_save()) { - Serial.println(F("BLAD: nie zapisano NVS (walidacja lub zapis)")); + Serial.println(F("ERROR: NVS not saved (validation or write)")); return false; } if (!radio_init(&g_settings)) { - Serial.println(F("OSTRZEZENIE: zapisano, ale CC1101 nie odpowiada")); + Serial.println(F("WARNING: saved, but the CC1101 does not respond")); } - Serial.println(F("OK: zapisano w NVS")); + Serial.println(F("OK: saved in NVS")); return true; } @@ -101,7 +101,7 @@ void app_print_frame(uint8_t wheel) g_settings.flags) || !tpms_build_payload(payload, s.id, s.pressure_kpa10, (int8_t)s.temp_c, g_settings.flags)) { - Serial.println(F("BLAD: nieprawidlowa konfiguracja ramki")); + Serial.println(F("ERROR: invalid frame configuration")); return; } Serial.printf("%s payload:", WHEEL_NAMES[wheel]); @@ -135,7 +135,7 @@ void app_print_info(void) (unsigned long)g_settings.normal_interval_s, (unsigned long)g_settings.ignition_interval_s, (unsigned long)g_settings.parking_interval_s); - Serial.printf("Vcc=%u mV (nie zmienia flag TPMS)\n", (unsigned)supply_mv); + Serial.printf("Vcc=%u mV (does not change TPMS flags)\n", (unsigned)supply_mv); } static void sync_ui(void) @@ -177,8 +177,8 @@ static void go_sleep(void) app_stay_awake(500u); return; } - /* Mikrodrzemka: reszta okresu po czasie boot+okno, zeby migniecia LED - * wypadaly co NAP_PERIOD_MS niezaleznie od dlugosci budzenia. */ + /* Micro-nap: the rest of the period after boot time + window, so that + * LED blinks land on NAP_PERIOD_MS regardless of awake duration. */ uint32_t awake_ms = millis(); uint32_t slice_ms = NAP_PERIOD_MS; if (awake_ms + NAP_MIN_SLEEP_MS < NAP_PERIOD_MS) { @@ -210,18 +210,18 @@ void setup(void) esp_sleep_wakeup_cause_t cause = esp_sleep_get_wakeup_cause(); #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP - /* Chipy z GPIO wakeup w deep sleep (np. ESP32-C3). */ + /* Chips with GPIO wakeup in deep sleep (e.g. ESP32-C3). */ bool pin_wake = cause == ESP_SLEEP_WAKEUP_GPIO; #else - /* ESP32-S2: budzenie z pinow RTC zglasza EXT1. */ + /* ESP32-S2: waking from RTC pins raises EXT1. */ bool pin_wake = cause == ESP_SLEEP_WAKEUP_EXT1; #endif bool timer_wake = cause == ESP_SLEEP_WAKEUP_TIMER; if (timer_wake) { slept_ms += last_slice_ms; } - /* TX co interwal: power-on, budzenie po przespaniu calego cyklu albo - * wyczerpany licznik snu. Budzenie przyciskiem nie nadaje (jak wczesniej). */ + /* TX on the interval: power-on, wake after sleeping the whole cycle, or + * an exhausted sleep counter. A button wake does not transmit (as before). */ uint32_t interval_ms = g_app->interval_s(ignition_on()) * 1000u; bool transmit = !pin_wake && (!timer_wake || slept_ms >= interval_ms); bool quick_nap = timer_wake && !transmit; @@ -232,15 +232,15 @@ void setup(void) bool radio_ready = radio_init(&g_settings); if (!quick_nap) { supply_mv = power_read_mv(); - Serial.printf("\nTPMS DIAG FW %s - DANE SZTUCZNE, NIE DO JAZDY\n", FW_VERSION); - Serial.printf("NVS: %s; dostep=%s\n", + Serial.printf("\nTPMS DIAG FW %s - SYNTHETIC DATA, NOT FOR ROAD USE\n", FW_VERSION); + Serial.printf("NVS: %s; access=%s\n", settings_load_result_text(settings_store_last_load()), - settings_store_available() ? "tak" : "nie"); + settings_store_available() ? "yes" : "no"); if (!radio_ready) { - Serial.println(F("BLAD: brak CC1101; sprawdz 3V3/SPI")); + Serial.println(F("ERROR: no CC1101; check 3V3/SPI")); } if (power_low_battery(supply_mv)) { - Serial.println(F("OSTRZEZENIE: niskie zasilanie emulatora")); + Serial.println(F("WARNING: emulator supply low")); } } @@ -258,14 +258,14 @@ void setup(void) g_app->send_current(); } #endif - /* Okna: power-on/przycisk/LF = konsola 10 s; budzenie timera = od razu - * sen po TX, a mikrodrzemka tylko na widoczne migniecie LED. */ + /* Windows: power-on/button/LF = 10 s console; timer wake = straight to + * sleep after TX, the micro-nap only for a visible LED blink. */ stay_awake_until = millis() + (timer_wake ? (transmit ? 0u : NAP_AWAKE_MS) : BOOT_STAY_AWAKE_MS); sync_ui(); if (!quick_nap) { app_print_info(); - Serial.println(F("gotowy; help = komendy; stay 60 = konsola 60 s")); + Serial.println(F("ready; help = commands; stay 60 = 60 s console")); } } @@ -281,8 +281,8 @@ void loop(void) default: break; } if (ev != UI_EV_NONE) { - /* Kazdy gest = okno konsoli 10 s (POWER.md), takze po wyjsciu - * z LEARN/SINGLE - urzadzenie nie zasypia natychmiast po przycisku. */ + /* Every gesture = a 10 s console window (POWER.md), also when leaving + * LEARN/SINGLE - the device does not fall asleep right after a button. */ app_stay_awake(BOOT_STAY_AWAKE_MS); } console_poll(); diff --git a/src/parse.cpp b/src/parse.cpp index a10271f..88dfe36 100644 --- a/src/parse.cpp +++ b/src/parse.cpp @@ -43,7 +43,7 @@ bool parse_float(const char *text, float lo, float hi, float *out) errno = 0; char *end = NULL; float value = strtof(text, &end); - /* Odwrocone porownanie odrzuca tez NaN (obie strony falszywe). */ + /* Inverted comparison also rejects NaN (both sides false). */ if (errno != 0 || end == text || *end != '\0' || !(value >= lo && value <= hi)) { return false; diff --git a/src/parse.h b/src/parse.h index 441c322..6bd10f0 100644 --- a/src/parse.h +++ b/src/parse.h @@ -1,4 +1,4 @@ -/* Parsowanie argumentow konsoli; modul przenosny (testy native). */ +/* Console argument parsing; portable module (native tests). */ #ifndef TPMS_PARSE_H #define TPMS_PARSE_H @@ -12,7 +12,7 @@ extern "C" { bool parse_u32(const char *text, uint32_t lo, uint32_t hi, uint32_t *out, int base = 10); bool parse_i32(const char *text, int32_t lo, int32_t hi, int32_t *out); -/* Odrzuca NaN i nieskonczonosc; zakres domkniety [lo, hi]. */ +/* Rejects NaN and infinity; closed range [lo, hi]. */ bool parse_float(const char *text, float lo, float hi, float *out); #ifdef __cplusplus diff --git a/src/power.cpp b/src/power.cpp index 22adcc1..61770ae 100644 --- a/src/power.cpp +++ b/src/power.cpp @@ -1,4 +1,4 @@ -/* Zasilanie i deep sleep. Stan zasilania NIE zmienia pol protokolu TPMS. */ +/* Power and deep sleep. Supply state does NOT change TPMS protocol fields. */ #include #include #include @@ -19,7 +19,7 @@ void power_init(void) gpio_hold_dis((gpio_num_t)PIN_CC1101_SCK); gpio_hold_dis((gpio_num_t)PIN_CC1101_MOSI); #if SOC_BT_SUPPORTED - /* ESP32-S2 nie ma radia Bluetooth; btStop istnieje tylko na chipach z BT. */ + /* ESP32-S2 has no Bluetooth radio; btStop only exists on chips with BT. */ btStop(); #endif #if PIN_VBAT_ADC >= 0 @@ -57,18 +57,18 @@ void power_deep_sleep(uint32_t ms) gpio_deep_sleep_hold_en(); esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_ALL); - /* PARKING_SHUTDOWN nie istnieje: kazdy sen ma budzik i nie mozna - * zatrzymac urzadzenia do czasu recznego wybudzenia. Dolny prog - * gwarantuje budzik takze dla mikrodrzemek. */ + /* PARKING_SHUTDOWN does not exist: every sleep has an RTC alarm and the + * device cannot be stopped until a manual wake. The lower bound also + * guarantees an alarm for micro-naps. */ if (ms < NAP_MIN_SLEEP_MS) { ms = NAP_MIN_SLEEP_MS; } esp_sleep_enable_timer_wakeup((uint64_t)ms * 1000ULL); #if PIN_BUTTON >= 0 || PIN_LF_TRIGGER >= 0 - /* Budzenie z pinow RTC (na ESP32-S2: GPIO0-21). Oba wejscia sa aktywne - * nisko, wiec moga wspoldzielic jeden tryb. ESP32-S2 nie obsluguje - * GPIO wakeup w deep sleep - uzywa EXT1 ANY_LOW. */ + /* Waking from RTC pins (on ESP32-S2: GPIO0-21). Both inputs are active + * low, so they can share one mode. ESP32-S2 does not support GPIO wakeup + * in deep sleep - it uses EXT1 ANY_LOW. */ uint64_t wake_mask = 0; #if PIN_BUTTON >= 0 wake_mask |= 1ULL << PIN_BUTTON; @@ -77,10 +77,10 @@ void power_deep_sleep(uint32_t ms) wake_mask |= 1ULL << PIN_LF_TRIGGER; #endif #if SOC_RTCIO_INPUT_OUTPUT_SUPPORTED - /* Cyfrowe pull-up/pull-down (pinMode) nie dzialaja w deep sleep, gdy - * domena RTC_PERIPH jest wylaczona. Bez pociagniec RTC piny budzenia - * plywaja i EXT1 moze budzic losowo; konfigurujemy je tu i utrzymujemy - * mechanizmem HOLD (wg ESP-IDF sleep_modes dla EXT1). */ + /* Digital pull-up/pull-down (pinMode) does not work in deep sleep while + * the RTC_PERIPH domain is off. Without RTC pulls the wake pins float and + * EXT1 can wake randomly; we configure them here and keep them with the + * HOLD mechanism (per ESP-IDF sleep_modes for EXT1). */ #if PIN_BUTTON >= 0 rtc_gpio_init((gpio_num_t)PIN_BUTTON); #if BTN_ACTIVE_LEVEL == 0 diff --git a/src/power.h b/src/power.h index 55608b5..a97b864 100644 --- a/src/power.h +++ b/src/power.h @@ -6,7 +6,7 @@ void power_init(void); uint32_t power_read_mv(void); -bool power_low_battery(uint32_t mv); /* tylko ostrzezenie o zasilaniu emulatora */ -void power_deep_sleep(uint32_t ms); /* zawsze ma budzik RTC; nie wraca */ +bool power_low_battery(uint32_t mv); /* only a warning about the emulator supply */ +void power_deep_sleep(uint32_t ms); /* always has an RTC alarm; does not return */ #endif diff --git a/src/radio.cpp b/src/radio.cpp index bb10394..e7af1b1 100644 --- a/src/radio.cpp +++ b/src/radio.cpp @@ -1,4 +1,4 @@ -/* CC1101: surowe 30 bajtow Manchester w fixed-length FIFO, bez wstawek HW. */ +/* CC1101: raw 30 Manchester bytes into the fixed-length FIFO, no HW extras. */ #include #include #include @@ -30,13 +30,13 @@ bool radio_init(const settings_t *cfg) } ELECHOUSE_cc1101.setCCMode(1); - ELECHOUSE_cc1101.setModulation(2); /* ASK/OOK; brak profilu FSK. */ + ELECHOUSE_cc1101.setModulation(2); /* ASK/OOK; no FSK profile. */ ELECHOUSE_cc1101.setMHZ(cfg->frequency_mhz); ELECHOUSE_cc1101.setDRate(1000.0f / (float)TPMS_CHIP_US); ELECHOUSE_cc1101.setPA(cfg->tx_power_dbm); ELECHOUSE_cc1101.setChannel(0); - /* SYNC_MODE=0: packet engine nie dodaje preambuly ani slowa sync. */ + /* SYNC_MODE=0: the packet engine adds no preamble or sync word. */ ELECHOUSE_cc1101.setSyncMode(0); ELECHOUSE_cc1101.setPRE(0); ELECHOUSE_cc1101.setAdrChk(0); @@ -66,8 +66,8 @@ bool radio_send_frame(const uint8_t *buf, uint8_t len) ELECHOUSE_cc1101.SpiWriteBurstReg(CC1101_TXFIFO, (uint8_t *)buf, len); ELECHOUSE_cc1101.SpiStrobe(CC1101_STX); - /* Czekamy na MARCSTATE, nie na samo TXBYTES=0: ostatni bajt moze byc - * jeszcze w rejestrze przesuwnym. Limit obejmuje start i pelny ogon. */ + /* We wait for MARCSTATE, not just TXBYTES=0: the last byte may still be + * in the shift register. The limit covers the start and the full tail. */ const uint32_t timeout_us = (uint32_t)len * 8u * TPMS_CHIP_US + 10000u; const uint32_t start = micros(); bool finished = false; @@ -78,7 +78,7 @@ bool radio_send_frame(const uint8_t *buf, uint8_t len) underflow = true; break; } - if (state == 0x01u) { /* IDLE po automatycznym zakonczeniu pakietu */ + if (state == 0x01u) { /* IDLE after the automatic end of the packet */ finished = true; break; } diff --git a/src/settings.cpp b/src/settings.cpp index c25c6a7..70d837c 100644 --- a/src/settings.cpp +++ b/src/settings.cpp @@ -160,13 +160,13 @@ const char *settings_load_result_text(settings_load_result_t result) { switch (result) { case SETTINGS_LOAD_OK: return "OK"; - case SETTINGS_LOAD_EMPTY: return "pusta konfiguracja"; - case SETTINGS_LOAD_BAD_MAGIC: return "nieprawidlowy magic"; - case SETTINGS_LOAD_BAD_VERSION: return "nieobslugiwana wersja"; - case SETTINGS_LOAD_BAD_SIZE: return "nieprawidlowy rozmiar"; - case SETTINGS_LOAD_BAD_CRC: return "blad CRC"; - case SETTINGS_LOAD_INVALID: return "nieprawidlowe wartosci"; - case SETTINGS_LOAD_IO_ERROR: return "blad NVS"; - default: return "nieznany blad"; + case SETTINGS_LOAD_EMPTY: return "empty configuration"; + case SETTINGS_LOAD_BAD_MAGIC: return "bad magic"; + case SETTINGS_LOAD_BAD_VERSION: return "unsupported version"; + case SETTINGS_LOAD_BAD_SIZE: return "invalid size"; + case SETTINGS_LOAD_BAD_CRC: return "CRC error"; + case SETTINGS_LOAD_INVALID: return "invalid values"; + case SETTINGS_LOAD_IO_ERROR: return "NVS error"; + default: return "unknown error"; } } diff --git a/src/settings.h b/src/settings.h index 9472fa9..6e14560 100644 --- a/src/settings.h +++ b/src/settings.h @@ -1,4 +1,4 @@ -/* Trwala konfiguracja uzytkownika; modul niezalezny od Arduino. */ +/* Persistent user configuration; module independent of Arduino. */ #ifndef TPMS_SETTINGS_H #define TPMS_SETTINGS_H diff --git a/src/settings_store.cpp b/src/settings_store.cpp index ef2cc5a..c2ba199 100644 --- a/src/settings_store.cpp +++ b/src/settings_store.cpp @@ -33,7 +33,7 @@ void settings_store_begin() } if (last_load != SETTINGS_LOAD_OK) { settings_defaults(&g_settings); - /* Odzyskiwanie po uszkodzeniu: zapisz spojne domyslne. */ + /* Recovery from corruption: save consistent defaults. */ settings_store_save(); } } diff --git a/src/tpms_frame.cpp b/src/tpms_frame.cpp index ecc0351..4c89143 100644 --- a/src/tpms_frame.cpp +++ b/src/tpms_frame.cpp @@ -1,4 +1,4 @@ -/* Generator ramek EG53MA4. Sztuczne dane wylacznie do diagnostyki. */ +/* EG53MA4 frame generator. Synthetic data for diagnostics only. */ #include #include "settings.h" @@ -12,7 +12,7 @@ static void put_bit(uint8_t *buf, unsigned *nbits, unsigned value) ++(*nbits); } -/* Polaryzacja potwierdzona nagraniami i rtl_433 OOK_MC_ZEROBIT: 0=01, 1=10. */ +/* Polarity confirmed by captures and rtl_433 OOK_MC_ZEROBIT: 0=01, 1=10. */ static void put_cell(uint8_t *buf, unsigned *nbits, unsigned bit) { put_bit(buf, nbits, bit != 0u ? 1u : 0u); @@ -68,7 +68,7 @@ bool tpms_build_frame(uint8_t out[TPMS_TX_BYTES], uint32_t id, memset(out, 0, TPMS_TX_BYTES); unsigned nbits = 0; - put_bit(out, &nbits, 1u); /* chip startowy */ + put_bit(out, &nbits, 1u); /* starting chip */ for (unsigned i = 0; i < TPMS_SYNC_BITS - 1u; ++i) { put_cell(out, &nbits, 0u); } diff --git a/src/tpms_frame.h b/src/tpms_frame.h index 09e60dc..db6d82b 100644 --- a/src/tpms_frame.h +++ b/src/tpms_frame.h @@ -1,4 +1,4 @@ -/* Schrader EG53MA4: 40 bitow sync + 80 bitow danych, OOK Manchester. */ +/* Schrader EG53MA4: 40 sync bits + 80 data bits, OOK Manchester. */ #ifndef TPMS_FRAME_H #define TPMS_FRAME_H @@ -15,20 +15,21 @@ extern "C" { #define TPMS_TX_BYTES 30 #define TPMS_TX_CHIPS (TPMS_TX_BYTES * 8) -/* Kalibracja pola P: tyle setnych kPa przypada na jeden bit bajtu P. - * Skala rtl_433 (250 = 2,5 kPa/bit) nie jest potwierdzona nagraniami - * (wszystkie maja P=0), a pomiar z auta: 260 kPa -> 284 kPa na wyswietlaczu - * przy P=104, wiec korekta skalujaca 2,73 kPa/bit daje P=95 dla 260 kPa. - * Potwierdzone z autem: 260 kPa -> 260 kPa na wyswietlaczu (docs/AUDIT.md) - - * zmienic tez PRESSURE_KPA100_PER_RAW w tools/tpms_frame.py. */ +/* Calibration of the P field: how many hundredths of a kPa one bit of the + * P byte represents. The rtl_433 scale (250 = 2.5 kPa/bit) is not confirmed + * by the captures (all have P=0), while a car measurement showed + * 260 kPa -> 284 kPa on the display at P=104, so a scaling correction of + * 2.73 kPa/bit gives P=95 for 260 kPa. Confirmed with the car: + * 260 kPa -> 260 kPa on the display (docs/AUDIT.md) - + * also change PRESSURE_KPA100_PER_RAW in tools/tpms_frame.py. */ #define TPMS_PRESSURE_KPA100_PER_RAW 273 #ifdef __cplusplus static_assert(TPMS_TX_CHIPS == 1 + 2 * (TPMS_ROW_BITS - 1) + 1, - "Nieprawidlowa dlugosc bufora Manchester"); + "Invalid Manchester buffer length"); #endif -/* Zwraca false dla ID 0, 0xFFFFFF i wartosci spoza 24 bitow. */ +/* Returns false for ID 0, 0xFFFFFF and values outside 24 bits. */ bool tpms_build_payload(uint8_t out[TPMS_PAYLOAD_LEN], uint32_t id, uint16_t press_kpa10, int8_t temp_c, uint32_t flags); bool tpms_build_frame(uint8_t out[TPMS_TX_BYTES], uint32_t id, diff --git a/src/ui.cpp b/src/ui.cpp index 861b782..b19c4ee 100644 --- a/src/ui.cpp +++ b/src/ui.cpp @@ -1,19 +1,19 @@ /* - * ui.cpp - przycisk (gesty) i LED statusowy (nieblokujaco, bez delay()) + * ui.cpp - button (gestures) and status LED (non-blocking, no delay()) */ #include #include "config.h" #include "ui.h" -/* ---------------------------- przycisk ---------------------------- */ -/* Debounce: nowy stan surowy musi sie utrzymac BTN_DEBOUNCE_MS, zanim - * zostanie uznany za stan stabilny (kandydat + czas jego zmiany). */ +/* ---------------------------- button ---------------------------- */ +/* Debounce: the new raw state must persist for BTN_DEBOUNCE_MS before it is + * accepted as stable (candidate + the time it changed). */ -static bool btn_raw_last = false; // ostatni surowy odczyt -static uint32_t btn_raw_change = 0; // czas ostatniej zmiany surowej -static bool btn_stable = false; // stan po debounce +static bool btn_raw_last = false; // last raw reading +static uint32_t btn_raw_change = 0; // time of the last raw change +static bool btn_stable = false; // debounced state static uint32_t btn_press_start = 0; -static bool btn_long_fired = false; // bardzo dlugie zdarzenie juz wyslane +static bool btn_long_fired = false; // very long event already reported bool ui_button_down(void) { @@ -31,7 +31,7 @@ void ui_init(void) btn_raw_last = raw; btn_raw_change = now; btn_stable = raw; - btn_press_start = now; // start z wcisnietym przyciskiem = poczatek gestu + btn_press_start = now; // starting pressed = beginning of a gesture btn_long_fired = false; } @@ -42,12 +42,12 @@ ui_event_t ui_poll(void) uint32_t now = millis(); if (raw != btn_raw_last) { - /* kandydat - czekaj az stan sie utrzyma */ + /* candidate - wait until the state persists */ btn_raw_last = raw; btn_raw_change = now; } else if (raw != btn_stable && (now - btn_raw_change) >= BTN_DEBOUNCE_MS) { - btn_stable = raw; // zaakceptowany po debounce + btn_stable = raw; // accepted after debounce if (btn_stable) { btn_press_start = now; btn_long_fired = false; @@ -60,7 +60,7 @@ ui_event_t ui_poll(void) } } - /* bardzo dlugi przycisk sygnalizujemy od razu (nie czekajac na puszczenie) */ + /* very long press is signalled immediately (without waiting for release) */ if (btn_stable && !btn_long_fired && (now - btn_press_start) >= BTN_VERYLONG_MS) { btn_long_fired = true; ev = UI_EV_VERYLONG; @@ -73,7 +73,7 @@ ui_event_t ui_poll(void) static ui_pat_t led_pat = UI_PAT_OFF; static uint8_t led_blinks_left = 0; static bool led_on = false; -static bool led_series = false; // seria migniec w trakcie +static bool led_series = false; // blink series in progress static uint32_t led_next = 0; void ui_set_pattern(ui_pat_t pat) @@ -103,7 +103,7 @@ void ui_update(void) if (led_series) { if (led_on) { - /* koniec migniecia */ + /* end of a blink */ digitalWrite(PIN_LED, LED_ACTIVE_LEVEL ? LOW : HIGH); led_on = false; if (led_blinks_left > 0) { @@ -112,13 +112,13 @@ void ui_update(void) led_next = now + 90; } else if (led_blinks_left > 0) { - /* kolejne migniecie */ + /* next blink */ digitalWrite(PIN_LED, LED_ACTIVE_LEVEL ? HIGH : LOW); led_on = true; led_next = now + 90; } else { - /* koniec serii - przerwa zalezna od wzorca */ + /* end of the series - gap depends on the pattern */ led_series = false; uint32_t idle = 2000; switch (led_pat) { @@ -133,7 +133,7 @@ void ui_update(void) return; } - /* rozpoczynamy serie wg wzorca */ + /* start the series for the pattern */ if (led_pat == UI_PAT_OFF) { digitalWrite(PIN_LED, LED_ACTIVE_LEVEL ? LOW : HIGH); led_next = now + 50; diff --git a/src/ui.h b/src/ui.h index cc0da9c..a2f9dc0 100644 --- a/src/ui.h +++ b/src/ui.h @@ -1,5 +1,5 @@ /* - * ui.h - przycisk (gesty) i LED statusowy + * ui.h - button (gestures) and status LED */ #ifndef TPMS_UI_H #define TPMS_UI_H @@ -14,28 +14,28 @@ extern "C" { typedef enum { UI_EV_NONE = 0, UI_EV_SHORT, // < BTN_LONG_MS - UI_EV_LONG, // >= BTN_LONG_MS (wejscie/wyjscie LEARN) - UI_EV_VERYLONG, // >= BTN_VERYLONG_MS (wejscie/wyjscie SINGLE) + UI_EV_LONG, // >= BTN_LONG_MS (enter/exit LEARN) + UI_EV_VERYLONG, // >= BTN_VERYLONG_MS (enter/exit SINGLE) } ui_event_t; typedef enum { UI_PAT_OFF = 0, - UI_PAT_NORMAL, // 1 migniecie co 2 s - UI_PAT_LEARN, // 3 szybkie migniecia co 0.5 s - UI_PAT_SINGLE, // 2 szybkie migniecia co 0.5 s - UI_PAT_LOWBAT, // 10 szybkich migniec co 3 s + UI_PAT_NORMAL, // 1 blink every 2 s + UI_PAT_LEARN, // 3 quick blinks every 0.5 s + UI_PAT_SINGLE, // 2 quick blinks every 0.5 s + UI_PAT_LOWBAT, // 10 quick blinks every 3 s } ui_pat_t; void ui_init(void); -/* Nieblokujaca obsluga przycisku i LED - wywolywac w kazdej petli. */ +/* Non-blocking button and LED handling - call in every loop. */ ui_event_t ui_poll(void); void ui_update(void); bool ui_button_down(void); void ui_set_pattern(ui_pat_t pat); -/* Seria n szybkich migniec (np. numer kola: 1-4). */ +/* Series of n quick blinks (e.g. wheel number: 1-4). */ void ui_blink_count(uint8_t n); #ifdef __cplusplus diff --git a/test/test_app_state/test_app_state.cpp b/test/test_app_state/test_app_state.cpp index 8948f7c..4641319 100644 --- a/test/test_app_state/test_app_state.cpp +++ b/test/test_app_state/test_app_state.cpp @@ -22,7 +22,7 @@ static void test_normal_clone_ids_sends_four_wheels_and_repeats(void) { settings_t cfg; settings_defaults(&cfg); - cfg.wheels[0].id = 0x111111u; /* Clone IDs: konfiguracja bez nauki. */ + cfg.wheels[0].id = 0x111111u; /* Clone IDs: configuration without LEARN. */ FakeRadio radio; AppState app(&cfg, &radio); app.begin(0u); @@ -48,7 +48,7 @@ static void test_new_ids_learn_order_force_and_finish(void) TEST_ASSERT_EQUAL(AppMode::LEARN, app.mode()); TEST_ASSERT_EQUAL_UINT8(1u, radio.count); TEST_ASSERT_EQUAL_UINT8(WHEEL_FL, radio.wheels[0]); - TEST_ASSERT_TRUE(app.send_current()); /* wymuszenie bez zmiany kola */ + TEST_ASSERT_TRUE(app.send_current()); /* force TX without changing wheel */ TEST_ASSERT_EQUAL_UINT8(2u, radio.count); app.short_press(100u); TEST_ASSERT_EQUAL_UINT8(WHEEL_FR, app.active_wheel()); @@ -77,7 +77,7 @@ static void test_learn_period_window_and_total_timeout(void) TEST_ASSERT_EQUAL(AppMode::LEARN, app.mode()); app.tick(60000u, false); TEST_ASSERT_EQUAL(AppMode::NORMAL, app.mode()); - TEST_ASSERT_EQUAL_UINT8(3u, radio.count); /* timeout nie nadaje nowej ramki */ + TEST_ASSERT_EQUAL_UINT8(3u, radio.count); /* timeout sends no new frame */ app.set_mode(AppMode::LEARN, WHEEL_FL, 100000u); app.tick(1000000u, false); @@ -118,7 +118,7 @@ static void test_button_gestures(void) app.very_long_press(30u); TEST_ASSERT_EQUAL(AppMode::NORMAL, app.mode()); app.short_press(40u); - TEST_ASSERT_EQUAL_UINT8(6u, radio.count); /* LEARN + SINGLE + 4 koła NORMAL */ + TEST_ASSERT_EQUAL_UINT8(6u, radio.count); /* LEARN + SINGLE + 4 wheels NORMAL */ } static void test_acc_intervals_without_permanent_shutdown(void) @@ -179,7 +179,7 @@ static void test_millis_wrap_does_not_stall_learn(void) FakeRadio radio; AppState app(&cfg, &radio); app.set_mode(AppMode::LEARN, WHEEL_FL, UINT32_MAX - 1000u); - app.tick(1000u, false); /* uplynely 2001 ms po zawinieciu */ + app.tick(1000u, false); /* 2001 ms elapsed after the wrap */ TEST_ASSERT_EQUAL_UINT8(2u, radio.count); } diff --git a/test/test_parse/test_parse.cpp b/test/test_parse/test_parse.cpp index 60cc550..7236e59 100644 --- a/test/test_parse/test_parse.cpp +++ b/test/test_parse/test_parse.cpp @@ -47,8 +47,8 @@ static void test_float_ranges(void) static void test_float_rejects_nan_and_infinity(void) { - /* Regresja: NaN przechodzil stary test zakresu (obie strony falszywe), - * trafial do NVS jako cisnienie i blokowal zapis czestotliwosci RF. */ + /* Regression: NaN passed the old range test (both comparisons false), + * ended up in NVS as pressure and blocked later RF frequency saves. */ float value = 0.0f; TEST_ASSERT_FALSE(parse_float("nan", 0.0f, 637.5f, &value)); TEST_ASSERT_FALSE(parse_float("-nan", 0.0f, 637.5f, &value)); diff --git a/test/test_tpms_frame/test_tpms_frame.cpp b/test/test_tpms_frame/test_tpms_frame.cpp index 7518032..f51bea7 100644 --- a/test/test_tpms_frame/test_tpms_frame.cpp +++ b/test/test_tpms_frame/test_tpms_frame.cpp @@ -14,8 +14,8 @@ struct capture_vector_t { static void test_four_independent_capture_payloads(void) { - /* rtl_433_tests commit 1aa8c29, cztery nagrania, po 16 dekodowan. - * Wszystkie: flags=4c900070, pressure=0. Wartosci nie pochodza z generatora. */ + /* rtl_433_tests commit 1aa8c29, four captures, 16 decodes each. + * All: flags=4c900070, pressure=0. The values do not come from a generator. */ static const capture_vector_t vectors[] = { {0x2FC871u, 32, 90u, 0x0Eu}, {0x2EAAF9u, 32, 90u, 0x77u}, @@ -36,8 +36,9 @@ static void test_four_independent_capture_payloads(void) static void test_known_frame_and_pressure_temperature(void) { - /* Wektor zregenerowany po kalibracji pola P wg auta (260 kPa -> P=95); - * rownolegle do tools/tpms_frame.py. Sam kod Manchester bez zmian. */ + /* Vector regenerated after calibrating the P field against the car + * (260 kPa -> P=95); parallel to tools/tpms_frame.py. Manchester bit + * coding itself is unchanged. */ static const uint8_t expected[TPMS_TX_BYTES] = { 0xAA,0xAA,0xAA,0xAA,0xAA,0xAA,0xAA,0xAA,0xAA,0xAA, 0xCB,0x4B,0x2C,0xAA,0xAA,0xAA,0xD4,0xAA,0xB3,0x55, @@ -48,7 +49,7 @@ static void test_known_frame_and_pressure_temperature(void) TEST_ASSERT_TRUE(tpms_build_frame(frame, 0x2FC871u, 2600u, 23, 0x4C900070u)); TEST_ASSERT_EQUAL_UINT8_ARRAY(expected, frame, TPMS_TX_BYTES); TEST_ASSERT_TRUE(tpms_build_payload(payload, 0x123456u, 2600u, 23, 0x4C900070u)); - TEST_ASSERT_EQUAL_HEX8(0x5F, payload[7]); /* 260 kPa -> 95 (2,73 kPa/bit) */ + TEST_ASSERT_EQUAL_HEX8(0x5F, payload[7]); /* 260 kPa -> 95 (2.73 kPa/bit) */ TEST_ASSERT_EQUAL_UINT8(73u, payload[8]); TEST_ASSERT_EQUAL_HEX8(0x90, payload[9]); } @@ -91,14 +92,14 @@ static void test_manchester_polarity_and_negative_frames(void) uint8_t damaged[TPMS_TX_BYTES]; memcpy(damaged, frame, sizeof(frame)); - damaged[10] &= 0x3Fu; /* dwa jednakowe chipy: niedozwolony Manchester */ + damaged[10] &= 0x3Fu; /* two identical chips: invalid Manchester */ TEST_ASSERT_FALSE(decode_strict(damaged, sizeof(damaged), payload)); TEST_ASSERT_FALSE(decode_strict(frame, sizeof(frame) - 1u, payload)); memcpy(damaged, frame, sizeof(frame)); - /* Odwroc cala komorke Manchester (oba chipy) w bicie sumy kontrolnej: - * ramka pozostaje poprawnym Manchesterem, ale suma przestaje sie zgadzac, - * wiec odrzucenie nastepuje wlasnie na etapie checksum. */ + /* Invert the whole Manchester cell (both chips) of the checksum bit: + * the frame remains a valid Manchester bitstream, but the sum stops + * matching, so rejection happens exactly at the checksum stage. */ damaged[28] ^= 0x60u; TEST_ASSERT_FALSE(decode_strict(damaged, sizeof(damaged), payload)); } @@ -108,11 +109,11 @@ static void test_rounding_and_saturation(void) uint8_t p[TPMS_PAYLOAD_LEN]; TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 12u, 0, 0u)); /* 1.2 kPa */ TEST_ASSERT_EQUAL_UINT8(0u, p[7]); - TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 13u, 0, 0u)); /* prog 13.7 */ + TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 13u, 0, 0u)); /* threshold 13.7 */ TEST_ASSERT_EQUAL_UINT8(0u, p[7]); TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 14u, 0, 0u)); TEST_ASSERT_EQUAL_UINT8(1u, p[7]); - TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 2608u, -40, 0u)); /* prog 2607.2 */ + TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 2608u, -40, 0u)); /* threshold 2607.2 */ TEST_ASSERT_EQUAL_UINT8(96u, p[7]); TEST_ASSERT_EQUAL_UINT8(0u, p[8]); TEST_ASSERT_TRUE(tpms_build_payload(p, 1u, 2607u, 85, 0u)); diff --git a/tools/check_all b/tools/check_all index 1e421ef..4814335 100644 --- a/tools/check_all +++ b/tools/check_all @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Wszystkie testy mozliwe bez ESP32/CC1101/RTL-SDR/samochodu. +# All tests possible without ESP32/CC1101/RTL-SDR/car. set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$ROOT" @@ -37,4 +37,4 @@ if [ ! -x "${RTL433:-$ROOT/.cache/rtl_433/build/src/rtl_433}" ] \ fi run rtl433 bash ./tools/verify_rtl433.sh -echo "PASS: wszystkie testy bez sprzetu zakonczone sukcesem" +echo "PASS: all hardware-free tests completed successfully" diff --git a/tools/fetch_references.sh b/tools/fetch_references.sh index 780ed50..7b281fe 100644 --- a/tools/fetch_references.sh +++ b/tools/fetch_references.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Pobiera i buduje dokladnie przypiete, niezalezne referencje RF. +# Fetches and builds the exactly pinned, independent RF references. set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" DEPS="${DEPS_DIR:-$ROOT/.cache}" diff --git a/tools/flash_release.sh b/tools/flash_release.sh index 7fdf0bf..7476b6d 100644 --- a/tools/flash_release.sh +++ b/tools/flash_release.sh @@ -1,9 +1,9 @@ #!/usr/bin/env bash -# Wgrywa pelny obraz release; PORT=np. /dev/ttyACM0. Kasuje flash ESP32-S2. +# Flashes the full release image; PORT=e.g. /dev/ttyACM0. Erases the ESP32-S2 flash. set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" -PORT="${PORT:?Ustaw PORT=/dev/ttyACMX lub /dev/ttyUSBX}" +PORT="${PORT:?Set PORT=/dev/ttyACMX or /dev/ttyUSBX}" ESPTOOL="${ESPTOOL:-${PLATFORMIO_CORE_DIR:-$HOME/.platformio}/packages/tool-esptool/esptool}" IMAGE="$ROOT/artifacts/release/firmware-full.bin" -[ -f "$IMAGE" ] || { echo "Brak $IMAGE; uruchom tools/package_release.sh"; exit 1; } +[ -f "$IMAGE" ] || { echo "Missing $IMAGE; run tools/package_release.sh"; exit 1; } "$ESPTOOL" --chip esp32s2 --port "$PORT" --baud 460800 write-flash 0x0 "$IMAGE" diff --git a/tools/gen_cu8.py b/tools/gen_cu8.py index ce5e892..7f768ca 100755 --- a/tools/gen_cu8.py +++ b/tools/gen_cu8.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Synteza CU8 OOK/Manchester dla niezaleznego testu rtl_433 (bez RF).""" +"""CU8 synthesis of OOK/Manchester for an independent rtl_433 test (no RF).""" import argparse import math import os @@ -18,7 +18,7 @@ def synth(bits: str, amp: float, noise: float, rng: random.Random): for n in range(int(round(len(bits) * samples_per_chip))): chip = bits[int(n / samples_per_chip) % len(bits)] amplitude = amp if chip == "1" else 0.0 - phase += 0.1 # dowolna nośna w pasmie IQ; demodulator uzywa amplitudy + phase += 0.1 # any carrier inside the IQ band; the demodulator uses amplitude yield (amplitude * math.cos(phase) + rng.gauss(0, noise), amplitude * math.sin(phase) + rng.gauss(0, noise)) @@ -63,7 +63,7 @@ def main() -> int: output.extend(synth(bits, args.amp, args.noise, rng)) output.extend(gap) write_cu8(args.out, output) - print(f"{args.out}: {len(output) / SAMPLE_RATE:.3f} s, {args.frames} ramek") + print(f"{args.out}: {len(output) / SAMPLE_RATE:.3f} s, {args.frames} frames") return 0 diff --git a/tools/package_release.sh b/tools/package_release.sh index 5260876..35c3b5f 100644 --- a/tools/package_release.sh +++ b/tools/package_release.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Buduje obrazy ESP32-S2 i pelny obraz 4 MB oraz manifest SHA-256. +# Builds the ESP32-S2 images, the full 4 MB image and the SHA-256 manifest. set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" cd "$ROOT" @@ -26,13 +26,13 @@ cp "$BOOT_APP0" "$OUT/boot_app0.bin" firmware-full.bin firmware.elf > SHA256SUMS ) cat > "$OUT/BUILD-INFO.txt" <<'EOF' -Wersja: 2.0.0-rc.1 (release candidate, bez HIL) +Version: 2.0.0-rc.1 (release candidate, no HIL) PlatformIO: 6.1.18 -Platforma: espressif32 8.0.0, ESP32-S2-MINI ESP32-S2FN4R2 (lolin_s2_mini) +Platform: espressif32 8.0.0, ESP32-S2-MINI ESP32-S2FN4R2 (lolin_s2_mini) CC1101: de6757ef633b3e626dae5c7835cdb66ab53f9a1d -Adresy: 0x1000 bootloader, 0x8000 partitions, 0xe000 boot_app0, 0x10000 firmware -Flash: dio, 80 MHz, 4 MB (zgodne z board manifest lolin_s2_mini) -Pelny obraz firmware-full.bin: flash od 0x0. +Addresses: 0x1000 bootloader, 0x8000 partitions, 0xe000 boot_app0, 0x10000 firmware +Flash: dio, 80 MHz, 4 MB (consistent with the lolin_s2_mini board manifest) +Full image firmware-full.bin: flash from 0x0. EOF cat "$OUT/BUILD-INFO.txt" cat "$OUT/SHA256SUMS" diff --git a/tools/tpms_frame.py b/tools/tpms_frame.py index d56ac8c..0aca81f 100755 --- a/tools/tpms_frame.py +++ b/tools/tpms_frame.py @@ -1,9 +1,9 @@ #!/usr/bin/env python3 -"""Niezalezny model ramki EG53MA4 i testy pomocnicze (OOK/Manchester). +"""Independent EG53MA4 frame model and auxiliary tests (OOK/Manchester). -Referencje: rtl_433 commit 406f9a33550a2b6b3d0d8a8a486417ce5b3f13ab, +References: rtl_433 commit 406f9a33550a2b6b3d0d8a8a486417ce5b3f13ab, rtl_433_tests commit 1aa8c29d6b9383739d1aeed495dbc5069b704392. -Narzedzie generuje sztuczne dane wylacznie do diagnostyki. +The tool generates synthetic data for diagnostics only. """ import argparse import math @@ -14,19 +14,19 @@ SYNC_BITS = 40 TX_BYTES = 30 DEFAULT_FLAGS = 0x4C900070 -# Kalibracja pola P (patrz docs/AUDIT.md): tyle setnych kPa przypada na jeden -# bit bajtu P. Skala rtl_433 (250 = 2,5 kPa/bit) nie jest potwierdzona -# nagraniami (wszystkie maja P=0), a pomiar z auta: 260 kPa -> 284 kPa na -# wyswietlaczu przy P=104 => korekta skalujaca 2,73 kPa/bit (P=95 dla 260). -# Potwierdzone z autem: 260 kPa -> 260 kPa - zmienic tez -# TPMS_PRESSURE_KPA100_PER_RAW w src/tpms_frame.h. +# Calibration of the P field (see docs/AUDIT.md): how many hundredths of a kPa +# one bit of the P byte represents. The rtl_433 scale (250 = 2.5 kPa/bit) is not +# confirmed by the captures (all have P=0), while a car measurement showed +# 260 kPa -> 284 kPa on the display at P=104 => a scaling correction of +# 2.73 kPa/bit (P=95 for 260). Confirmed with the car: 260 kPa -> 260 kPa - +# also change TPMS_PRESSURE_KPA100_PER_RAW in src/tpms_frame.h. PRESSURE_KPA100_PER_RAW = 273 def press_raw(pressure_kpa: float) -> int: kpa10 = int(math.floor(pressure_kpa * 10.0 + 0.5)) if not 0 <= kpa10 <= 6375: - raise ValueError("cisnienie musi byc w zakresie 0..637.5 kPa") + raise ValueError("pressure must be in the range 0..637.5 kPa") return (kpa10 * 10 + PRESSURE_KPA100_PER_RAW // 2) // PRESSURE_KPA100_PER_RAW @@ -41,20 +41,21 @@ def cell(bit: int) -> str: def build_row(sensor_id: int, pressure_kpa: float, temp_c: float, flags: int = DEFAULT_FLAGS) -> str: if not valid_id(sensor_id): - raise ValueError("ID musi byc w zakresie 000001..FFFFFE") + raise ValueError("ID must be in the range 000001..FFFFFE") if not 0 <= flags <= 0xFFFFFFFF: - raise ValueError("flags musza miec 32 bity") + raise ValueError("flags must be 32-bit") kpa10 = int(math.floor(pressure_kpa * 10.0 + 0.5)) if not 0 <= kpa10 <= 6375: - raise ValueError("cisnienie musi byc w zakresie 0..637.5 kPa") + raise ValueError("pressure must be in the range 0..637.5 kPa") press_byte = press_raw(pressure_kpa) tc = int(math.floor(temp_c + 0.5)) if not -40 <= tc <= 85: - raise ValueError("temperatura musi byc w zakresie -40..85 C") + raise ValueError("temperature must be in the range -40..85 C") num = 9 * tc + 160 temp_f = (num + 2) // 5 if num >= 0 else -((-num + 2) // 5) - # Saturacja zgodna z tpms_frame.cpp: bez niej temperatura <= -19 C daje - # ujemny bajt i psuje ramke (roznica miedzy modelem Pythona a firmware). + # Saturation consistent with tpms_frame.cpp: without it a temperature + # <= -19 C produces a negative byte and corrupts the frame (difference + # between the Python model and the firmware). temp_f = max(0, min(255, temp_f)) payload = [flags >> 24, (flags >> 16) & 255, (flags >> 8) & 255, flags & 255, sensor_id >> 16, (sensor_id >> 8) & 255, @@ -65,14 +66,14 @@ def build_row(sensor_id: int, pressure_kpa: float, temp_c: float, def build_tx_bits(row: str) -> str: if len(row) != FRAME_BITS: - raise ValueError("ramka musi miec 120 bitow") + raise ValueError("frame must have 120 bits") bits = "1" + "".join(cell(int(bit)) for bit in row[1:]) return bits.ljust(TX_BYTES * 8, "0") def tx_bytes(bits: str) -> bytes: if len(bits) != TX_BYTES * 8: - raise ValueError("bufor nadawczy musi miec 30 bajtow") + raise ValueError("TX buffer must have 30 bytes") return bytes(int(bits[i:i + 8], 2) for i in range(0, len(bits), 8)) @@ -83,9 +84,9 @@ def decode_row(row: str): for i in range(10)] return {"flags": int.from_bytes(bytes(data[:4]), "big"), "id": int.from_bytes(bytes(data[4:7]), "big"), - # 2,5 kPa/bit to skala dekodera rtl_433 (niepotwierdzona); firmware - # koryguje ja stala PRESSURE_KPA100_PER_RAW, wiec wartosc ponizej - # != cisnieniu zadanemu w konsoli. + # 2.5 kPa/bit is the rtl_433 decoder scale (unconfirmed); the + # firmware corrects it with the PRESSURE_KPA100_PER_RAW constant, + # so the value below != the pressure set in the console. "pressure_kPa": data[7] * 2.5, "temperature_F": data[8], "checksum_ok": sum(data[:9]) & 255 == data[9], "bytes": data} @@ -95,19 +96,20 @@ def self_test() -> int: row = build_row(0x2FC871, 0, 32) got = decode_row(row)["bytes"] if got != expected: - print(f"FAIL: nagranie gfile001: {got} != {expected}") + print(f"FAIL: capture gfile001: {got} != {expected}") return 1 - # Regresja: saturacja temperatury zgodna z firmware (zakres -40..85 C). + # Regression: temperature saturation consistent with the firmware + # (range -40..85 C). for tc, want in ((-40, 0), (-19, 0), (-18, 0), (23, 73), (85, 185)): byte = decode_row(build_row(0x2FC871, 0, tc))["bytes"][8] if byte != want: - print(f"FAIL: temperatura {tc} C: {byte} != {want}") + print(f"FAIL: temperature {tc} C: {byte} != {want}") return 1 - # Regresja kalibracji pola P (punkt pomiarowy z auta: 260 kPa -> P=95). + # Regression of the P field calibration (car measurement point: 260 kPa -> P=95). for kpa, want in ((0, 0), (1.2, 0), (1.4, 1), (260.0, 95), (637.5, 234)): byte = press_raw(kpa) if byte != want: - print(f"FAIL: cisnienie {kpa} kPa: {byte} != {want}") + print(f"FAIL: pressure {kpa} kPa: {byte} != {want}") return 1 import random rng = random.Random(42) @@ -119,7 +121,7 @@ def self_test() -> int: if not decoded["checksum_ok"] or decoded["id"] != sensor_id: print("FAIL: round trip") return 1 - print("self-test: OK (nagranie + 500 ramek)") + print("self-test: OK (capture + 500 frames)") return 0 diff --git a/tools/verify_rtl433.py b/tools/verify_rtl433.py index e4ffb96..ec2eb4d 100644 --- a/tools/verify_rtl433.py +++ b/tools/verify_rtl433.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Walidacja prawdziwych i syntetycznych CU8 przez przypiety rtl_433.""" +"""Validation of real and synthetic CU8 with the pinned rtl_433.""" import argparse import json import pathlib @@ -50,7 +50,7 @@ def main() -> int: for filename, (sensor_id, temp_f) in EXPECTED.items(): capture = args.reference_dir / filename - if not require(capture.is_file(), f"brak {capture}", failures): + if not require(capture.is_file(), f"missing {capture}", failures): continue status, records, raw = decode(args.rtl433, capture) valid = status == 0 and len(records) == 16 and all( @@ -58,13 +58,13 @@ def main() -> int: and record.get("pressure_kPa") == 0.0 and record.get("temperature_F") == temp_f and record.get("mic") == "CHECKSUM" for record in records) - require(valid, f"{filename}: niezgodne rekordy\n{raw}", failures) - print(f"{'OK' if valid else 'FAIL'} referencja {filename}: " + require(valid, f"{filename}: mismatched records\n{raw}", failures) + print(f"{'OK' if valid else 'FAIL'} reference {filename}: " f"{len(records)}/16, id={sensor_id}, flags=4c900070") - # rtl_433 liczy pole P skala 2,5 kPa/bit (niepotwierdzona); firmware - # koryguje ja stala PRESSURE_KPA100_PER_RAW, wiec oczekiwana wartosc - # z rtl_433 to surowy bajt P * 2.5, a nie zadane kPa. + # rtl_433 computes the P field on a 2.5 kPa/bit scale (unconfirmed); the + # firmware corrects it with the PRESSURE_KPA100_PER_RAW constant, so the + # expected rtl_433 value is the raw P byte * 2.5, not the requested kPa. synthetic = [("2FC871", 260, 23, 73.0), ("3495AC", 220, -5, 23.0), ("ABCDEE", 262.5, 24, 75.0)] with tempfile.TemporaryDirectory(prefix="tpms-rtl433-") as temp: @@ -82,8 +82,8 @@ def main() -> int: and record.get("temperature_F") == temp_f and record.get("flags") == "4c900070" and record.get("mic") == "CHECKSUM" for record in records) - require(valid, f"syntetyczna {sensor_id}: {raw}", failures) - print(f"{'OK' if valid else 'FAIL'} syntetyczna id={sensor_id}: " + require(valid, f"synthetic {sensor_id}: {raw}", failures) + print(f"{'OK' if valid else 'FAIL'} synthetic id={sensor_id}: " f"{len(records)} dekodowan, P={press_raw(pressure)} " f"(rtl_433: {expect_kpa:.1f} kPa z {pressure:.1f} kPa), " f"{temp_f:.1f} F") @@ -95,11 +95,11 @@ def main() -> int: check=True, capture_output=True) status, records, raw = decode(args.rtl433, capture) valid = status == 0 and not records - require(valid, f"negatywny {corruption}: blednie zdekodowano\n{raw}", failures) - print(f"{'OK' if valid else 'FAIL'} negatywny {corruption}: " + require(valid, f"negative {corruption}: decoded incorrectly\n{raw}", failures) + print(f"{'OK' if valid else 'FAIL'} negative {corruption}: " f"{len(records)} dekodowan (oczekiwano 0)") - print(f"WYNIK: {'PASS' if not failures else 'FAIL'}; bledow={len(failures)}") + print(f"RESULT: {'PASS' if not failures else 'FAIL'}; errors={len(failures)}") for failure in failures: print(" - " + failure) return 1 if failures else 0 diff --git a/tools/verify_rtl433.sh b/tools/verify_rtl433.sh index 5ce7c65..701f2c3 100755 --- a/tools/verify_rtl433.sh +++ b/tools/verify_rtl433.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Zwraca niezerowy kod przy bledzie i zapisuje czytelny raport. +# Returns a non-zero code on error and writes a readable report. set -euo pipefail ROOT="$(cd "$(dirname "$0")/.." && pwd)" RTL433="${RTL433:-$ROOT/.cache/rtl_433/build/src/rtl_433}"