pamoja-hal 0.2.0__tar.gz

pamoja_hal-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+# Native extensions are built per platform, not committed.
+*.so
+*.pyd
+*.dylib
+
+# Build and packaging output.
+dist/
+wheels/
+target/
+
+# Local virtual environments.
+.venv/
+venv/

pamoja_hal-0.2.0/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Wiedman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pamoja_hal-0.2.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: pamoja-hal
+Version: 0.2.0
+Summary: The embedded-hal traits every driver takes, a bit-banged 1-Wire bus, simulated parts and scripted buses that stand in for hardware, the Linux backends over i2c-dev, spidev, and the GPIO character device, one I2C bus and one serial port a program and its drivers share, and delays that sleep or only count.
+Project-URL: Repository, https://github.com/molexxxx/pamoja
+Project-URL: Documentation, https://pamoja.molex.cloud/docs/guides/hal.html
+Author: molexxxx
+License: MIT
+License-File: LICENSE-MIT
+Keywords: hal,iot,pamoja,robotics
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pamoja-native==0.2.0
+Description-Content-Type: text/markdown
+
+# pamoja-hal
+
+The embedded-hal traits every driver takes, a bit-banged 1-Wire bus, simulated parts and scripted buses that stand in for hardware, the Linux backends over i2c-dev, spidev, and the GPIO character device, one I2C bus and one serial port a program and its drivers share, and delays that sleep or only count. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/hal.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/hal.html)
+
+## Install
+
+```sh
+pip install pamoja-hal
+```
+
+```python
+from pamoja import hal
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/hal.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/hal.py):
+
+```python
+from pamoja.core import PamojaError
+from pamoja.hal import I2cBus, I2cStep
+from pamoja.sensors import Bme280, Bme280Config, Bme280CtrlMeas, Bme280Measurement, bme280
+
+BME280 = bme280.ADDRESS_PRIMARY
+
+
+def shown(reading: Bme280Measurement) -> str:
+    """A reading the way every line below prints it."""
+    return (
+        f"{reading.celsius:.2f} C, {reading.hectopascals:.2f} hPa, "
+        f"{reading.relative_humidity_percent:.2f} %"
+    )
+
+
+def x(code: int) -> str:
+    """An oversampling setting the way a datasheet writes it."""
+    return f"x{bme280.oversampling_factor(code)}"
+
+
+# A bus with one part on it: a BME280 that is not there. It holds a real part's calibration
+# and one measurement that part took, and it answers from its registers, so the driver runs
+# its whole datasheet sequence against it. On a Raspberry Pi the bus is
+# I2cBus.open("/dev/i2c-1") and nothing after this line changes.
+bus = I2cBus.simulated([bme280.sim.part(BME280)])
+sensor = Bme280(bus, BME280)
+
+# Reset, identify, calibrate, configure. The datasheet wants ctrl_hum written before
+# ctrl_meas, and the part left asleep until a measurement is forced. The part keeps what the
+# driver wrote, so the configuration reads back off the bus.
+sensor.init()
+part = bus.part(BME280)
+humidity = bme280.ctrl_hum_from_bits(part.register(bme280.REGISTER_CTRL_HUM))
+ctrl = bme280.ctrl_meas_from_bits(part.register(bme280.REGISTER_CTRL_MEAS))
+asleep = ctrl.mode == bme280.Mode.SLEEP
+print(
+    f"configured   humidity {x(humidity)}, temperature {x(ctrl.temperature)}, "
+    f"pressure {x(ctrl.pressure)}, asleep: {str(asleep).lower()}"
+)
+
+# One forced measurement. The driver waits the datasheet's longest measurement time for
+# these settings before it reads, and a simulated bus counts that wait rather than sleeping
+# through it.
+reading = sensor.measure()
+print(f"measured     {shown(reading)}")
+print(f"waited       {bus.waited_micros / 1000:.2f} ms across {bus.transfers} transfers")
+waited = bus.waited_micros
+
+# A part reports whatever it is asked to. Putting one in the first one's place is how a
+# program meets a reading it would otherwise wait on the weather for, here a cold store at
+# four degrees, and the driver carries on without noticing.
+bus.attach(bme280.sim.reporting(BME280, 4.0, 1013.25, 80.0))
+cold = sensor.measure()
+print(f"cold store   {shown(cold)}")
+
+# Nothing answers at the part's other address, and the driver says so rather than
+# returning a reading.
+try:
+    Bme280(bus, bme280.ADDRESS_SECONDARY).init()
+    print("absent       a part answered")
+except PamojaError as error:
+    print(f"absent       {error}")
+
+# The other half of the bus layer. A script plays one conversation and refuses anything
+# else, which proves a driver follows the datasheet rather than merely working: the reset,
+# the status once the calibration has loaded, the chip id, the two calibration blocks, the
+# three configuration writes in the order the part requires, then one forced measurement.
+x1 = bme280.Oversampling.X1
+settings = Bme280CtrlMeas(temperature=x1, pressure=x1, mode=bme280.Mode.SLEEP)
+forced = Bme280CtrlMeas(temperature=x1, pressure=x1, mode=bme280.Mode.FORCED)
+idle = bytes([bme280.sim.STATUS_IDLE])
+script = I2cBus.scripted([
+    I2cStep.write(BME280, bytes([bme280.REGISTER_RESET, bme280.RESET_WORD])),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_STATUS]), idle),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_CHIP_ID]), bytes([bme280.CHIP_ID])),
+    I2cStep.write_read(
+        BME280, bytes([bme280.REGISTER_CALIB_TEMP_PRESS]), bme280.sim.calibration()
+    ),
+    I2cStep.write_read(
+        BME280, bytes([bme280.REGISTER_CALIB_HUMIDITY]), bme280.sim.calibration_humidity()
+    ),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CONFIG, bme280.config_bits(Bme280Config())])),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CTRL_HUM, bme280.ctrl_hum_bits(x1)])),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CTRL_MEAS, bme280.ctrl_meas_bits(settings)])),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CTRL_MEAS, bme280.ctrl_meas_bits(forced)])),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_STATUS]), idle),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_DATA]), bme280.sim.burst()),
+])
+checked = Bme280(script, BME280).measure()
+print(
+    f"datasheet    {checked.celsius:.2f} C after {script.transfers} transfers, "
+    f"{script.remaining} steps left"
+)
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-hal`](https://crates.io/crates/pamoja-hal) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_hal/index.html), [docs.rs](https://docs.rs/pamoja-hal), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-hal) |
+| TypeScript | [`@pamoja/hal`](https://www.npmjs.com/package/@pamoja/hal) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_hal.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-hal) |
+| Python | [`pamoja-hal`](https://pypi.org/project/pamoja-hal/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/hal.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-hal) |
+| C# | [`Pamoja.Hal`](https://www.nuget.org/packages/Pamoja.Hal) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Hal.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-hal) |
+
+## Documentation
+
+- [`pamoja.hal` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/hal.html), every class and function in this module.
+- [The Buses guide](https://pamoja.molex.cloud/docs/guides/hal.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_hal-0.2.0/README.md

@@ -0,0 +1,140 @@
+# pamoja-hal
+
+The embedded-hal traits every driver takes, a bit-banged 1-Wire bus, simulated parts and scripted buses that stand in for hardware, the Linux backends over i2c-dev, spidev, and the GPIO character device, one I2C bus and one serial port a program and its drivers share, and delays that sleep or only count. One capability of [pamoja](https://github.com/molexxxx/pamoja), one memory-safe Rust core with bindings for TypeScript, Python, and C#.
+
+[![read the guide](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-guide.svg)](https://pamoja.molex.cloud/docs/guides/hal.html)
+[![documentation](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-docs.svg)](https://pamoja.molex.cloud/docs/)
+[![API reference](https://raw.githubusercontent.com/molexxxx/pamoja/main/.github/badges/btn-api.svg)](https://pamoja.molex.cloud/docs/reference/python/pamoja/hal.html)
+
+## Install
+
+```sh
+pip install pamoja-hal
+```
+
+```python
+from pamoja import hal
+```
+
+This pulls in `pamoja-native`, the compiled engine. `pip install pamoja` is the whole framework in one package.
+
+## Example
+
+The script the test suite runs, spliced here as it ran.
+
+From [`bindings/python/guides/hal.py`](https://github.com/molexxxx/pamoja/blob/main/bindings/python/guides/hal.py):
+
+```python
+from pamoja.core import PamojaError
+from pamoja.hal import I2cBus, I2cStep
+from pamoja.sensors import Bme280, Bme280Config, Bme280CtrlMeas, Bme280Measurement, bme280
+
+BME280 = bme280.ADDRESS_PRIMARY
+
+
+def shown(reading: Bme280Measurement) -> str:
+    """A reading the way every line below prints it."""
+    return (
+        f"{reading.celsius:.2f} C, {reading.hectopascals:.2f} hPa, "
+        f"{reading.relative_humidity_percent:.2f} %"
+    )
+
+
+def x(code: int) -> str:
+    """An oversampling setting the way a datasheet writes it."""
+    return f"x{bme280.oversampling_factor(code)}"
+
+
+# A bus with one part on it: a BME280 that is not there. It holds a real part's calibration
+# and one measurement that part took, and it answers from its registers, so the driver runs
+# its whole datasheet sequence against it. On a Raspberry Pi the bus is
+# I2cBus.open("/dev/i2c-1") and nothing after this line changes.
+bus = I2cBus.simulated([bme280.sim.part(BME280)])
+sensor = Bme280(bus, BME280)
+
+# Reset, identify, calibrate, configure. The datasheet wants ctrl_hum written before
+# ctrl_meas, and the part left asleep until a measurement is forced. The part keeps what the
+# driver wrote, so the configuration reads back off the bus.
+sensor.init()
+part = bus.part(BME280)
+humidity = bme280.ctrl_hum_from_bits(part.register(bme280.REGISTER_CTRL_HUM))
+ctrl = bme280.ctrl_meas_from_bits(part.register(bme280.REGISTER_CTRL_MEAS))
+asleep = ctrl.mode == bme280.Mode.SLEEP
+print(
+    f"configured   humidity {x(humidity)}, temperature {x(ctrl.temperature)}, "
+    f"pressure {x(ctrl.pressure)}, asleep: {str(asleep).lower()}"
+)
+
+# One forced measurement. The driver waits the datasheet's longest measurement time for
+# these settings before it reads, and a simulated bus counts that wait rather than sleeping
+# through it.
+reading = sensor.measure()
+print(f"measured     {shown(reading)}")
+print(f"waited       {bus.waited_micros / 1000:.2f} ms across {bus.transfers} transfers")
+waited = bus.waited_micros
+
+# A part reports whatever it is asked to. Putting one in the first one's place is how a
+# program meets a reading it would otherwise wait on the weather for, here a cold store at
+# four degrees, and the driver carries on without noticing.
+bus.attach(bme280.sim.reporting(BME280, 4.0, 1013.25, 80.0))
+cold = sensor.measure()
+print(f"cold store   {shown(cold)}")
+
+# Nothing answers at the part's other address, and the driver says so rather than
+# returning a reading.
+try:
+    Bme280(bus, bme280.ADDRESS_SECONDARY).init()
+    print("absent       a part answered")
+except PamojaError as error:
+    print(f"absent       {error}")
+
+# The other half of the bus layer. A script plays one conversation and refuses anything
+# else, which proves a driver follows the datasheet rather than merely working: the reset,
+# the status once the calibration has loaded, the chip id, the two calibration blocks, the
+# three configuration writes in the order the part requires, then one forced measurement.
+x1 = bme280.Oversampling.X1
+settings = Bme280CtrlMeas(temperature=x1, pressure=x1, mode=bme280.Mode.SLEEP)
+forced = Bme280CtrlMeas(temperature=x1, pressure=x1, mode=bme280.Mode.FORCED)
+idle = bytes([bme280.sim.STATUS_IDLE])
+script = I2cBus.scripted([
+    I2cStep.write(BME280, bytes([bme280.REGISTER_RESET, bme280.RESET_WORD])),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_STATUS]), idle),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_CHIP_ID]), bytes([bme280.CHIP_ID])),
+    I2cStep.write_read(
+        BME280, bytes([bme280.REGISTER_CALIB_TEMP_PRESS]), bme280.sim.calibration()
+    ),
+    I2cStep.write_read(
+        BME280, bytes([bme280.REGISTER_CALIB_HUMIDITY]), bme280.sim.calibration_humidity()
+    ),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CONFIG, bme280.config_bits(Bme280Config())])),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CTRL_HUM, bme280.ctrl_hum_bits(x1)])),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CTRL_MEAS, bme280.ctrl_meas_bits(settings)])),
+    I2cStep.write(BME280, bytes([bme280.REGISTER_CTRL_MEAS, bme280.ctrl_meas_bits(forced)])),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_STATUS]), idle),
+    I2cStep.write_read(BME280, bytes([bme280.REGISTER_DATA]), bme280.sim.burst()),
+])
+checked = Bme280(script, BME280).measure()
+print(
+    f"datasheet    {checked.celsius:.2f} C after {script.transfers} transfers, "
+    f"{script.remaining} steps left"
+)
+```
+
+## The same capability in every language
+
+| Language | Package | Reference |
+| --- | --- | --- |
+| Rust | [`pamoja-hal`](https://crates.io/crates/pamoja-hal) | [reference](https://pamoja.molex.cloud/docs/reference/rust/pamoja_hal/index.html), [docs.rs](https://docs.rs/pamoja-hal), [install](https://pamoja.molex.cloud/docs/reference/rust.html#rust-hal) |
+| TypeScript | [`@pamoja/hal`](https://www.npmjs.com/package/@pamoja/hal) | [reference](https://pamoja.molex.cloud/docs/reference/node/modules/_pamoja_hal.html), [install](https://pamoja.molex.cloud/docs/reference/node.html#node-hal) |
+| Python | [`pamoja-hal`](https://pypi.org/project/pamoja-hal/) | [reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/hal.html), [install](https://pamoja.molex.cloud/docs/reference/python.html#python-hal) |
+| C# | [`Pamoja.Hal`](https://www.nuget.org/packages/Pamoja.Hal) | [reference](https://pamoja.molex.cloud/docs/reference/dotnet/api/Pamoja.Hal.html), [install](https://pamoja.molex.cloud/docs/reference/dotnet.html#dotnet-hal) |
+
+## Documentation
+
+- [`pamoja.hal` reference](https://pamoja.molex.cloud/docs/reference/python/pamoja/hal.html), every class and function in this module.
+- [The Buses guide](https://pamoja.molex.cloud/docs/guides/hal.html), with the same example in Rust, TypeScript, and C#.
+- [Every capability](https://pamoja.molex.cloud/docs/), and the [install page](https://pamoja.molex.cloud/docs/install.html).
+
+## License
+
+MIT

pamoja_hal-0.2.0/pamoja/hal/__init__.py

@@ -0,0 +1,801 @@
+"""Idiomatic bus facade.
+
+A driver is a conversation with a part, and a bus is what carries it. An
+:class:`I2cBus` is one bus that the program and every driver on it share, with one of
+three things on the other end: the kernel's adapter on a Linux board, simulated parts
+that answer from their registers, or a script of the transfers a driver is expected to
+make. A driver runs the same way over all three, so a program is written and tested
+with nothing plugged in and then pointed at ``/dev/i2c-1``. A :class:`SerialPort` is the
+same idea for a UART, and :class:`DelayLog` and :class:`SleepDelay` pace a driver that
+waits between pin changes.
+"""
+
+from __future__ import annotations
+
+import enum
+import time
+from dataclasses import dataclass
+from typing import Iterable, List, Optional, Protocol, Tuple, Union
+
+from pamoja._native import CommandPart as _NativeCommandPart
+from pamoja._native import I2cBus as _NativeBus
+from pamoja._native import I2cPart as _NativePart
+from pamoja._native import I2cStep as _NativeStep
+from pamoja._native import SerialPort as _NativeSerialPort
+from pamoja._native import SerialStep as _NativeSerialStep
+from pamoja._native import WordPart as _NativeWordPart
+from pamoja._native import serial_bits_per_character as _serial_bits_per_character
+from pamoja._native import serial_character_nanos as _serial_character_nanos
+from pamoja._native import serial_transfer_micros as _serial_transfer_micros
+
+__all__ = [
+    "CommandPart",
+    "Delay",
+    "DelayLog",
+    "I2cBus",
+    "I2cBusKind",
+    "I2cFault",
+    "I2cPart",
+    "I2cStep",
+    "Parity",
+    "SerialPort",
+    "SerialPortKind",
+    "SerialSettings",
+    "SerialStep",
+    "SimulatedPart",
+    "SleepDelay",
+    "WordPart",
+]
+
+
+class I2cBusKind(str, enum.Enum):
+    """What answers on a bus."""
+
+    #: The kernel's adapter, with real parts on real wires.
+    ADAPTER = "Adapter"
+    #: Simulated parts, answering from their registers.
+    SIMULATED = "Simulated"
+    #: A script of the transfers a driver is expected to make.
+    SCRIPTED = "Scripted"
+
+
+class I2cFault(str, enum.Enum):
+    """How a scripted step fails the transfer that reaches it."""
+
+    #: Nothing acknowledged the address.
+    NO_ACKNOWLEDGE_ADDRESS = "NoAcknowledgeAddress"
+    #: The part did not acknowledge a data byte.
+    NO_ACKNOWLEDGE_DATA = "NoAcknowledgeData"
+    #: A missing acknowledge, with no telling whether of the address or the data.
+    NO_ACKNOWLEDGE = "NoAcknowledge"
+    #: A bus error, such as a misplaced start or stop condition.
+    BUS = "Bus"
+    #: Another controller won the bus.
+    ARBITRATION_LOSS = "ArbitrationLoss"
+    #: Data arrived faster than it was taken.
+    OVERRUN = "Overrun"
+    #: A failure of no more particular kind.
+    OTHER = "Other"
+
+
+class I2cPart:
+    """A part that is not there, answering from 256 registers.
+
+    A write names a register and fills it and the ones after it; a read takes them
+    back from wherever the last write left off. What a driver writes stays written, so
+    :meth:`register` reads a part's configuration back once a driver is done with it.
+
+    >>> BME280, CHIP_ID_REGISTER, BME280_CHIP_ID = 0x76, 0xD0, 0x60
+    >>> part = I2cPart(BME280).holding(CHIP_ID_REGISTER, bytes([BME280_CHIP_ID]))
+    >>> part.register(CHIP_ID_REGISTER) == BME280_CHIP_ID
+    True
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, address: int) -> None:
+        """Make a part answering at one address, with every register reading zero.
+
+        :param address: The 7-bit address it answers to.
+        """
+        self._native = _NativePart(address)
+
+    @classmethod
+    def _wrap(cls, native: _NativePart) -> I2cPart:
+        part = cls.__new__(cls)
+        part._native = native
+        return part
+
+    def holding(self, first: int, data: bytes) -> I2cPart:
+        """Put bytes in the part from a register on, and return the part.
+
+        :param first: The register the bytes start at.
+        :param data: What to put there. Past the last register it wraps to the first.
+        :returns: This part, so calls chain.
+        """
+        self._native.load(first, bytes(data))
+        return self
+
+    def register(self, register: int) -> int:
+        """Read what one register holds now.
+
+        :param register: Which register.
+        :returns: Its value, which is what a driver wrote if it wrote one.
+        """
+        return self._native.register(register)
+
+    def read(self, first: int, length: int) -> bytes:
+        """Read consecutive registers from one register on.
+
+        :param first: The first register.
+        :param length: How many registers.
+        :returns: One byte per register.
+        """
+        return bytes(self._native.read(first, length))
+
+    @property
+    def address(self) -> int:
+        """The address the part answers to."""
+        return self._native.address
+
+    @property
+    def transfers(self) -> int:
+        """How many transfers the part has served."""
+        return self._native.transfers
+
+
+class WordPart:
+    """A part that is not there, answering from 256 registers sixteen bits wide.
+
+    This is how Texas Instruments lays out parts such as the TMP117, the INA219 and
+    INA226, the OPT3001, the ADS1115, and the HDC1080. A pointer byte names a register and
+    a register travels most significant byte first. Bits the part sets for itself, such as
+    a conversion-ready flag, are marked with :meth:`read_only` and keep the part's value
+    whatever a driver writes.
+
+    >>> TMP117, DEVICE_ID_REGISTER, TMP117_DEVICE_ID = 0x48, 0x0F, 0x0117
+    >>> part = WordPart(TMP117).holding(DEVICE_ID_REGISTER, TMP117_DEVICE_ID)
+    >>> part.word(DEVICE_ID_REGISTER) == TMP117_DEVICE_ID
+    True
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, address: int) -> None:
+        """Make a part answering at one address, with every register reading zero.
+
+        :param address: The 7-bit address it answers to.
+        """
+        self._native = _NativeWordPart(address)
+
+    @classmethod
+    def _wrap(cls, native: _NativeWordPart) -> WordPart:
+        part = cls.__new__(cls)
+        part._native = native
+        return part
+
+    def holding(self, register: int, value: int) -> WordPart:
+        """Put a value in one register, and return the part.
+
+        :param register: The register.
+        :param value: What it holds, read-only bits included.
+        :returns: This part, so calls chain.
+        """
+        self._native.set(register, value)
+        return self
+
+    def read_only(self, register: int, mask: int) -> WordPart:
+        """Mark bits of one register as the part's to set, and return the part.
+
+        :param register: The register.
+        :param mask: The bits a driver's write leaves as the part holds them.
+        :returns: This part, so calls chain.
+        """
+        self._native.read_only(register, mask)
+        return self
+
+    def set(self, register: int, value: int) -> None:
+        """Put a value in one register, read-only bits included, as the part itself would.
+
+        :param register: The register.
+        :param value: What it holds.
+        """
+        self._native.set(register, value)
+
+    def word(self, register: int) -> int:
+        """Read what one register holds now.
+
+        :param register: Which register.
+        :returns: Its value, which is what a driver wrote apart from the read-only bits.
+        """
+        return self._native.word(register)
+
+    @property
+    def address(self) -> int:
+        """The address the part answers to."""
+        return self._native.address
+
+    @property
+    def transfers(self) -> int:
+        """How many transfers the part has served."""
+        return self._native.transfers
+
+
+class CommandPart:
+    """A part that is not there, answering commands with the replies it was given.
+
+    This is how Sensirion lays out parts such as the SHT3x and the SCD4x. A write sends a
+    command and any arguments after it; a read takes the reply that command left, once,
+    padded with ``0xFF`` the way an idle bus reads. A command given no reply leaves none,
+    and a read then is not acknowledged, which is what a real part does when asked for data
+    it does not have.
+
+    >>> SHT3X, READ_STATUS = 0x44, (0xF32D).to_bytes(2, "big")
+    >>> STATUS_AFTER_RESET = bytes([0x80, 0x10, 0xE1])  # the word 0x8010, then its CRC
+    >>> part = CommandPart(SHT3X).answering(READ_STATUS, STATUS_AFTER_RESET)
+    >>> part.address == SHT3X
+    True
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, address: int, width: int = 2) -> None:
+        """Make a part answering at one address that has been given no replies yet.
+
+        :param address: The 7-bit address it answers to.
+        :param width: How many bytes a command takes: two for Sensirion's commands.
+        """
+        self._native = _NativeCommandPart(address, width)
+
+    @classmethod
+    def _wrap(cls, native: _NativeCommandPart) -> CommandPart:
+        part = cls.__new__(cls)
+        part._native = native
+        return part
+
+    def answering(self, command: bytes, reply: bytes) -> CommandPart:
+        """Answer one command with a reply from now on, and return the part.
+
+        :param command: The command's bytes.
+        :param reply: What a read after it returns, in place of any reply given before.
+        :returns: This part, so calls chain.
+        """
+        self.answer(command, reply)
+        return self
+
+    def answer(self, command: bytes, reply: bytes) -> None:
+        """Answer one command with a reply from now on.
+
+        :param command: The command's bytes.
+        :param reply: What a read after it returns, in place of any reply given before.
+        """
+        self._native.answer(bytes(command), bytes(reply))
+
+    @property
+    def received(self) -> List[bytes]:
+        """Every write the part has received, oldest first: a command and any arguments."""
+        return [bytes(write) for write in self._native.received]
+
+    @property
+    def address(self) -> int:
+        """The address the part answers to."""
+        return self._native.address
+
+    @property
+    def transfers(self) -> int:
+        """How many transfers the part has served."""
+        return self._native.transfers
+
+
+#: Any simulated part: a bus takes each kind and gives each back as its own class.
+SimulatedPart = Union[I2cPart, WordPart, CommandPart]
+
+
+def _part_of(native: object) -> SimulatedPart:
+    """Wrap a native part as the class of part it is."""
+    if isinstance(native, _NativeWordPart):
+        return WordPart._wrap(native)
+    if isinstance(native, _NativeCommandPart):
+        return CommandPart._wrap(native)
+    return I2cPart._wrap(native)
+
+
+class I2cStep:
+    """One transfer a script expects, and what the part answers."""
+
+    __slots__ = ("_native",)
+
+    def __init__(self, native: _NativeStep) -> None:
+        """Wrap a native step. Use :meth:`write`, :meth:`read`, :meth:`write_read`, or
+        :meth:`fault`."""
+        self._native = native
+
+    @classmethod
+    def write(cls, address: int, data: bytes) -> I2cStep:
+        """The driver writes exactly ``data`` to the address.
+
+        :param address: The 7-bit address the write must go to.
+        :param data: The bytes the driver must send.
+        :returns: The step.
+        """
+        return cls(_NativeStep.write(address, bytes(data)))
+
+    @classmethod
+    def read(cls, address: int, reply: bytes) -> I2cStep:
+        """The driver reads from the address and receives ``reply``.
+
+        :param address: The 7-bit address the read must come from.
+        :param reply: The bytes the part answers with; the driver must ask for exactly
+            this many.
+        :returns: The step.
+        """
+        return cls(_NativeStep.read(address, bytes(reply)))
+
+    @classmethod
+    def write_read(cls, address: int, data: bytes, reply: bytes) -> I2cStep:
+        """The driver writes ``data`` and then reads ``reply`` in one transaction, the
+        shape of a register read.
+
+        :param address: The 7-bit address of the part.
+        :param data: The bytes the driver must send first, usually a register address.
+        :param reply: The bytes the part answers with.
+        :returns: The step.
+        """
+        return cls(_NativeStep.write_read(address, bytes(data), bytes(reply)))
+
+    @classmethod
+    def fault(cls, address: int, fault: I2cFault) -> I2cStep:
+        """The next transfer to the address fails, the way a missing or busy part does.
+
+        :param address: The 7-bit address the failing transfer must go to.
+        :param fault: The failure the driver sees.
+        :returns: The step.
+        """
+        return cls(_NativeStep.fault(address, I2cFault(fault).value))
+
+
+class I2cBus:
+    """One I2C bus, shared by the program and every driver built on it.
+
+    :meth:`open` opens the kernel's adapter on a Linux board; :meth:`simulated` puts
+    simulated parts of any kind on a bus, each answering at its own address;
+    :meth:`scripted` plays :class:`I2cStep` s in order and refuses any other transfer. A
+    failed transfer raises ``PamojaError`` with the reason: nothing answered at the address,
+    the script expected something else, or the kernel's own words.
+
+    >>> BME280, CHIP_ID_REGISTER, BME280_CHIP_ID = 0x76, 0xD0, 0x60
+    >>> bus = I2cBus.simulated([I2cPart(BME280).holding(CHIP_ID_REGISTER, bytes([BME280_CHIP_ID]))])
+    >>> bus.write_read(BME280, bytes([CHIP_ID_REGISTER]), 1) == bytes([BME280_CHIP_ID])
+    True
+    >>> bus.transfers
+    1
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, native: _NativeBus) -> None:
+        """Wrap a native bus. Use :meth:`open`, :meth:`simulated`, or :meth:`scripted`."""
+        self._native = native
+
+    @classmethod
+    def open(cls, path: str) -> I2cBus:
+        """Open the kernel's I2C adapter, such as ``/dev/i2c-1`` on a Raspberry Pi.
+
+        :param path: The adapter's device file.
+        :returns: The bus, with the real parts wired to it on the other end.
+        :raises PamojaError: Anywhere but Linux, and when the file cannot be opened as
+            an adapter: the interface is not turned on, or the process may not use it.
+        """
+        return cls(_NativeBus.open(path))
+
+    @classmethod
+    def simulated(cls, parts: Iterable[SimulatedPart] = ()) -> I2cBus:
+        """Make a bus of simulated parts, each answering at its own address.
+
+        :param parts: The parts on the bus, of any kind. A later part at an address an
+            earlier one holds takes its place.
+        :returns: The bus. A transfer to an address no part holds raises
+            ``PamojaError``, as nothing acknowledges it.
+        """
+        return cls(_NativeBus.simulated([part._native for part in parts]))
+
+    @classmethod
+    def scripted(cls, steps: Iterable[I2cStep]) -> I2cBus:
+        """Make a bus that plays the steps in order and refuses any other transfer.
+
+        :param steps: The transfers a driver is expected to make, and the replies.
+        :returns: The bus.
+        """
+        return cls(_NativeBus.scripted([step._native for step in steps]))
+
+    def attach(self, part: SimulatedPart) -> None:
+        """Put a copy of a part on a simulated bus, in place of any part at its address.
+
+        A driver keeps working across the change, which is how a test moves a reading on.
+
+        :param part: The part, of any kind.
+        :raises PamojaError: If the bus is not simulated.
+        """
+        self._native.attach(part._native)
+
+    @property
+    def kind(self) -> I2cBusKind:
+        """What answers on the bus."""
+        return I2cBusKind(self._native.kind)
+
+    def write(self, address: int, data: bytes) -> None:
+        """Write bytes to a part in one transaction: usually a register and its value.
+
+        :param address: The part's 7-bit address.
+        :param data: The bytes to write.
+        :raises PamojaError: If the transfer fails.
+        """
+        self._native.write(address, bytes(data))
+
+    def read(self, address: int, length: int) -> bytes:
+        """Read bytes from a part in one transaction.
+
+        :param address: The part's 7-bit address.
+        :param length: How many bytes to read.
+        :returns: The bytes.
+        :raises PamojaError: If the transfer fails.
+        """
+        return bytes(self._native.read(address, length))
+
+    def write_read(self, address: int, data: bytes, length: int) -> bytes:
+        """Write bytes and then read the reply in one transaction, with a repeated start
+        between them, which is how a register is read.
+
+        :param address: The part's 7-bit address.
+        :param data: What to write first, usually the register address.
+        :param length: How many bytes to read.
+        :returns: The reply.
+        :raises PamojaError: If the transfer fails.
+        """
+        return bytes(self._native.write_read(address, bytes(data), length))
+
+    def part(self, address: int) -> Optional[SimulatedPart]:
+        """Copy what a simulated part holds now, with whatever drivers wrote to it.
+
+        :param address: The part's address.
+        :returns: The copy, as the class of part it is, or ``None`` when the bus is not
+            simulated or no part holds the address.
+        """
+        native = self._native.part(address)
+        return None if native is None else _part_of(native)
+
+    @property
+    def transfers(self) -> int:
+        """How many transfers have been made on the bus, by the program and every driver
+        on it, including any that failed."""
+        return self._native.transfers
+
+    @property
+    def remaining(self) -> Optional[int]:
+        """How many steps a script has left, or ``None`` when the bus is not scripted."""
+        return self._native.remaining
+
+    @property
+    def waited_micros(self) -> int:
+        """How long the drivers on the bus have asked to wait, in microseconds, whether
+        or not the process slept through it."""
+        return self._native.waited_micros
+
+
+class Parity(str, enum.Enum):
+    """The parity bit each character on a serial line carries."""
+
+    #: No parity bit.
+    NONE = "None"
+    #: A bit that makes the count of ones even, what Modbus RTU asks for by default.
+    EVEN = "Even"
+    #: A bit that makes the count of ones odd.
+    ODD = "Odd"
+
+
+class SerialPortKind(str, enum.Enum):
+    """What is on the other end of a serial port."""
+
+    #: The kernel's serial device, with a real line on the other end.
+    DEVICE = "Device"
+    #: The port's own output, looped back to its input.
+    LOOPED = "Looped"
+    #: The other end of a null-modem pair.
+    PAIRED = "Paired"
+    #: A simulated device that answers each write.
+    SIMULATED = "Simulated"
+    #: A script of the writes a driver is expected to make.
+    SCRIPTED = "Scripted"
+
+
+@dataclass(frozen=True)
+class SerialSettings:
+    """A port's speed and character format: eight data bits, with the parity and stop bits
+    given.
+
+    >>> modbus = SerialSettings(9_600, Parity.EVEN)
+    >>> str(modbus), modbus.bits_per_character, modbus.character_nanos
+    ('9600 8E1', 11, 1145834)
+    """
+
+    #: The speed, in bits a second.
+    baud: int
+    #: The parity bit each character carries.
+    parity: Parity = Parity.NONE
+    #: 1 or 2 stop bits.
+    stop_bits: int = 1
+
+    def _values(self) -> tuple:
+        return (self.baud, Parity(self.parity).value, self.stop_bits)
+
+    @property
+    def bits_per_character(self) -> int:
+        """The bits one character takes on the wire: a start bit, eight data bits, the
+        parity bit if there is one, and the stop bits."""
+        return _serial_bits_per_character(*self._values())
+
+    @property
+    def character_nanos(self) -> int:
+        """How long one character takes on the wire, in nanoseconds, rounded up."""
+        return _serial_character_nanos(*self._values())
+
+    def transfer_micros(self, count: int) -> int:
+        """How long ``count`` bytes sent back to back take on the wire.
+
+        :param count: How many bytes.
+        :returns: The time in microseconds, rounded up.
+        """
+        return _serial_transfer_micros(*self._values(), count)
+
+    def __str__(self) -> str:
+        letter = {Parity.NONE: "N", Parity.EVEN: "E", Parity.ODD: "O"}[Parity(self.parity)]
+        return f"{self.baud} 8{letter}{self.stop_bits}"
+
+
+class SerialStep:
+    """One step of a scripted port: :meth:`write` for a write the program is expected to
+    make, and :meth:`read` for bytes the far end sends."""
+
+    __slots__ = ("_native",)
+
+    def __init__(self, native: _NativeSerialStep) -> None:
+        """Wrap a native step; use :meth:`write` or :meth:`read` instead."""
+        self._native = native
+
+    @classmethod
+    def write(cls, data: bytes) -> SerialStep:
+        """A write the program is expected to make, in one call.
+
+        :param data: The bytes of the write.
+        :returns: The step.
+        """
+        return cls(_NativeSerialStep.write(bytes(data)))
+
+    @classmethod
+    def read(cls, data: bytes) -> SerialStep:
+        """Bytes the far end sends, readable once every step before them has happened.
+
+        :param data: What arrives.
+        :returns: The step.
+        """
+        return cls(_NativeSerialStep.read(bytes(data)))
+
+
+class SerialPort:
+    """One serial port, shared by the program and every driver built on it.
+
+    :meth:`open` opens the kernel's serial device raw on a Linux board, :meth:`looped` is a
+    line with TX wired to RX, :meth:`pair` the two ends of a null-modem cable, and
+    :meth:`scripted` a port that checks each write against a script. A write returns once
+    the bytes have left the UART, and a read once bytes have arrived or its timeout has
+    passed. On anything but the kernel's device a read never waits: it returns at once, and
+    the time it would have waited is added to :attr:`waited_micros`. Every call releases the
+    interpreter while the line is busy, and a failure raises ``PamojaError``.
+
+    >>> gateway, node = SerialPort.pair(SerialSettings(115_200))
+    >>> node.write(b"t=21.5")
+    >>> gateway.read(16, timeout=0.1)
+    b't=21.5'
+    """
+
+    __slots__ = ("_native",)
+
+    def __init__(self, native: _NativeSerialPort) -> None:
+        """Wrap a native port; use one of the class methods instead."""
+        self._native = native
+
+    @classmethod
+    def open(cls, path: str, settings: SerialSettings) -> SerialPort:
+        """Open the kernel's serial device raw.
+
+        :param path: ``/dev/serial0`` for a Raspberry Pi's own UART, ``/dev/ttyUSB0`` or
+            ``/dev/ttyACM0`` for a USB adapter.
+        :param settings: The speed, a standard rate from 1200 to 921600, and the format.
+        :returns: The port.
+        :raises PamojaError: Anywhere but Linux, or when the device cannot be opened.
+        """
+        return cls(_NativeSerialPort.open(path, *settings._values()))
+
+    @classmethod
+    def looped(cls, settings: SerialSettings) -> SerialPort:
+        """A line looped back on itself: every byte written is waiting to be read.
+
+        :param settings: The speed and format the line runs at.
+        :returns: The port.
+        """
+        return cls(_NativeSerialPort.looped(*settings._values()))
+
+    @classmethod
+    def pair(cls, settings: SerialSettings) -> Tuple[SerialPort, SerialPort]:
+        """The two ends of a null-modem pair: what one end writes, the other reads.
+
+        :param settings: The speed and format both ends run at.
+        :returns: The two ends.
+        """
+        one, other = _NativeSerialPort.pair(*settings._values())
+        return cls(one), cls(other)
+
+    @classmethod
+    def scripted(cls, settings: SerialSettings, steps: Iterable[SerialStep]) -> SerialPort:
+        """A port that checks each write against the next step of a script.
+
+        :param settings: The speed and format the line runs at.
+        :param steps: The writes and reads, in order; reads at the start are there at once.
+        :returns: The port.
+        """
+        natives = [step._native for step in steps]
+        return cls(_NativeSerialPort.scripted(*settings._values(), natives))
+
+    @property
+    def kind(self) -> SerialPortKind:
+        """What is on the other end of the port."""
+        return SerialPortKind(self._native.kind)
+
+    @property
+    def settings(self) -> SerialSettings:
+        """The speed and character format the port runs at."""
+        baud, parity, stop_bits = self._native.settings
+        return SerialSettings(baud, Parity(parity), stop_bits)
+
+    def write(self, data: bytes) -> None:
+        """Write bytes, returning once they have left the UART.
+
+        :param data: The bytes, in order.
+        :raises PamojaError: When a script expected another write, or the device fails.
+        """
+        self._native.write(bytes(data))
+
+    def read(self, size: int, timeout: float) -> bytes:
+        """Read up to ``size`` bytes, waiting up to ``timeout`` for the first one when
+        nothing has arrived.
+
+        :param size: The most bytes to read.
+        :param timeout: How long to wait for the first byte, in seconds.
+        :returns: What arrived, empty when the timeout passed with nothing.
+        :raises PamojaError: When the device fails.
+        """
+        return self._native.read(size, _micros(timeout))
+
+    def discard_input(self) -> None:
+        """Drop whatever has arrived and not been read, as a client does before a request
+        so a stale reply cannot be taken for the new one.
+
+        :raises PamojaError: When the device fails.
+        """
+        self._native.discard_input()
+
+    def wait(self, seconds: float) -> None:
+        """Wait, as a protocol does to leave the line silent between frames: really on the
+        kernel's device, and anywhere else only counted.
+
+        :param seconds: How long.
+        """
+        self._native.wait(_micros(seconds))
+
+    @property
+    def written(self) -> int:
+        """How many bytes have been written through the port."""
+        return self._native.written
+
+    @property
+    def received(self) -> int:
+        """How many bytes have been read through the port."""
+        return self._native.received
+
+    @property
+    def waited_micros(self) -> int:
+        """How long reads have waited without an answer, and waits have waited, in
+        microseconds, whether or not the process slept through it."""
+        return self._native.waited_micros
+
+    @property
+    def remaining(self) -> Optional[int]:
+        """How many steps a script has left, or ``None`` when the port is not scripted."""
+        return self._native.remaining
+
+
+def _micros(seconds: float) -> int:
+    if seconds < 0:
+        raise ValueError("a time must be zero or more")
+    return round(seconds * 1_000_000)
+
+
+class Delay(Protocol):
+    """What paces a driver that has to wait between pin changes, such as a stepper
+    between steps. :class:`SleepDelay` really waits; :class:`DelayLog` counts every wait
+    and waits for none, for a program run with nothing plugged in."""
+
+    def delay_micros(self, micros: int) -> None:
+        """Wait, or count the wait.
+
+        :param micros: How long, in microseconds.
+        """
+        ...
+
+
+class DelayLog:
+    """A delay that records every wait it is asked for and sleeps through none of them,
+    as ``pamoja_hal::script::DelayLog`` does in Rust.
+
+    >>> delay = DelayLog()
+    >>> delay.delay_micros(480)
+    >>> delay.delay_micros(10_000)
+    >>> delay.total_micros, delay.total_millis
+    (10480, 10)
+    """
+
+    __slots__ = ("_total", "_waits")
+
+    def __init__(self) -> None:
+        """Create a log with nothing waited yet."""
+        self._waits: List[int] = []
+        self._total = 0
+
+    @property
+    def waits_micros(self) -> List[int]:
+        """Every wait asked for, in microseconds, oldest first."""
+        return list(self._waits)
+
+    @property
+    def total_micros(self) -> int:
+        """The waits added up, in microseconds."""
+        return self._total
+
+    @property
+    def total_millis(self) -> int:
+        """The waits added up, in whole milliseconds, rounded down."""
+        return self._total // 1_000
+
+    def delay_micros(self, micros: int) -> None:
+        """Record a wait.
+
+        :param micros: How long, in microseconds.
+        """
+        self._waits.append(micros)
+        self._total += micros
+
+    def clear(self) -> None:
+        """Forget every recorded wait."""
+        self._waits.clear()
+        self._total = 0
+
+
+class SleepDelay:
+    """A delay that really waits: :func:`time.sleep` for a millisecond or more, and a
+    spin on :func:`time.perf_counter_ns` for a shorter wait, which the scheduler cannot
+    keep. A sleep lasts at least what was asked and may run over by the scheduler's own
+    latency."""
+
+    __slots__ = ()
+
+    def delay_micros(self, micros: int) -> None:
+        """Wait.
+
+        :param micros: How long, in microseconds.
+        """
+        if micros >= 1_000:
+            time.sleep(micros / 1_000_000)
+            return
+        until = time.perf_counter_ns() + micros * 1_000
+        while time.perf_counter_ns() < until:
+            pass

pamoja_hal-0.2.0/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pamoja-hal"
+version = "0.2.0"
+description = "The embedded-hal traits every driver takes, a bit-banged 1-Wire bus, simulated parts and scripted buses that stand in for hardware, the Linux backends over i2c-dev, spidev, and the GPIO character device, one I2C bus and one serial port a program and its drivers share, and delays that sleep or only count."
+readme = "README.md"
+license = { text = "MIT" }
+license-files = ["LICENSE-MIT"]
+requires-python = ">=3.10"
+authors = [{ name = "molexxxx" }]
+keywords = ["pamoja", "iot", "robotics", "hal"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pamoja-native==0.2.0",
+]
+
+[project.urls]
+Repository = "https://github.com/molexxxx/pamoja"
+Documentation = "https://pamoja.molex.cloud/docs/guides/hal.html"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pamoja"]