Py-Micro-HIL

Py-Micro-HIL is a modular, lightweight Hardware-in-the-Loop (HIL) testing framework for Python. It provides a unified interface for testing embedded systems, sensors, and communication buses (Modbus RTU, SPI, I2C, UART, GPIO) both on Raspberry Pi hardware and in PC simulation mode.

🚀 Overview

Py-Micro-HIL enables automated functional and integration testing of embedded systems. It supports both real hardware execution on Raspberry Pi and simulated environments on any PC.

With this framework you can:

• Write and organize test suites for hardware peripherals.
• Interface with GPIO, SPI, I2C, UART, or Modbus RTU devices.
• Use mocks for offline or CI/CD testing.
• Generate structured HTML and console reports.
• Integrate easily with pipelines or GitHub Actions.

🔗 Documentation

📚 Full developer and user documentation is available here: ➡️ https://niwciu.github.io/PY_MICRO_HIL

⚙️ Installation

🧰 Option 1 – From PyPI (recommended for most users)

pip install py-micro-hil

🧪 Option 2 – From source (for contributors)

git clone https://github.com/niwciu/PY_MICRO_HIL.git
cd PY_MICRO_HIL
pip install -e .

💡 On your hil test server, you can use the flag  --break-system-packages  to simplify installation and usage for CI/CD environments:

pip install py-micro-hil --break-system-packages

It will make your life easier when using it in services like GitHub Actions

dependencies

pymodbus, pytest, smbus2, spidev, pyserial

Developer setup

For development and contribution:

git clone https://github.com/niwciu/PY_MICRO_HIL.git
cd PY_MICRO_HIL
pip install -e .[dev]

🧩 Example usage

1️⃣ Create a configuration file

In the project root for your project hil tests main folder, create a file peripherals_config.yaml , for example:

peripherals:  
  gpio:
    - pin: 17
      mode: out
      initial: low
    - pin: 18
      mode: in

Full configuration reference: 📖 Configuration and YAML guide →

2️⃣ Create test files

Create a directory named hil_tests/ and add your test groups there. Each .py file should start it's name from test and represents a test group.

Example: hil_tests/test_gpio_led.py

from py_micro_hil.assertions import *
from py_micro_hil.framework_API import *

def setup_group():    TEST_INFO_MESSAGE("Setting up gpio led test group")

def teardown_group():    TEST_INFO_MESSAGE("Tearing down gpio led test group")

def test_led_toggle():    gpio = get_RPiGPIO_peripheral()    gpio.write(17, 1)    TEST_    TEST_ASSERT_EQUAL (1, gpio.read(18))

3️⃣ Run the tests

Before running tests check available options by typing:

hiltests --help

Use the built-in CLI runner:

hiltests --config ./peripherals_config.yaml --test-dir ./hil_tests

Generate a starter group from the editable template without executing any tests:

hiltests --create-test-group gpio_smoke ./hil_tests

If both the YAML configuration and the hil_tests folder are in the same directory, simply open this directory and run:

hiltests

4️⃣ Generate reports

Py-Micro-HIL can generate both console log files and HTML reports.

Example:

hiltests --log ./reports/log.txt

or

hiltests --html ./reports/report.html

Reports can be customized with name and path. See: Reports and Logging →

💡 Features

• ✅ Unified test structure (TestFramework, TestGroup, Test)
• ✅ Automatic setup/teardown with context isolation
• ✅ YAML-driven configuration system
• ✅ Dynamic test discovery (tests_group_factory)
• ✅ Mock peripherals for PC environment (not RPi)
• ✅ Full logging and HTML report generation
• ✅ Native CLI interface (hiltests)
• ✅ Compatible with Raspberry Pi and Linux hosts

🧰 Supported peripherals & protocols