Skip to content

webdev1881/scale-S2L / .claude/skills/hardware-hal

hardware-hal

Verified

Слой абстракции железа, метрология и протокол весовой платы Aurora S2. Использовать при работе с backend/app/hal/, драйверами весов и принтера, эндпоинтами /api/sim/*, расчётом веса, тары и стабилизации.

FileKindSize
SKILL.mdskill md4.3 KB
---
name: hardware-hal
description: Слой абстракции железа, метрология и протокол весовой платы Aurora S2. Использовать при работе с backend/app/hal/, драйверами весов и принтера, эндпоинтами /api/sim/*, расчётом веса, тары и стабилизации.
---

# Железо и метрология

## Главное правило

Код вне `backend/app/hal/` **никогда** не обращается к порту, устройству или библиотеке
железа напрямую. Любой новый узел добавляется как интерфейс в `hal/base.py` плюс **две**
реализации: `fake` (симулятор) и реальный драйвер. Выбор — только в `hal/registry.py`.

Без этого разработка вне работы (весы недоступны) и автотесты становятся невозможны.

- `S2L_HAL_BACKEND=fake` — режим по умолчанию, вся разработка идёт в нём.
- Симулятор платформы качается, а не доезжает по прямой: груз на пружине с затуханием
  (`RESONANCE_HZ`, `DAMPING` в `hal/scale/fake.py`). Замер: 800 г проскакивают до 896 г,
  проседают до 788 и устаиваются за 1.25 с; снятие уводит показание до −98 г и
  возвращает к нулю за 1.04 с. Без перелёта и просадки проверять нечего — интерфейс,
  который ждёт стабилизации, на мгновенно доезжающем весе выглядит рабочим всегда.
- Покой определяется по разбросу последних отсчётов, а не по близости к заданной цели:
  настоящая плата тоже не знает, что на неё положили. Шум АЦП подмешивается только в
  сам отсчёт (`read`) — в состоянии он превращался в случайное блуждание, и признак
  покоя мигал у самого порога.
- Эндпоинты `/api/sim/*` существуют только для `fake` и обязаны возвращать 400 на `real`.

## Метрология

- Метрологические параметры (НПВ, цена деления, наименьшая навеска) живут в `.env`,
  а не в админке: это свойства прибора. Показание всегда кратно цене деления —
  вес, который прибор не может измерить, не должен попадать на этикетку.
- Тара, стабилизация, минимальная масса и округление считаются **на бэкенде**
  (`services/printing.py`). Фронтенд только отображает и блокирует кнопку. Причина
  метрологическая: расчёт, попавший в браузер, невозможно ни проверить, ни
  сертифицировать.

## Протокол весовой платы

Подтверждён на приборе: `/dev/ttyS4`, 19200 8N1, кадр из 8 байт с шестью ASCII-цифрами
граммов (см. `docs/hardware/aurora-s2.md`). Разбор кадра менять только в
`SerialScale._parse_frame` — остальной код не трогать.

Кадры выцепляются из потока по признаку, а не отрезаются вслепую по 8 байт: после
потери байта слепое чтение склеивает половинки соседних кадров в правдоподобные, но
неверные числа — то есть в неверную цену на этикетке.

Паспортные данные прибора — `docs/hardware/aurora-s2.md`: экран 1920x1080, НПВ 15 кг,
цена деления 2/5 г, ширина этикетки не более 56 мм.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall