Сервіс калібрування

Заводське калібрування виконується в межах одного спільного для всього пристрою сеансу. Сеанс монопольно використовує вимірювальний тракт, завершується після 30 секунд бездіяльності та зберігає чернетку в оперативній пам’яті до операції commit. Успішні операції status, range, capture і commit подовжують строк дії сеансу.

Авторизація

• GET /api/service/calibration/report/ потребує Bearer powerUser; апаратний сервісний ключ не потрібен.
• status і всі кінцеві точки, що вносять зміни, потребують Bearer powerUser та збереженого прапорця наявності апаратного сервісного ключа.
• За відсутності ключа кінцева точка повертає 403 ERROR_NO_ACCESS.

Модель даних

Передбачено шість незалежних комірок: x24_p1 (50 Ом), x24_p2 (100 Ом), x24_p3 (200 Ом), x2_p1 (500 Ом), x2_p2 (1000 Ом) і x2_p3 (2000 Ом).

Кожен збережений знімок містить застосований абсолютний допуск і необроблені значення АЦП для чотирьох каналів. Поточні значення опору та перевірки для вибраної комірки обчислюються лише за її еталонним і зчитаним значеннями АЦП: R = referenceOhm * ADC / capturedAdc. Значення previewOhm, deltaOhm і deltaPercent обчислюються динамічно під час формування відповіді. Інші комірки в обчисленні не беруть участі.

Допуск обчислює інструмент виробника. Під час операції commit прошивка отримує два остаточні значення, зберігає їх як історичні дані та не визначає, чи відповідає вимірювання технічним вимогам.

Одразу після зчитування відповідний елемент captures уже містить усі поля знімка. Доки не буде опрацьовано десять нових вікон перевірки, поля verifyAdc, previewOhm, deltaOhm і deltaPercent мають нульові значення. До операції commit поле tolerance має значення null. Готовність результату слід визначати за станом: завершений знімок стає доступним після переходу зі стану verify_capture у active.

Вихідні дані завершеного знімка не змінюються, доки ту саму комірку не буде зчитано повторно. Зчитування іншої точки не робить завершені знімки недійсними.

---

GET /api/service/calibration/report/

Формує останній повний звіт про якість зі збережених комірок калібрування. Окрема сутність звіту у Flash-пам’яті не зберігається.

Відповідь 200, звіт недоступний

{
  "available": false
}

Відповідь available: false означає, що збережений звіт недоступний. API не вказує причину його недоступності.

Відповідь 200, звіт доступний

{
  "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
        }
      ]
    }
  }
}

Повна відповідь містить усі шість ключів знімків і чотири канали в кожному знімку. Карти допусків верхнього рівня немає. Поля scale та offset відсутні.

---

GET /api/service/calibration/status/

Повертає активний сеанс і подовжує строк його дії на 30 секунд.

Відповідь 200, стан бездіяльності

{
  "state": "idle"
}

Відповідь 200, активний стан

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

Спостережувані активні стани: switching, active і verify_capture. Внутрішня модель також містить стани committing і stopping, але операції збереження та завершення виконуються синхронно, тому status не повертає ці перехідні стани.

Інструмент виробника застосовує допуск для поточної процедури зі своєї конфігурації. Для незбережених елементів captures поле tolerance має значення null; після операції commit кожна комірка містить історичний допуск, наданий інструментом.

Поле live[].resistanceOhm має тип number|null: для порожньої або неповної чернетки значення опору, яке неможливо обчислити, серіалізується як null.

---

POST /api/service/calibration/begin/

Розпочинає єдиний сеанс калібрування зі збереженого набору точок. Якщо запис у Flash-пам’яті відсутній або недійсний, сеанс починається з порожньої чернетки. Тіло запиту не використовується.

Початкова активна комірка — x24_p1.

Відповідь 200

{
  "sessionId": "7A19C2E4"
}

Повертає 400 ERROR_INVALID_VALUE, якщо інший сеанс уже активний. 503 ERROR_NOT_READY означає, що завдання вимірювання не прийняло команду.

---

POST /api/service/calibration/range/

Вибирає коефіцієнт підсилення і точку. Коли коефіцієнт підсилення змінюється, сеанс переходить у стан switching, доки не буде опубліковано нове вікно вимірювання, яке підтверджує застосування апаратного тракту.

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

Відповідь 200

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

---

POST /api/service/calibration/capture/

Зчитує поточне вікно необроблених значень АЦП для всіх чотирьох каналів і запускає перевірку за десятьма новими вікнами.

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

Відповідь 200

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

referenceOhm має бути скінченним додатним числом. Надані коефіцієнт підсилення і точка мають відповідати активній комірці.

---

POST /api/service/calibration/commit/

Зберігає набір точок і всі шість завершених, структурно коректних знімків. Еталонні значення опору та значення АЦП мають зростати від p1 до p3; різниця значень АЦП між кожною парою сусідніх точок має становити щонайменше 5%. Перед викликом кінцевої точки інструмент виробника перевіряє, чи перебувають вимірювання в межах допуску.

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

Відповідь 200

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

Значення toleranceOhm.x24 записується до трьох комірок діапазону x24, а toleranceOhm.x2 — до трьох комірок діапазону x2. Обидва значення мають бути скінченними додатними числами.

Повторна операція commit для тієї самої збереженої редакції в межах сеансу є ідемпотентною. Відсутні, неповні або структурно некоректні знімки призводять до відповіді 400 ERROR_INVALID_ARGUMENT. Вихід за межі зазначеного допуску сам по собі не є помилкою прошивки.

---

POST /api/service/calibration/finish/

Завершує сеанс, відкидає незбережену чернетку та звільняє вимірювальний тракт.

{
  "sessionId": "7A19C2E4"
}

Відповідь 200

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

---

Обмеження сховища

Один запис у внутрішньому секторі 1 Flash-пам’яті містить службове значення magic, версію формату та CRC, а вкладена структура Calibration_t — спільне значення committedAt і шість комірок калібрування. У кожній комірці зберігаються capturedAt, referenceOhm, історичне значення toleranceOhm, надане під час операції commit, а також capturedAdc і verifyAdc для кожного каналу. Похідні результати вимірювань у Flash-пам’яті не зберігаються. Поточна версія формату — 0x0600; записи інших версій не завантажуються та потребують повторного калібрування. Кінцева точка report обчислює похідні поля та серіалізує їх за запитом; окрема сутність звіту не зберігається.

Під час звичайного вимірювання опір обчислюється за допомогою кусково-лінійної інтерполяції. Якщо ADC <= ADC(p2), використовуються коефіцієнти, отримані з p1+p2; для більшого значення АЦП — коефіцієнти, отримані з p2+p3. За межами крайніх точок для екстраполяції використовується найближча пара.

У разі помилки сховища сеанс в оперативній пам’яті залишається активним для наступної спроби commit або явної операції finish. Збереження попередньої редакції у Flash-пам’яті в разі збою живлення чи помилки програмування під час стирання або запису не гарантується. Для справжньої атомарності за принципом «стара або нова версія» потрібен другий банк стирання або зміна структури Flash-пам’яті.

---

Помилки сеансу

• Порожнє або синтаксично некоректне тіло JSON → 400 ERROR_API_PARSING.
• Відсутні поля або поля некоректного типу → 400 ERROR_INVALID_ARGUMENT.
• Недійсний чи прострочений sessionId або операція в недійсному стані → 400 ERROR_INVALID_VALUE.
• Вимірювальний тракт не готовий під час операції status або capture → 503 ERROR_NOT_READY.
• Помилка збереження під час операції commit → 500 ERROR_IO.