Usługa kalibracji

Kalibracja fabryczna jest obsługiwana w ramach jednej sesji obejmującej całe urządzenie. Sesja przejmuje ścieżkę pomiarową, wygasa po 30 sekundach bezczynności i przechowuje w pamięci RAM wersję roboczą do czasu wykonania operacji commit. Pomyślne operacje status, range, capture i commit przedłużają czas trwania sesji.

Autoryzacja

• GET /api/service/calibration/report/ wymaga powerUser; klucz serwisowy nie jest wymagany.
• Operacja status i wszystkie punkty końcowe wprowadzające zmiany wymagają powerUser oraz zapisanej flagi wskazującej, że klucz serwisowy jest podłączony.
• Jeśli klucz nie jest podłączony, punkt końcowy zwraca 403 ERROR_NO_ACCESS.

Model danych

Dostępnych jest sześć niezależnych pozycji: x24_p1 (50 Ω), x24_p2 (100 Ω), x24_p3 (200 Ω), x2_p1 (500 Ω), x2_p2 (1000 Ω) i x2_p3 (2000 Ω).

Każda zapisana migawka zawiera zastosowaną tolerancję bezwzględną i surowe wartości ADC czterech kanałów. Bieżąca rezystancja oraz wartości weryfikacyjne dla aktualnej pozycji są obliczane wyłącznie na podstawie jej rezystancji wzorcowej i zarejestrowanej wartości ADC: R = referenceOhm * ADC / capturedAdc. Pola previewOhm, deltaOhm i deltaPercent są obliczane dynamicznie podczas generowania odpowiedzi. Pozostałe pozycje nie uczestniczą w obliczeniach.

Narzędzie producenta oblicza tolerancję. Podczas operacji commit oprogramowanie układowe otrzymuje dwie wartości końcowe i zapisuje je jako dane historyczne, ale nie określa, czy pomiar jest zgodny ze specyfikacją.

Bezpośrednio po rejestracji odpowiedni element captures zawiera już wszystkie pola migawki. Dopóki nie zostanie przetworzonych dziesięć nowych okien weryfikacyjnych, pola verifyAdc, previewOhm, deltaOhm i deltaPercent mają wartości zerowe. Przed operacją commit pole tolerance ma wartość null. Gotowość wyniku należy określać na podstawie stanu: ukończona migawka jest dostępna po przejściu ze stanu verify_capture do active.

Dane źródłowe ukończonej migawki nie zmieniają się do czasu ponownego zarejestrowania tej samej pozycji. Rejestracja innego punktu nie unieważnia ukończonych migawek.

---

GET /api/service/calibration/report/

Generuje najnowszy kompletny raport jakości na podstawie zapisanych pozycji kalibracji. W pamięci Flash nie jest przechowywany oddzielny obiekt raportu.

Odpowiedź 200, raport niedostępny

{
  "available": false
}

Odpowiedź available: false oznacza, że zapisany raport jest niedostępny. API nie określa przyczyny jego niedostępności.

Odpowiedź 200, raport dostępny

{
  "available": true,
  "committedAt": "2026-07-23T12:00:00Z",
  "snapshots": {
    "x2_p1": {
      "capturedAt": "2026-07-23T11:58:00Z",
      "tolerance": { "ohm": 1.875 },
      "channels": [
        {
          "channel": 0,
          "referenceOhm": 500.0,
          "capturedAdc": 123456,
          "verifyAdc": 123460,
          "previewOhm": 500.0162,
          "deltaOhm": 0.0162,
          "deltaPercent": 0.00324
        }
      ]
    }
  }
}

Pełna odpowiedź zawiera wszystkie sześć kluczy migawek oraz cztery kanały w każdej migawce. Nie ma nadrzędnej mapy tolerancji ani pól scale lub offset.

---

GET /api/service/calibration/status/

Zwraca aktywną sesję i przedłuża jej 30-sekundowy czas trwania.

Odpowiedź 200, bezczynność

{
  "state": "idle"
}

Odpowiedź 200, sesja aktywna

{
  "state": "active",
  "sessionId": "7A19C2E4",
  "activeGain": "x24",
  "activePoint": "p1",
  "committedAt": null,
  "captures": {},
  "live": [
    { "channel": 0, "filteredAdc": 123456, "resistanceOhm": 100.01 }
  ]
}

Obserwowalne stany aktywnej sesji to switching, active i verify_capture. Model wewnętrzny obejmuje również stany committing i stopping, jednak operacje zatwierdzania i kończenia są przetwarzane synchronicznie, dlatego operacja status nie zwraca tych stanów przejściowych.

Narzędzie producenta stosuje tolerancję określoną w konfiguracji dla bieżącej procedury. W niezatwierdzonych elementach captures pole tolerance ma wartość null; po operacji commit każda pozycja zawiera historyczną tolerancję podaną przez narzędzie.

Pole live[].resistanceOhm ma typ number|null: w przypadku pustej lub niekompletnej wersji roboczej rezystancja, której nie można obliczyć, jest serializowana jako null.

---

POST /api/service/calibration/begin/

Rozpoczyna pojedynczą sesję kalibracji na podstawie zapisanego zestawu punktów. Jeśli rekord w pamięci Flash nie istnieje lub jest nieprawidłowy, sesja rozpoczyna się z pustą wersją roboczą. Treść żądania nie jest używana.

Początkową aktywną pozycją jest x24_p1.

Odpowiedź 200

{
  "sessionId": "7A19C2E4"
}

Jeśli inna sesja jest już aktywna, zwraca 400 ERROR_INVALID_VALUE. Kod 503 ERROR_NOT_READY oznacza, że zadanie pomiarowe nie przyjęło polecenia.

---

POST /api/service/calibration/range/

Wybiera wzmocnienie i punkt. Po zmianie wzmocnienia sesja przechodzi w stan switching, w którym pozostaje do czasu opublikowania nowego okna pomiarowego potwierdzającego zastosowanie sprzętowej ścieżki pomiarowej.

{
  "sessionId": "7A19C2E4",
  "gain": "x24",
  "point": "p1"
}

Odpowiedź 200

{
  "state": "switching",
  "activeGain": "x24",
  "activePoint": "p1"
}

---

POST /api/service/calibration/capture/

Rejestruje bieżące okno surowych wartości ADC dla wszystkich czterech kanałów i rozpoczyna weryfikację na podstawie dziesięciu nowych okien.

{
  "sessionId": "7A19C2E4",
  "gain": "x24",
  "point": "p1",
  "referenceOhm": 1000.01
}

Odpowiedź 200

{
  "gain": "x24",
  "point": "p1",
  "capturedAt": "2026-07-23T11:58:00Z",
  "state": "verify_capture",
  "channels": [
    { "channel": 0, "referenceOhm": 1000.01, "capturedAdc": 123456 }
  ]
}

Wartość referenceOhm musi być skończoną liczbą dodatnią. Podane wzmocnienie i punkt muszą odpowiadać aktywnej pozycji.

---

POST /api/service/calibration/commit/

Zapisuje zestaw punktów oraz wszystkie sześć ukończonych, poprawnych strukturalnie migawek. Rezystancje wzorcowe i wartości ADC muszą rosnąć od p1 do p3; różnica ADC między każdą parą sąsiednich punktów musi wynosić co najmniej 5%. Przed wywołaniem punktu końcowego narzędzie producenta sprawdza, czy pomiary mieszczą się w granicach tolerancji.

{
  "sessionId": "7A19C2E4",
  "toleranceOhm": {
    "x24": 0.1875,
    "x2": 1.875
  }
}

Odpowiedź 200

{
  "committedAt": "2026-07-23T12:00:00Z"
}

Wartość toleranceOhm.x24 jest zapisywana w trzech pozycjach zakresu x24, a toleranceOhm.x2 — w trzech pozycjach zakresu x2. Obie wartości muszą być skończonymi liczbami dodatnimi.

Powtórzenie operacji commit dla tej samej zapisanej wersji w ramach sesji jest idempotentne. Brakujące, niekompletne lub nieprawidłowe strukturalnie migawki powodują zwrócenie 400 ERROR_INVALID_ARGUMENT. Przekroczenie podanej tolerancji nie jest samo w sobie błędem oprogramowania układowego.

---

POST /api/service/calibration/finish/

Kończy sesję, odrzuca niezatwierdzoną wersję roboczą i zwalnia ścieżkę pomiarową.

{
  "sessionId": "7A19C2E4"
}

Odpowiedź 200

{
  "state": "idle",
  "finished": true
}

---

Ograniczenia pamięci

Pojedynczy rekord w wewnętrznym sektorze 1 pamięci Flash zawiera serwisową wartość magic, wersję formatu i sumę kontrolną CRC, natomiast zagnieżdżona struktura Calibration_t zawiera wspólną wartość committedAt oraz sześć pozycji kalibracji. Każda pozycja przechowuje capturedAt, referenceOhm, historyczną wartość toleranceOhm podaną przy operacji commit, a dla każdego kanału także capturedAdc i verifyAdc. Pochodne wyniki pomiarów nie są przechowywane w pamięci Flash. Bieżąca wersja formatu to 0x0600; rekordy w innych wersjach nie są wczytywane i wymagają ponownej kalibracji. Punkt końcowy report oblicza pola pochodne i serializuje je na żądanie; oddzielny obiekt raportu nie jest przechowywany.

Podczas zwykłego pomiaru rezystancja jest obliczana metodą interpolacji odcinkowo-liniowej. Gdy ADC <= ADC(p2), używane są współczynniki wyznaczone z p1+p2; w przypadku wyższej wartości ADC używane są współczynniki wyznaczone z p2+p3. Poza skrajnymi punktami do ekstrapolacji używana jest najbliższa para.

Błąd zapisu pozostawia sesję w pamięci RAM aktywną, umożliwiając kolejną próbę wykonania operacji commit lub jawne wywołanie operacji finish. Nie ma gwarancji, że poprzednia wersja w pamięci Flash przetrwa awarię zasilania lub błąd programowania podczas kasowania albo zapisu. Rzeczywista atomowość typu „stara lub nowa wersja” wymaga drugiego banku kasowania lub zmiany układu pamięci Flash.

---

Błędy sesji

• Pusta treść żądania lub nieprawidłowy składniowo kod JSON → 400 ERROR_API_PARSING.
• Brakujące pola lub pola nieprawidłowego typu → 400 ERROR_INVALID_ARGUMENT.
• Nieprawidłowy lub wygasły identyfikator sessionId albo operacja wykonana w nieprawidłowym stanie → 400 ERROR_INVALID_VALUE.
• Ścieżka pomiarowa nie jest gotowa podczas operacji status lub capture → 503 ERROR_NOT_READY.
• Błąd zapisu podczas operacji commit → 500 ERROR_IO.