Skip to content

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

hardware-hal

Unverified

Слой абстракции железа, метрология и протокол весовой платы 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: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 318kUpdated Claude CodeCodexUnverifiedInstall
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: 318kUpdated Claude CodeCodexUnverifiedInstall