brick-instruments 0.9.0__py3-none-any.whl

brick/__init__.py

@@ -0,0 +1,46 @@
+"""Host drivers for the Brick modular instrument system.
+
+One mainframe owns one serial port and hands you an object per slot:
+
+    >>> from brick import Brick
+    >>> brick = Brick('/dev/cu.usbmodem101')
+    >>> brick.slots
+    {1: DiodeReadout(slot=1), 2: ACResistanceBridge(slot=2),
+     3: IsolatedVoltageSource(slot=3), 4: None}
+
+    >>> vs = brick.slots[3]
+    >>> vs.set_voltage(0.47)
+    >>> vs.set_output(True)
+    >>> vs.get_calibration()
+
+Everything a brick offers is a method, including the facts that never
+change -- ``vs.slot()``, ``vs.type()`` -- so there is one way to call
+anything and nothing invites an assignment that would silently do nothing.
+``brick.slots`` is the one attribute, because it is what you index, and it
+is read-only.
+
+A factory-fresh brick has a blank ID EEPROM, so it arrives as a placeholder
+that says what to do:
+
+    >>> brick.slots[4]
+    Unprovisioned(slot=4) -- call .initialize(<type>); brick.types() lists them
+    >>> brick.slots[4].initialize('DiodeReadout')
+    DiodeReadout(slot=4)
+
+Published as ``brick-instruments``, imported as ``brick``.
+"""
+
+from .errors import BrickError, EepromError, SlotError
+from .mainframe import Brick, Connection, _find_port, find_bricks
+from .modules import (ACResistanceBridge, BrickModule, DiodeReadout,
+                      IsolatedVoltageSource, UnknownType, Unprovisioned)
+
+__version__ = '0.9.0'
+
+__all__ = [
+    'Brick', 'Connection', 'find_bricks',
+    'BrickModule', 'DiodeReadout', 'ACResistanceBridge',
+    'IsolatedVoltageSource', 'Unprovisioned', 'UnknownType',
+    'BrickError', 'EepromError', 'SlotError',
+    '__version__',
+]

brick/eeprom.py

@@ -0,0 +1,167 @@
+"""The bricks' ID EEPROMs: record layout, CRC32 and chunked access.
+
+Every brick carries a 24AA64 holding two records, each a 16-byte binary
+frame followed by a UTF-8 JSON document:
+
+    record      frame   payload          capacity  holds
+    identity    0x0000  0x0010-0x03FF    1008 B    type
+    data        0x0400  0x0410-0x1FFF    7152 B    calibration, date, notes
+
+This file mirrors the firmware's own ``mainframe/eeprom.py``. It is a copy,
+and copies go stale, so :func:`write_json` compares the CRC the board
+computed over what actually landed against the one computed here. That one
+check catches both a dropped chunk and these offsets drifting from the
+firmware's -- and it fails at write time rather than corrupting a record
+that reads back wrong weeks later.
+
+Everything here takes a ``brick`` whose ``_query(command, timeout=None)``
+reaches the mainframe, so it needs no serial port of its own and can be
+tested against a fake.
+"""
+
+import binascii
+import json
+import time
+
+from .errors import EepromError
+
+__all__ = ['EEPROM_RECORDS', 'crc32', 'dump', 'write_bytes', 'read_json',
+           'write_json', 'merge_calibration']
+
+FRAME_SIZE = 16
+EEPROM_RECORDS = {
+    'identity': {'index': 0, 'frame': 0x0000, 'payload': 0x0010, 'limit': 0x0400},
+    'data': {'index': 1, 'frame': 0x0400, 'payload': 0x0410, 'limit': 0x2000},
+}
+
+# One EEPROM:WRITE carries this many bytes. 32 matches the chip's page size,
+# so each chunk is a single page write; the firmware refuses more than 64 per
+# command because a longer line breaks MicroPython's own parser.
+WRITE_CHUNK = 32
+
+# EEPROM:DUMP replies are one line, and the firmware caps them at 256 bytes.
+DUMP_CHUNK = 256
+
+# EEPROM:ERASE:ALL writes all 256 pages, each waiting out its own write
+# cycle: about 2 s, during which the board answers nothing else.
+ERASE_ALL_TIMEOUT = 20.0
+
+
+def capacity(record):
+    """Usable payload bytes in a record."""
+    entry = EEPROM_RECORDS[record]
+    return entry['limit'] - entry['payload']
+
+
+def crc32(data):
+    return binascii.crc32(bytes(data)) & 0xFFFFFFFF
+
+
+def frame(brick, slot, record='identity'):
+    """A record's frame: presence, length, CRC32 and any error."""
+    return brick._query_literal(f'EEPROM:FRAME? {slot} {record}')
+
+
+def dump(brick, slot, offset=0, length=32):
+    """Raw bytes, in as many EEPROM:DUMP calls as it takes."""
+    result = bytearray()
+    while len(result) < length:
+        chunk = min(DUMP_CHUNK, length - len(result))
+        reply = brick._query(f'EEPROM:DUMP {slot} {offset + len(result)} {chunk}')
+        result += bytes(int(byte, 16) for byte in reply.split())
+    return bytes(result)
+
+
+def write_bytes(brick, slot, offset, data):
+    """Write raw bytes, one EEPROM page per command."""
+    data = bytes(data)
+    written = 0
+    while written < len(data):
+        chunk = data[written:written + WRITE_CHUNK]
+        payload = ' '.join(f'{byte:02X}' for byte in chunk)
+        brick._query(f'EEPROM:WRITE {slot} {offset + written} {payload}')
+        written += len(chunk)
+    return written
+
+
+def read_json(brick, slot, record='data'):
+    """Read and parse a record. Returns ``(document, frame)``.
+
+    ``document`` is None when the record is absent or corrupt, and the
+    frame says which.
+    """
+    header = frame(brick, slot, record)
+    if not header.get('valid'):
+        return None, header
+    payload = dump(brick, slot, EEPROM_RECORDS[record]['payload'],
+                   header['length'])
+    if crc32(payload) != header['payload_crc']:
+        return None, dict(header, valid=False,
+                          error='payload CRC32 mismatch on readback')
+    try:
+        return json.loads(payload.decode('utf-8')), header
+    except (ValueError, UnicodeError) as error:
+        return None, dict(header, valid=False,
+                          error=f'payload is not valid JSON: {error}')
+
+
+def write_json(brick, slot, document, record='data'):
+    """Serialise ``document`` here and store it in a brick's EEPROM.
+
+    Serialising on the host is deliberate. CircuitPython uses
+    single-precision floats and its ``json.dumps`` emits only about six
+    significant digits, so a board serialising its own calibration would
+    silently round it -- 123456.789012345 becomes 123457.0. Written from
+    here every digit is stored; the board then holds about seven
+    significant digits once parsed, which is 0.12 ppm on a 125 kohm
+    resistor.
+
+    The payload goes out in page-sized chunks, then EEPROM:WRITEFRAME has
+    the board compute the CRC over what actually landed. Comparing that
+    against the CRC computed here is the check described in the module
+    docstring.
+    """
+    if record not in EEPROM_RECORDS:
+        raise EepromError(f'unknown record {record!r}; records are '
+                          + ', '.join(sorted(EEPROM_RECORDS)))
+    payload = json.dumps(document, separators=(',', ':')).encode('utf-8')
+    room = capacity(record)
+    if not 0 < len(payload) <= room:
+        raise EepromError(f'{len(payload)} bytes of JSON does not fit the '
+                          f'{room} byte {record} record')
+    write_bytes(brick, slot, EEPROM_RECORDS[record]['payload'], payload)
+    header = brick._query_literal(
+        f'EEPROM:WRITEFRAME {slot} {record} {len(payload)}')
+    if not isinstance(header, dict) or not header.get('valid'):
+        raise EepromError(f'writing the {record} record frame failed: {header}')
+    expected = crc32(payload)
+    if header['payload_crc'] != expected:
+        raise EepromError(
+            f'the board computed CRC32 0x{header["payload_crc"]:08X} over '
+            f'what it stored, but the payload sent was 0x{expected:08X}. '
+            'Either a chunk went missing, or these record offsets no longer '
+            "match the firmware's.")
+    return header
+
+
+def merge_calibration(brick, slot, constants, notes=None, date=None):
+    """Merge constants into a brick's ``data`` record and return it.
+
+    Every record carries a ``date`` (YYYYMMDD) and a ``notes`` string,
+    because a constant whose provenance nobody wrote down is a constant
+    nobody can defend later. Both are set here rather than on the board
+    because they have to be: the RP2040 has no battery-backed clock.
+
+    Reads first and merges, so storing one constant does not discard
+    another, the notes, or a sensor curve kept alongside.
+    """
+    existing, _ = read_json(brick, slot, 'data')
+    document = existing if isinstance(existing, dict) else {}
+    merged = dict(document.get('calibration') or {})
+    merged.update(constants)
+    document['calibration'] = merged
+    document['date'] = int(time.strftime('%Y%m%d')) if date is None else int(date)
+    document['notes'] = (document.get('notes', '') if notes is None
+                         else str(notes))
+    write_json(brick, slot, document, 'data')
+    return document

brick/errors.py

@@ -0,0 +1,19 @@
+"""The package's exceptions.
+
+In their own module so that ``mainframe`` and ``modules`` can both raise
+them without importing each other, which they otherwise would have to.
+"""
+
+__all__ = ['BrickError', 'EepromError', 'SlotError']
+
+
+class BrickError(Exception):
+    """A command failed, or the board said something unexpected."""
+
+
+class EepromError(BrickError):
+    """A record could not be read or written."""
+
+
+class SlotError(BrickError):
+    """A slot holds nothing usable, or not what was asked for."""