matterlab_hotplates

matterlab_hotplates provides serial drivers for the heat-stir devices used in the Matter Lab. The package wraps device-specific command sets behind a small common interface so automation code can read temperatures, set heating targets, and control stirring without dealing with raw serial commands.

Supported Devices

• HeatStirPlate: shared abstract base class
• IKAHotplate
• HeidolphHotplate
• IKAHBHotbath

Installation

Install the package:

pip install matterlab_hotplates

For development:

pip install -e .[dev]

The package depends on matterlab_serial_device, which is installed automatically.

Quick Start

Example with an IKA hotplate:

from matterlab_hotplates import IKAHotplate

hotplate = IKAHotplate(com_port="COM5")

print("Current temperature:", hotplate.temp)
print("Current stirring speed:", hotplate.rpm)

hotplate.temp = 80
hotplate.rpm = 400
hotplate.stand_by()

Core API

The shared HeatStirPlate interface exposes:

• temp
• target_temp
• rpm
• target_rpm
• stand_by()

Device-specific classes add their own helpers:

• IKAHotplate: reset(), tare(), weight
• HeidolphHotplate: _set_new_interface_protocol()
• IKAHBHotbath: name, maxtemp

Testing

Simulation Tests

Simulation tests are the default validation layer and are safe for CI.

One-click run:

python examples/test_sim.py

Direct pytest run:

pytest tests/test_heat_stir_plate.py tests/test_ika_sim.py tests/test_heidolph_sim.py tests/test_ika_hotbath_sim.py

Hardware Tests

Hardware tests are opt-in because real devices may not be connected in every environment.

Available hardware test files:

• tests/test_ika_real.py
• tests/test_heidolph_real.py
• tests/test_ika_hotbath_real.py

They are marked with @pytest.mark.real and are skipped unless --run-real is supplied.

Example:

pytest tests/test_ika_real.py --run-real --com-port COM5

You can also provide hardware configuration through an environment variable:

• HOTPLATE_COM_PORT

Examples

The examples/ directory contains the recommended entry points:

• examples/test_sim.py: one-click simulation-only test runner
• examples/real_devices.py: readable examples for real IKA, Heidolph, and hotbath hardware
• examples/README.md: short guide to the examples directory

Development

Useful commands:

pytest
ruff check .
ruff format .

The default pytest configuration includes retries, timeouts, coverage output, and uses src as the import root for local development.

Package Layout

src/matterlab_hotplates/
  base_hotplate.py
  heidolph_hotplate.py
  ika_hotbath.py
  ika_hotplate.py
tests/
examples/

License

This project is distributed under the MIT License. See LICENSE for details.