hardware-hal

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

SKILL.md

GitHub

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

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

Код вне 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 мм.