HTTP API

Interfejs HTTP API umożliwia komunikację z urządzeniem TR-100E. Wszystkie ścieżki żądań rozpoczynają się od /api/. Obsługiwane są metody GET i POST.

---

Zasady ogólne

• Interfejs API przyjmuje i zwraca dane w formacie JSON (Content-Type: application/json), z wyjątkiem binarnych fragmentów aktualizacji OTA oraz odpowiedzi eksportu.
• Fragmenty aktualizacji OTA są przesyłane z nagłówkiem Content-Type: application/octet-stream.
• Punkty końcowe eksportu do formatu CSV zwracają nagłówek Content-Type: text/csv.
• Punkty końcowe eksportu do zwykłego tekstu zwracają nagłówek Content-Type: text/plain.
• Pomyślne odpowiedzi mają kod stanu 200 OK.
• W przypadku błędu zwracany jest odpowiedni kod stanu HTTP oraz obiekt JSON: { "error": "ERROR_CODE", "message": "Human readable text" }.
• Obsługiwane są trwałe połączenia HTTP.
• Maksymalny rozmiar nagłówka HTTP: 1380 bajtów.
• Maksymalny rozmiar treści żądania HTTP: 4096 bajtów.
• Maksymalny całkowity rozmiar żądania HTTP: 5476 bajtów.

Poziomy dostępu

Poziom	Opis
🟩 guest	Klient nieuwierzytelniony
🟨 user	Użytkownik standardowy
🟥 powerUser	Użytkownik zaawansowany

• Poziom guest zapewnia dostęp wyłącznie do GET /api/auth/status/, GET /api/auth/salt/, GET /api/version/ oraz POST /api/auth/login/.
• Poziom user zapewnia dostęp do standardowych punktów końcowych, a także do service/time/sync.
• Poziom powerUser zapewnia pełny dostęp do wszystkich punktów końcowych.

Wszystkie żądania POST /api/debug/*, z wyjątkiem /api/debug/display/start/ i /api/debug/display/stop/, wymagają dodatkowo trybu diagnostycznego. Tryb ten włącza się podczas uruchamiania urządzenia przez jednoczesne naciśnięcie przycisków Góra i Dół. W trybie normalnym żądania te zwracają 403 Forbidden. Ograniczenie nie dotyczy żądań GET /api/debug/*.

Autoryzacja

1. Pobierz wartość salt — GET /api/auth/salt/.
2. Zaloguj się — wyślij wartość SHA256(username + password + salt) w żądaniu POST /api/auth/login/.
3. Do wszystkich kolejnych żądań dołącz nagłówek Authorization: Bearer <token>.
4. Wyloguj się — POST /api/auth/logout/.

Uwierzytelnianie WWW używa dwóch niezależnych haseł: jednego dla poziomu user i jednego dla poziomu powerUser. Pobieranie i modyfikowanie ustawień dostępu opisano w settings-get.md i settings-set.md.

Czas

• Bezwzględne znaczniki czasu są przesyłane wyłącznie w UTC+0, w formacie ISO 8601: 2026-04-16T12:34:56Z.
• Przedziały czasu i opóźnienia są liczbami całkowitymi wyrażonymi w sekundach lub minutach.

Częściowe aktualizacje ustawień

Żądanie POST /api/settings/set/ scala ustawienia według następujących zasad:

• zapisywane są tylko podane pola;
• pominięcie pola oznacza, że jego wartość nie zostanie zmieniona;
• tablice są zastępowane w całości;
• nieznane klucze powodują błąd 400 ERROR_INVALID_VALUE.

---

Żądania GET

Ścieżka	Przeznaczenie	Dostęp
/api/version/	Identyfikacja urządzenia i wersja oprogramowania sprzętowego	🟩 guest
/api/auth/status/	Bieżący poziom dostępu dla danego żądania	🟩 guest
/api/auth/salt/	Pobranie wartości salt używanej do haszowania hasła	🟩 guest
/api/state/get/?...	Migawka stanu urządzenia podczas pracy, według grupy (device, network, relays, leds, protection, recorder, channels, log, ntp, httpd, modbus, wireguard)	🟨 user
/api/settings/get/?...	Pobranie ustawień według grupy	🟨 user
/api/reference/sensor-types/	Lista obsługiwanych typów czujników	🟨 user
/api/history/temperature/info/	Metadane okna historii bieżącej	🟨 user
/api/history/temperature/samples/?...	Bieżąca historia temperatury dla wszystkich kanałów	🟨 user
/api/recorder/info/	Metadane rejestratora	🟨 user
/api/recorder/records/?...	Zarchiwizowane wpisy rejestratora	🟨 user
/api/recorder/export.csv/	Eksport danych rejestratora do formatu CSV	🟨 user
/api/log/info/	Podsumowanie dziennika zdarzeń	🟨 user
/api/log/events/?...	Zdarzenia zapisane w dzienniku	🟨 user
/api/log/export.log/	Eksport dziennika w formacie tekstowym	🟨 user
/api/debug/tasks/	Migawka zadań systemu RTOS	🟥 powerUser
/api/debug/heap/	Stan sterty FreeRTOS/lwIP	🟥 powerUser
/api/debug/system/	Diagnostyka systemu	🟥 powerUser
/api/debug/settings/	Stan banku ustawień przechowywanych w pamięci trwałej	🟥 powerUser
/api/debug/adc/	Surowe dane przetwornika ADC i dane pomiarowe	🟥 powerUser
/api/debug/external-storage/	Informacje o pamięci zewnętrznej	🟥 powerUser
/api/debug/external-storage/dump/	Pełny zrzut pamięci zewnętrznej	🟥 powerUser + tryb diagnostyczny
/api/debug/network/	Diagnostyka stosu sieciowego	🟥 powerUser
/api/debug/lwip-stats/	Liczniki lwIP (protokoły i pule memp)	🟥 powerUser
/api/debug/menu/	Stan menu interfejsu użytkownika	🟥 powerUser
/api/debug/keyget/	Stan przycisków fizycznych	🟥 powerUser
/api/service/firmware/upload/status/	Stan sesji przesyłania aktualizacji OTA	🟥 powerUser
/api/service/identity/get/	Bieżący stan danych identyfikacyjnych i blokady sprzętowej	🟥 powerUser
/api/service/challenge/status/	Stan weryfikacji fizycznego dostępu przez Overvis	WireGuard + 🟨 user
/api/service/calibration/report/	Ostatnio zapisany raport kalibracji; klucz sprzętowy nie jest wymagany	🟥 powerUser
/api/service/calibration/status/	Stan aktywnej sesji kalibracji i sygnał aktywności	🟥 powerUser + klucz sprzętowy

---

Żądania POST

Ścieżka	Przeznaczenie	Dostęp
/api/auth/login/	Uwierzytelnienie użytkownika	🟩 guest
/api/auth/logout/	Zakończenie sesji	🟨 user
/api/settings/set/	Częściowa aktualizacja ustawień	🟥 powerUser
/api/log/acknowledge/	Potwierdzenie wyświetlenia zdarzeń	🟨 user
/api/recorder/clear/	Wyczyszczenie rejestratora	🟥 powerUser
/api/log/clear/	Wyczyszczenie dziennika	🟥 powerUser
/api/service/settings/reset/	Przywrócenie ustawień fabrycznych	🟥 powerUser
/api/service/reboot/	Zaplanowanie ponownego uruchomienia	🟥 powerUser
/api/service/time/set/	Ustawienie czasu systemowego	🟥 powerUser
/api/service/time/sync/	Wymuszenie synchronizacji SNTP	🟨 user
/api/service/identity/set/	Aktualizacja i zapis pól identyfikacyjnych	🟥 powerUser
/api/service/challenge/set/	Ustawienie, zastąpienie lub wyzerowanie wyzwania Overvis	WireGuard + 🟨 user
/api/service/calibration/begin/	Rozpoczęcie sesji kalibracji	🟥 powerUser + klucz sprzętowy
/api/service/calibration/range/	Wybór zakresu i punktu	🟥 powerUser + klucz sprzętowy
/api/service/calibration/capture/	Zarejestrowanie czterech surowych wartości ADC i rozpoczęcie weryfikacji	🟥 powerUser + klucz sprzętowy
/api/service/calibration/commit/	Zapisanie punktów i czterech migawek jakości	🟥 powerUser + klucz sprzętowy
/api/service/calibration/finish/	Zakończenie sesji i zwolnienie toru pomiarowego	🟥 powerUser + klucz sprzętowy
/api/service/firmware/upload/begin/	Rozpoczęcie przesyłania obrazu aktualizacji OTA	🟥 powerUser
/api/service/firmware/upload/chunk/?offset=	Zapisanie fragmentu obrazu aktualizacji OTA	🟥 powerUser
/api/service/firmware/upload/finish/	Zakończenie przesyłania i weryfikacji	🟥 powerUser
/api/service/firmware/upload/discard/	Usunięcie przesłanego obrazu aktualizacji OTA i wyzerowanie sesji przesyłania	🟥 powerUser
/api/service/firmware/apply/	Zastosowanie aktualizacji OTA	🟥 powerUser
/api/debug/relay/start/	Uruchomienie testu przekaźnika	🟥 powerUser
/api/debug/relay/stop/	Zatrzymanie testu przekaźnika	🟥 powerUser
/api/debug/led/start/	Uruchomienie testu diod LED	🟥 powerUser
/api/debug/led/stop/	Zatrzymanie testu diod LED	🟥 powerUser
/api/debug/display/start/	Uruchomienie testu wyświetlacza i przejęcie nad nim sterowania	🟥 powerUser
/api/debug/display/stop/	Zatrzymanie testu wyświetlacza i zwolnienie sterowania	🟥 powerUser
/api/debug/keypress/	Symulowanie naciśnięcia przycisku	🟥 powerUser

---

Błędy i kody stanu

HTTP	błąd	Przeznaczenie
400	ERROR_INVALID_ARGUMENT, ERROR_INVALID_VALUE, ERROR_API_PARSING	Nieprawidłowe żądanie
401	ERROR_UNAUTHORIZED	Brak prawidłowego uwierzytelnienia
403	ERROR_NO_ACCESS, ERROR_WRITE_PROTECT	Niewystarczające uprawnienia
404	ERROR_NOT_FOUND	Nie znaleziono zasobu
408	ERROR_TIMEOUT	Przekroczono limit czasu operacji
429	ERROR_LOCKED	Blokada po nieudanych próbach logowania
500	ERROR, ERROR_IO	Błąd wewnętrzny
503	ERROR_NOT_READY	Podsystem nie jest gotowy
507	ERROR_NO_MEMORY	Niewystarczająca ilość pamięci

---

Dokumentacja zaktualizowana: 2026-07-30