scietex.hal.dac 0.1.0__tar.gz

scietex_hal_dac-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anton Bondarenko
+
+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.

scietex_hal_dac-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: scietex.hal.dac
+Version: 0.1.0
+Summary: Digital-to-analog converters and digital potentiometers
+Author-email: Anton Bondarenko <bond.anton@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Anton Bondarenko
+        
+        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.
+Project-URL: Homepage, https://github.com/bond-anton/scietex.hal.dac
+Project-URL: Bug Tracker, https://github.com/bond-anton/scietex.hal.dac/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: BDPotentiometer<1.0.0,>=0.4.0
+Requires-Dist: scietex.hal.spi<1.0.0,>=0.1.0
+Provides-Extra: spi
+Requires-Dist: scietex.hal.spi[spi]; extra == "spi"
+Provides-Extra: gpiozero
+Requires-Dist: scietex.hal.spi[gpiozero]; extra == "gpiozero"
+Provides-Extra: dev
+Requires-Dist: tox>=4.46.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff==0.17.4; extra == "lint"
+Requires-Dist: ty==0.0.99; extra == "lint"
+Dynamic: license-file
+
+# scietex.hal.dac
+
+Digital-to-analog converters: a `DAC` device owns its output channels, and each
+channel converts between a raw code and a scaled output. The package ships the
+Microchip MCP4xx1 dual digital potentiometers, exposed as grounded resistor
+dividers driven over a plain SPI transport.
+
+The abstraction is unit-neutral: the device reference is a full scale in volts
+for a voltage device and in amperes for a current device, and a channel may
+override it. Scaled outputs stay `None` while no reference is configured.
+
+## Parts
+
+| Part | Codes | Wiper storage |
+| --- | --- | --- |
+| MCP4231 | 7-bit, `0..127` | volatile |
+| MCP4241 | 7-bit, `0..127` | non-volatile |
+| MCP4251 | 8-bit, `0..255` | volatile |
+| MCP4261 | 8-bit, `0..255` | non-volatile |
+
+The non-volatile parts keep a wiper value across power cycles, but this package
+has no commit path: only the volatile register is written, exactly as on the
+volatile parts.
+
+## Install
+
+```bash
+pip install scietex.hal.dac[spi]        # Linux spidev backend
+pip install scietex.hal.dac[gpiozero]   # gpiozero backend
+```
+
+The base package installs without either backend. A device built from the
+default keywords needs `spidev`; pin keywords (`clock_pin`, `mosi_pin`,
+`miso_pin`, `select_pin`) need `gpiozero`. A missing backend raises
+`ImportError` naming the extra to install.
+
+## Wiring
+
+| Signal | Connection |
+| --- | --- |
+| SCLK | SPI clock |
+| SDI | SPI MOSI |
+| SDO | SPI MISO |
+| CS | SPI chip select |
+| V_DD | Supply, 2.7 V to 5.5 V |
+| V_SS | Ground |
+
+Each wiper is a three-terminal divider: terminal A and terminal B are the ends
+of the resistor, W is the wiper. One end is tied to ground and the other to the
+reference, so the wiper voltage is a fraction of that reference.
+
+## Usage
+
+```python
+from scietex.hal.dac import MCP4251
+
+device = MCP4251(port=0, device=1, reference=3.3)  # /dev/spidev0.1
+try:
+    code = device.channel(0).value  # raw 8-bit code, 0..255
+    voltage = device.channel(0).voltage
+    print(code, voltage)
+finally:
+    device.close()
+```
+
+`MCP4251(port=0, device=1, reference=3.3)` is also a context manager; leaving the
+`with` block closes the transport:
+
+```python
+with MCP4251(port=0, device=1, reference=3.3) as device:
+    print(device.read_all())
+```
+
+Constructor keywords:
+
+| Keyword | Meaning |
+| --- | --- |
+| `r_ab` | Total resistance in ohms; 5k, 10k, 50k, or 100k (default 10k) |
+| `channels` | Channels to expose, 1..2; omitted uses both |
+| `reference` | Full-scale voltage in volts, or omitted while unknown |
+| `grounded` | Terminal tied to ground, `"B"` (default) or `"A"` |
+| `transport` (alias `spi`) | Any object with `transfer(tx)` and `close()` |
+| `port`, `device` | spidev bus and chip select |
+| `clock_pin`, `mosi_pin`, `miso_pin`, `select_pin` | gpiozero pin wiring |
+| `label`, `log_level` | Logger name and level |
+
+`invert` and `max_value` are not part of the constructor: the wiper is always
+built uninverted, and the code range is fixed by the part. Passing either
+keyword raises `TypeError`.
+
+## Codes and outputs
+
+`channel.value` is the raw code the wiper register holds. It is a live read:
+every access is a new bus transaction, nothing is cached. The range is
+`0..max_code`, which is `127` on a 7-bit part and `255` on an 8-bit part.
+
+`channel.output` scales that code by the reference (grounded B shown here; see
+[Grounding](#grounding)):
+
+```
+output = code / max_code * reference
+```
+
+With no reference configured, `output` is `None` — the library will not guess a
+reference. Setting `device.reference = 3.3` later starts scaling new readings;
+the codes themselves never change. `device.v_ref` and `channel.v_ref` are
+aliases.
+
+The setter clamps instead of rejecting: an output below zero becomes the bottom
+of the scale (code 0 when grounded B) and an output above the reference becomes
+the top code. Setting `output` while no reference is configured raises
+`DACReferenceError`.
+
+## Grounding
+
+`grounded="B"` makes the output rise with the code: code 0 is 0 V, the top code
+is the reference. `grounded="A"` mirrors the curve: code 0 is the reference and
+the top code is 0 V. The raw `value` is the same under either wiring; only the
+scaled `output` changes direction.
+
+## Geometry
+
+| Part | Channels | Resolution | Top code |
+| --- | --- | --- | --- |
+| MCP4231 | 2 | 7 | 127 |
+| MCP4241 | 2 | 7 | 127 |
+| MCP4251 | 2 | 8 | 255 |
+| MCP4261 | 2 | 8 | 255 |
+
+`device.channels` is a tuple in index order and `channel(n)` raises `IndexError`
+outside the range. A part built with `channels=1` exposes channel 0 only.
+
+## Reading and writing
+
+```python
+codes = device.read_all()  # one code per channel
+written = device.write_all((0, 128))
+```
+
+Both return tuples in index order. Every element is a separate bus transaction —
+the calls read and write the device, they do not replay a cached buffer.
+
+A single write is two transactions: the wiper command followed by a register
+read-back, so the value a channel reports afterwards is what the device
+returned, not what the caller submitted. `write_all` validates the whole
+sequence before the first transaction, so a rejected code cannot leave the
+device partially updated.
+
+## Errors
+
+- `TransportError` and `TransportClosed` (from `scietex.hal.spi`) mean the bus
+  transaction failed or the transport was already closed.
+- `DACCodeError` (a `ValueError`) means a raw code is outside `0..max_code`.
+- `DACReferenceError` (a `ValueError`) means an output was requested while no
+  reference is configured.
+- A malformed device answer is rejected by the wrapped potentiometer with a
+  `ValueError` naming the frame.
+
+## Testing
+
+```bash
+pytest                 # unit tests, no hardware needed
+RUN_HARDWARE_TESTS=1 pytest tests/test_hardware.py
+```
+
+The unit tests drive a scripted transport and never open a real bus. The
+hardware test needs an MCP4251 on `/dev/spidev0.1` and is skipped unless
+`RUN_HARDWARE_TESTS=1` is set; CI never enables it.
+
+Other checks:
+
+```bash
+tox -e format,lint,type
+```
+
+## License
+
+This project is licensed under the **MIT License** - see the LICENSE file for
+details.

scietex_hal_dac-0.1.0/README.md

@@ -0,0 +1,179 @@
+# scietex.hal.dac
+
+Digital-to-analog converters: a `DAC` device owns its output channels, and each
+channel converts between a raw code and a scaled output. The package ships the
+Microchip MCP4xx1 dual digital potentiometers, exposed as grounded resistor
+dividers driven over a plain SPI transport.
+
+The abstraction is unit-neutral: the device reference is a full scale in volts
+for a voltage device and in amperes for a current device, and a channel may
+override it. Scaled outputs stay `None` while no reference is configured.
+
+## Parts
+
+| Part | Codes | Wiper storage |
+| --- | --- | --- |
+| MCP4231 | 7-bit, `0..127` | volatile |
+| MCP4241 | 7-bit, `0..127` | non-volatile |
+| MCP4251 | 8-bit, `0..255` | volatile |
+| MCP4261 | 8-bit, `0..255` | non-volatile |
+
+The non-volatile parts keep a wiper value across power cycles, but this package
+has no commit path: only the volatile register is written, exactly as on the
+volatile parts.
+
+## Install
+
+```bash
+pip install scietex.hal.dac[spi]        # Linux spidev backend
+pip install scietex.hal.dac[gpiozero]   # gpiozero backend
+```
+
+The base package installs without either backend. A device built from the
+default keywords needs `spidev`; pin keywords (`clock_pin`, `mosi_pin`,
+`miso_pin`, `select_pin`) need `gpiozero`. A missing backend raises
+`ImportError` naming the extra to install.
+
+## Wiring
+
+| Signal | Connection |
+| --- | --- |
+| SCLK | SPI clock |
+| SDI | SPI MOSI |
+| SDO | SPI MISO |
+| CS | SPI chip select |
+| V_DD | Supply, 2.7 V to 5.5 V |
+| V_SS | Ground |
+
+Each wiper is a three-terminal divider: terminal A and terminal B are the ends
+of the resistor, W is the wiper. One end is tied to ground and the other to the
+reference, so the wiper voltage is a fraction of that reference.
+
+## Usage
+
+```python
+from scietex.hal.dac import MCP4251
+
+device = MCP4251(port=0, device=1, reference=3.3)  # /dev/spidev0.1
+try:
+    code = device.channel(0).value  # raw 8-bit code, 0..255
+    voltage = device.channel(0).voltage
+    print(code, voltage)
+finally:
+    device.close()
+```
+
+`MCP4251(port=0, device=1, reference=3.3)` is also a context manager; leaving the
+`with` block closes the transport:
+
+```python
+with MCP4251(port=0, device=1, reference=3.3) as device:
+    print(device.read_all())
+```
+
+Constructor keywords:
+
+| Keyword | Meaning |
+| --- | --- |
+| `r_ab` | Total resistance in ohms; 5k, 10k, 50k, or 100k (default 10k) |
+| `channels` | Channels to expose, 1..2; omitted uses both |
+| `reference` | Full-scale voltage in volts, or omitted while unknown |
+| `grounded` | Terminal tied to ground, `"B"` (default) or `"A"` |
+| `transport` (alias `spi`) | Any object with `transfer(tx)` and `close()` |
+| `port`, `device` | spidev bus and chip select |
+| `clock_pin`, `mosi_pin`, `miso_pin`, `select_pin` | gpiozero pin wiring |
+| `label`, `log_level` | Logger name and level |
+
+`invert` and `max_value` are not part of the constructor: the wiper is always
+built uninverted, and the code range is fixed by the part. Passing either
+keyword raises `TypeError`.
+
+## Codes and outputs
+
+`channel.value` is the raw code the wiper register holds. It is a live read:
+every access is a new bus transaction, nothing is cached. The range is
+`0..max_code`, which is `127` on a 7-bit part and `255` on an 8-bit part.
+
+`channel.output` scales that code by the reference (grounded B shown here; see
+[Grounding](#grounding)):
+
+```
+output = code / max_code * reference
+```
+
+With no reference configured, `output` is `None` — the library will not guess a
+reference. Setting `device.reference = 3.3` later starts scaling new readings;
+the codes themselves never change. `device.v_ref` and `channel.v_ref` are
+aliases.
+
+The setter clamps instead of rejecting: an output below zero becomes the bottom
+of the scale (code 0 when grounded B) and an output above the reference becomes
+the top code. Setting `output` while no reference is configured raises
+`DACReferenceError`.
+
+## Grounding
+
+`grounded="B"` makes the output rise with the code: code 0 is 0 V, the top code
+is the reference. `grounded="A"` mirrors the curve: code 0 is the reference and
+the top code is 0 V. The raw `value` is the same under either wiring; only the
+scaled `output` changes direction.
+
+## Geometry
+
+| Part | Channels | Resolution | Top code |
+| --- | --- | --- | --- |
+| MCP4231 | 2 | 7 | 127 |
+| MCP4241 | 2 | 7 | 127 |
+| MCP4251 | 2 | 8 | 255 |
+| MCP4261 | 2 | 8 | 255 |
+
+`device.channels` is a tuple in index order and `channel(n)` raises `IndexError`
+outside the range. A part built with `channels=1` exposes channel 0 only.
+
+## Reading and writing
+
+```python
+codes = device.read_all()  # one code per channel
+written = device.write_all((0, 128))
+```
+
+Both return tuples in index order. Every element is a separate bus transaction —
+the calls read and write the device, they do not replay a cached buffer.
+
+A single write is two transactions: the wiper command followed by a register
+read-back, so the value a channel reports afterwards is what the device
+returned, not what the caller submitted. `write_all` validates the whole
+sequence before the first transaction, so a rejected code cannot leave the
+device partially updated.
+
+## Errors
+
+- `TransportError` and `TransportClosed` (from `scietex.hal.spi`) mean the bus
+  transaction failed or the transport was already closed.
+- `DACCodeError` (a `ValueError`) means a raw code is outside `0..max_code`.
+- `DACReferenceError` (a `ValueError`) means an output was requested while no
+  reference is configured.
+- A malformed device answer is rejected by the wrapped potentiometer with a
+  `ValueError` naming the frame.
+
+## Testing
+
+```bash
+pytest                 # unit tests, no hardware needed
+RUN_HARDWARE_TESTS=1 pytest tests/test_hardware.py
+```
+
+The unit tests drive a scripted transport and never open a real bus. The
+hardware test needs an MCP4251 on `/dev/spidev0.1` and is skipped unless
+`RUN_HARDWARE_TESTS=1` is set; CI never enables it.
+
+Other checks:
+
+```bash
+tox -e format,lint,type
+```
+
+## License
+
+This project is licensed under the **MIT License** - see the LICENSE file for
+details.

scietex_hal_dac-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scietex.hal.dac"
+dynamic = ["version"]
+description = "Digital-to-analog converters and digital potentiometers"
+authors = [{ name = "Anton Bondarenko", email = "bond.anton@gmail.com" }]
+license = { file = "LICENSE" }
+readme = "README.md"
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.12",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+dependencies = ["BDPotentiometer >= 0.4.0, < 1.0.0", "scietex.hal.spi >= 0.1.0, < 1.0.0"]
+
+[project.urls]
+"Homepage" = "https://github.com/bond-anton/scietex.hal.dac"
+"Bug Tracker" = "https://github.com/bond-anton/scietex.hal.dac/issues"
+
+[project.optional-dependencies]
+spi = ["scietex.hal.spi[spi]"]
+gpiozero = ["scietex.hal.spi[gpiozero]"]
+dev = ["tox>=4.46.0"]
+test = ["pytest"]
+lint = ["ruff==0.17.4", "ty==0.0.99"]
+
+[tool.setuptools.dynamic]
+version = { attr = "scietex.hal.dac.version.__version__" }
+
+[tool.setuptools.package-data]
+"scietex.hal.dac" = ["py.typed"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E4","E7","E9","F","W","I","B","C4","SIM","UP","PLC0415","PLR0913","PLR0917"]
+ignore = ["E501","SLF001"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["PLC0415"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+docstring-code-format = false
+
+[tool.ty.environment]
+python-version = "3.10"
+
+[tool.ty.analysis]
+replace-imports-with-any = ["spidev.**", "gpiozero.**"]

scietex_hal_dac-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

scietex_hal_dac-0.1.0/src/scietex/hal/dac/__helpers.py

@@ -0,0 +1,195 @@
+"""Internal validation helpers shared by the package.
+
+These functions are not part of the public API. They check the type of an
+argument first, raising `TypeError` for anything that is not a real number, and
+its value second, raising `ValueError` for infinities, `NaN`, and values outside
+the requested range.
+"""
+
+from math import isnan
+from numbers import Integral, Real
+
+
+def check_number(num: float | int | Real) -> float | int:
+    """
+    Check that `num` is a finite real number.
+
+    Infinity and `NaN` are rejected. `bool` is rejected as well even though it
+    is an `int` subclass: `True` and `False` are flags, not measurements, and
+    accepting them as numbers hides caller mistakes. Both `+0.0` and `-0.0` are
+    returned as `0.0`; integers are returned as int, all other numbers as float.
+
+    :param num: variable to check.
+    :return: Unchanged `num` as int or float.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is infinite or `NaN`.
+    """
+    if isinstance(num, bool):
+        raise TypeError(
+            f"Expected a finite integer or float number, not bool {num!r} "
+            f"of type {type(num)}"
+        )
+    if not isinstance(num, Real):
+        raise TypeError(f"Expected a finite integer or float number, got {type(num)}")
+    if isinstance(num, Integral):
+        return int(num)
+    if num in [float("inf"), float("-inf")]:
+        raise ValueError(f"Expected a finite integer or float number, got {num}")
+    if isnan(num):
+        raise ValueError("Expected a finite integer or float number, not NaN")
+    if num == 0:
+        return 0.0
+    return float(num)
+
+
+def check_integer(num: float | int | Real) -> int:
+    """
+    Check that `num` is an integer and convert it to int.
+
+    :param num: Number (either int or float) to be checked.
+    :return: int representation of `num`.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is infinite, `NaN`, or has a fractional part.
+    """
+    num = check_number(num)
+    if isinstance(num, float) and not num.is_integer():
+        raise ValueError(f"Expected an integer number, got {num}")
+    return int(num)
+
+
+def check_bool(value: bool) -> bool:
+    """
+    Check that `value` is a boolean.
+
+    :param value: variable to check.
+    :return: Unchanged `value` as bool.
+    :raises TypeError: If `value` is not a boolean.
+    """
+    if not isinstance(value, bool):
+        raise TypeError(f"Expected a boolean, got {value!r} of type {type(value)}")
+    return value
+
+
+LABEL_MAX_LENGTH = 64
+
+
+def check_label(value: str) -> str:
+    """
+    Check that `value` is a non-empty string usable as a channel label.
+
+    Non-string input is rejected instead of coerced, so a label can never be
+    confused with a channel number. Surrounding whitespace is stripped and the
+    stripped text is returned, so `" a "` and `"a"` are the same label and an
+    all-whitespace string is empty.
+
+    :param value: Label to check.
+    :return: Stripped label as str.
+    :raises TypeError: If `value` is not a str.
+    :raises ValueError: If `value` is empty after stripping, or longer than
+        `LABEL_MAX_LENGTH` characters.
+    """
+    if not isinstance(value, str):
+        raise TypeError(f"Expected a string label, got {value!r} of type {type(value)}")
+    text = value.strip()
+    if not text:
+        raise ValueError("Expected a non-empty label")
+    if len(text) > LABEL_MAX_LENGTH:
+        raise ValueError(
+            f"Expected a label of at most {LABEL_MAX_LENGTH} characters, "
+            f"got {len(text)}"
+        )
+    return text
+
+
+def check_positive(num: float | int) -> float | int:
+    """
+    Check that `num` is a positive number.
+
+    `bool` is rejected as a type error even though it is an `int` subclass; pass
+    `1` explicitly when a numeric flag is intended.
+
+    :param num: Either float or int number.
+    :return: `num` unchanged.
+    :raises TypeError: If `num` is not a real number, or is a `bool`.
+    :raises ValueError: If `num` is zero, negative, infinite, or `NaN`.
+    """
+    num = check_number(num)
+    if num <= 0:
+        raise ValueError(f"Expected a positive number, got {num}")
+    return num
+
+
+def clamp(
+    value: float | int, min_value: float | int, max_value: float | int
+) -> float | int:
+    """
+    Clamp `value` to the range between `min_value` and `max_value`.
+
+    The bounds may be passed in any order: swapped bounds are normalized before
+    the comparison. A float `value` always stays a float, even when it is
+    clamped to an int bound. All three arguments reject `bool` even though it
+    is an `int` subclass; pass `0` or `1` explicitly when a numeric flag is
+    intended.
+
+    :param value: Either float or int number to be coerced.
+    :param min_value: Lower coerce range boundary.
+    :param max_value: Upper coerce range boundary.
+    :return: Value coerced to the given range.
+    :raises TypeError: If an argument is not a real number, or is a `bool`.
+    :raises ValueError: If an argument is infinite or `NaN`.
+    """
+    value = check_number(value)
+    min_value = check_number(min_value)
+    max_value = check_number(max_value)
+    if min_value > max_value:
+        min_value, max_value = max_value, min_value
+    if value < min_value:
+        if isinstance(value, float):
+            return float(min_value)
+        return min_value
+    if value > max_value:
+        if isinstance(value, float):
+            return float(max_value)
+        return max_value
+    return value
+
+
+def check_reference(value: float | None) -> float | None:
+    """
+    Check an optional reference: `None` passes through, a number must be positive.
+
+    The reference is unit-neutral: it is a full-scale value in volts for a
+    voltage output and in amperes for a current output, so only its positivity
+    is enforced here.
+
+    :param value: Reference value, or None when the scaling is unknown.
+    :return: `None`, or the reference as float.
+    :raises TypeError: If `value` is not a real number, or is a `bool`.
+    :raises ValueError: If `value` is zero, negative, infinite, or `NaN`.
+    """
+    if value is None:
+        return None
+    return float(check_positive(value))
+
+
+def check_grounded(value: str) -> str:
+    """
+    Check the terminal a divider output is grounded at.
+
+    Only `"A"` and `"B"` are meaningful: grounding B makes the output rise with
+    the code, grounding A makes it fall. Anything else is rejected instead of
+    coerced, so a typo cannot silently pick a direction.
+
+    :param value: Terminal name, either `"A"` or `"B"`.
+    :return: Unchanged terminal name.
+    :raises TypeError: If `value` is not a str.
+    :raises ValueError: If `value` is neither `"A"` nor `"B"`.
+    """
+    if not isinstance(value, str):
+        raise TypeError(
+            f'Expected "A" or "B" as a grounded terminal, '
+            f"got {value!r} of type {type(value)}"
+        )
+    if value not in ("A", "B"):
+        raise ValueError(f'Expected "A" or "B" as a grounded terminal, got {value!r}')
+    return value