lift_indicator_suite/tools/hil

tools/hil

Python-окружение на базе uv для HIL-тестов и отладки MIMXRT1052 через pyOCD (SWD: загрузка ELF в RAM, GDB-сервер).

Запускается на хост-машине — не внутри devcontainer.

---

Структура

tools/hil/
├── conftest.py                — pytest-фикстуры (m5, loaded_<n>, uart_<n>, usb_cdc_port, firmware_cdc)
├── env_config.py               — конфигурация из os.environ / .env
├── pyocd_utils.py               — FLEXRAM init, ELF loader, run_from_vectors (использует conftest.py и load_and_run.py)
├── load_and_run.py              — CLI-утилита: загрузить ELF в RAM вручную
├── 01_test_uart.py              — bsp_uart_host, без внешнего стенда
├── 02_test_opto.py              — bsp_opto через реле M5StampPLC
├── 03_test_can.py               — bsp_can, M5StampPLC как второй узел CAN-шины
├── 04_test_button.py            — bsp_button, интерактивный (кнопки нажимает оператор)
├── 05_test_usb_cdc.py           — bsp_usb_cdc, требует физический USB-порт таргета
├── 06_test_firmware_can.py      — test_can внутри firmware_test (протокол v2 через CDC)
├── 06_test_firmware_opto.py     — test_opto внутри firmware_test (протокол v2 через CDC)
├── m5/
│   ├── agent.py                  — MicroPython-агент на M5StampPLC (реле, входы, CAN)
│   ├── cli.py                    — интерактивный CLI для ручного тестирования стенда и таргета
│   ├── power.py                  — управление питанием таргета (RLY1) из командной строки
│   └── firmware/                 — прошивки MicroPython для M5StampPLC
│       ├── esp32s3_bl-v1.25.0_twai.bin  — используется (поддерживает CAN)
│       └── esp32s3_bl-v1.27.0.bin       — CAN не поддерживается, не использовать
├── pyproject.toml
└── uv.lock

Числовой префикс в имени файла (NN_test_*.py, паттерн задан в pyproject.toml → python_files) фиксирует порядок диагностики стенда — от простого автономного теста к более сложным и зависящим от внешнего оборудования.

MicroPython на M5StampPLC: использовать m5/firmware/esp32s3_bl-v1.25.0_twai.bin. В прошивке 1.27 модуль CAN недоступен — agent.py инициализирует CAN при старте, тесты с CAN не пройдут. Загрузить прошивку можно с помощью espflash.

---

Тестовые файлы

Файл	Что проверяет	Внешний стенд	Маркер
01_test_uart.py	bsp_uart_host	нет (M5 только включает питание)	—
02_test_opto.py	bsp_opto	M5StampPLC (реле → оптопары)	—
03_test_can.py	bsp_can	M5StampPLC (второй узел CAN-шины)	—
04_test_button.py	bsp_button	нет, кнопки нажимает оператор	interactive
05_test_usb_cdc.py	bsp_usb_cdc	физический USB-порт таргета	usb_vcom
06_test_firmware_can.py	test_can внутри firmware_test (протокол v2)	M5StampPLC	usb_vcom
06_test_firmware_opto.py	test_opto внутри firmware_test (протокол v2)	M5StampPLC	usb_vcom

Подробности о том, что именно проверяется и какие гарантии даёт каждый тест — в tests/target/*/README.md рядом с соответствующей HIL-прошивкой (06_test_firmware_*.py — исключение: они гоняют test_can/test_opto внутри firmware_test, а не прошивки из tests/target).

---

Документация

Полное описание стека HIL-тестирования — в docs/testing/hil/:

Документ	Содержимое
HIL_HOW_TO.md	Как запускать HIL-тесты (пошагово)
HIL_BENCH.md	Стенд: оборудование, подключение, маппинг реле
HIL_CREATE_TEST.md	Как добавить новый HIL-тест
HIL_FIXTURES.md	Памятка по pytest-фикстурам применительно к HIL

---

Быстрый старт

# Первый раз: установить зависимости
cd tools/hil && uv sync

# Заполнить .env в корне репозитория (см. .env.example — порты MCU-Link и M5)

# Задеплоить агент на M5 (после изменений agent.py — повторить)
just host::m5-deploy

# devcontainer: собрать HIL-прошивки
just build::build-hil

# хост: запустить тесты
just host::hil-run              # все не интерактивные и не usb_vcom тесты
just host::hil-run-interactive  # интерактивные (кнопки) — нужен оператор у стенда
just host::hil-uart
just host::hil-opto
just host::hil-can
just host::hil-button
just host::hil-usb-cdc
just host::hil-firmware-opto    # test_opto через firmware_test (протокол v2)
just host::hil-firmware-can     # test_can через firmware_test (протокол v2)
just host::hil-firmware         # оба сразу

Отладка без pytest

just host::debug-server         # GDB-сервер pyOCD — оставить запущенным, подключаться из VSCode
just host::debug-list-targets   # доступные builtin-таргеты pyOCD для MIMXRT
uv run python load_and_run.py firmware_test.elf   # загрузить ELF в RAM вручную

Работа со стендом M5StampPLC

just host::m5-scan       # показать подключённые M5Stack-устройства
just host::m5-cli        # интерактивный CLI для ручного тестирования агента
just host::m5-power on   # управление питанием таргета через RLY1 (on|off)