PyPI - totalsync-webinterface - Versions diffs - 0.1.1__py3-none-any.whl - Mend

totalsync-webinterface 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

totalsync_webinterface/__init__.py +8 -0
totalsync_webinterface/camera.py +163 -0
totalsync_webinterface/curses_interface.py +142 -0
totalsync_webinterface/fake_picamera.py +81 -0
totalsync_webinterface/packet.py +194 -0
totalsync_webinterface/pin_sheet.py +101 -0
totalsync_webinterface/serial_dummy.py +92 -0
totalsync_webinterface/serial_dump.py +66 -0
totalsync_webinterface/teensy_commander.py +490 -0
totalsync_webinterface/web/CanvasCamera.js +33 -0
totalsync_webinterface/web/CanvasPlot.js +71 -0
totalsync_webinterface/web/favicon.ico +0 -0
totalsync_webinterface/web/index.html +31 -0
totalsync_webinterface/web/interface.js +342 -0
totalsync_webinterface/web/reconnecting-websocket/LICENSE.txt +21 -0
totalsync_webinterface/web/reconnecting-websocket/README.md +149 -0
totalsync_webinterface/web/reconnecting-websocket/package.json +19 -0
totalsync_webinterface/web/reconnecting-websocket/reconnecting-websocket.js +365 -0
totalsync_webinterface/web/style.css +165 -0
totalsync_webinterface/web/webgl-plot/LICENSE +21 -0
totalsync_webinterface/web/webgl-plot/README.md +184 -0
totalsync_webinterface/web/webgl-plot/dist/webglplot.esm.js +619 -0
totalsync_webinterface/web/webgl-plot/package.json +42 -0
totalsync_webinterface/web_interface.py +268 -0
totalsync_webinterface/websocket_server/LICENSE +21 -0
totalsync_webinterface/websocket_server/__init__.py +1 -0
totalsync_webinterface/websocket_server/websocket_server.py +377 -0
totalsync_webinterface-0.1.1.dist-info/METADATA +41 -0
totalsync_webinterface-0.1.1.dist-info/RECORD +32 -0
totalsync_webinterface-0.1.1.dist-info/WHEEL +4 -0
totalsync_webinterface-0.1.1.dist-info/entry_points.txt +2 -0
totalsync_webinterface-0.1.1.dist-info/licenses/LICENSE +676 -0

totalsync_webinterface/__init__.py ADDED Viewed

@@ -0,0 +1,8 @@
+"""Serial reader and browser interface for the TotalSync Teensy synchroniser.
+The `totalsync` command is `teensy_commander.cli_entry`: it reads packets off the
+Teensy's serial port and serves them to the browser interface in `web/`, which this
+package ships as package data (see `web_interface.WEB_DIRECTORY`).
+"""
+__version__ = '0.1.0'

totalsync_webinterface/camera.py ADDED Viewed

@@ -0,0 +1,163 @@
+# https://picamera.readthedocs.io/en/release-1.13/recipes2.html#web-streaming
+import argparse
+import io
+import logging
+import os
+import socketserver
+from datetime import datetime
+from http import server
+from threading import Condition
+from pathlib import Path
+try:
+    import picamera
+except ImportError:
+    # picamera is Raspberry Pi only. Fall back to the stub so the module is at
+    # least importable and runnable elsewhere.
+    from . import fake_picamera as picamera
+# Create the html page for the stream
+PAGE = """\
+<html>
+<head>
+<title>MouseCam</title>
+</head>
+<body>
+<center>
+<h1>Streaming the setup</h1>
+<img src="stream.mjpg" width="1280" height="768" />
+</center>
+</body>
+</html>
+"""
+PORT = 8111
+http_stream = None
+# Define a class for the streaming output
+class StreamingOutput(object):
+    def __init__(self):
+        self.frame = None
+        self.buffer = io.BytesIO()
+        self.condition = Condition()
+    def write(self, buf):
+        if buf.startswith(b'\xff\xd8'):
+            # New frame, copy the existing buffer's content and notify all
+            # clients it's available
+            self.buffer.truncate()
+            with self.condition:
+                self.frame = self.buffer.getvalue()
+                self.condition.notify_all()
+            self.buffer.seek(0)
+        return self.buffer.write(buf)
+# Create handler for the stream, showing the stream or an error message
+class StreamingHandler(server.BaseHTTPRequestHandler):
+    def do_GET(self):
+        if self.path == '/':
+            self.send_response(301)
+            self.send_header('Location', '/index.html')
+            self.end_headers()
+        elif self.path == '/index.html':
+            content = PAGE.encode('utf-8')
+            self.send_response(200)
+            self.send_header('Content-Type', 'text/html')
+            self.send_header('Content-Length', str(len(content)))
+            self.end_headers()
+            self.wfile.write(content)
+        elif self.path == '/stream.mjpg':
+            self.send_response(200)
+            self.send_header('Age', str(0))
+            self.send_header('Cache-Control', 'no-cache, private')
+            self.send_header('Pragma', 'no-cache')
+            self.send_header('Content-Type', 'multipart/x-mixed-replace; boundary=FRAME')
+            self.end_headers()
+            try:
+                while True:
+                    with http_stream.condition:
+                        http_stream.condition.wait()
+                        frame = http_stream.frame
+                    self.wfile.write(b'--FRAME\r\n')
+                    self.send_header('Content-Type', 'image/jpeg')
+                    self.send_header('Content-Length', str(len(frame)))
+                    self.end_headers()
+                    self.wfile.write(frame)
+                    self.wfile.write(b'\r\n')
+            except Exception as e:
+                logging.warning(
+                    'Removed streaming client %s: %s',
+                    self.client_address, str(e))
+        else:
+            self.send_error(404)
+            self.end_headers()
+class StreamingServer(socketserver.ThreadingMixIn, server.HTTPServer):
+    allow_reuse_address = True
+    daemon_threads = True
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('-p', '--port', default=PORT)
+    parser.add_argument('-v', '--verbose', action='count', default=2, help="Increase logging verbosity")
+    parser.add_argument('-o', '--output', help='Output directory, created if not existing', default='/home/pi/data')
+    parser.add_argument('-f', '--fps', default=30, help='Framerate', type=float)
+    parser.add_argument('-r', '--resolution', default='600x800', help='Resolution for video written to disk')
+    parser.add_argument('-m', '--mode', default=5, help='Camera mode', type=int)
+    parser.add_argument('-I', '--iso', default=800, help='Camera iso sensitivity', type=int)
+    parser.add_argument('--downscale', default=0.5, help='Downscaling factor of MJPG web stream', type=float)
+    parser.add_argument('-R', '--rotation', default=90, help='Rotate the image (in degrees, steps of 90°', type=int)
+    cli_args = parser.parse_args()
+    # Create date and time for the filename
+    dt_obj = datetime.now()
+    timestamp = dt_obj.strftime("%Y-%b-%d_%H-%M-%S")
+    save_dir = Path(cli_args.output).resolve()
+    if not save_dir.is_dir():
+        print(save_dir)
+    assert save_dir.is_dir()
+    if not os.path.exists(save_dir):
+        os.makedirs(save_dir)
+    filename = save_dir / f'{timestamp}_picamera.h264'
+    frame_width, frame_height = map(int, cli_args.resolution.split('x'))
+    frame_width_web = int(frame_width * cli_args.downscale)
+    frame_height_web = int(frame_height * cli_args.downscale)
+    logging.debug(f'resolution: {frame_width} x {frame_height} : {frame_width_web} x {frame_height_web}')
+    with picamera.PiCamera(resolution=f'{frame_width}x{frame_height}', framerate=cli_args.fps,
+                           sensor_mode=cli_args.mode) as camera:
+        camera.rotation = cli_args.rotation
+        camera.exposure_mode = 'fixedfps'
+        camera.awb_mode = 'auto'
+        camera.awb_gains = (1.5, 1.2)
+        camera.iso = cli_args.iso
+        global http_stream
+        http_stream = StreamingOutput()
+        # record to local disk in full resolution
+        camera.start_recording(str(filename), splitter_port=2)
+        # record to stream in reduced resolution
+        camera.start_recording(http_stream, format='mjpeg', resize=(frame_width_web, frame_height_web))
+        camera.wait_recording(1)
+        try:
+            address = ('', cli_args.port)
+            http_server = StreamingServer(address, StreamingHandler)
+            http_server.serve_forever()
+        finally:
+            camera.stop_recording()
+if __name__ == '__main__':
+    main()

totalsync_webinterface/curses_interface.py ADDED Viewed

@@ -0,0 +1,142 @@
+import curses
+import logging
+import sys
+import threading
+import time
+from datetime import datetime
+class CursesHandler(logging.Handler):
+    def __init__(self, window):
+        logging.Handler.__init__(self)
+        self.window = window
+    def emit(self, record):
+        try:
+            msg = self.format(record)
+            lvl = record.levelno
+            color = 0
+            if lvl > 10:
+                color = 3
+            if lvl > 20:
+                color = 13
+            if lvl > 30:
+                color = 5
+            if color > 40:
+                color = 5
+            self.window.addstr(msg + "\n", curses.color_pair(color))
+        except (KeyboardInterrupt, SystemExit):
+            raise
+        except:
+            logging.error("curses handler error!")
+            self.handleError(record)
+class CursesUI(threading.Thread):
+    def __init__(self, commander, screen, daemon=True):
+        super(CursesUI, self).__init__(daemon=daemon)
+        self.alive = True
+        self.screen = screen
+        self.commander = commander
+        curses.start_color()
+        curses.use_default_colors()
+        num_colors = min(16, curses.COLORS)
+        for i in range(0, num_colors):
+            curses.init_pair(i+1, i, -1)
+        curses.curs_set(0)
+        curses.setsyx(-1, -1)
+        self.screen.nodelay(1)
+        maxy, maxx = self.screen.getmaxyx()
+        self.width = maxx - 1
+        begin_x = 0
+        # Title Bar
+        tbw_height = 2
+        self.tb_window = curses.newwin(tbw_height, self.width, 0, begin_x)
+        self.tb_window.scrollok(True)
+        self.tb_window.idlok(True)
+        self.tb_window.leaveok(True)
+        title_str = "Commander Teensy v3"
+        self.tb_window.addstr(0, (self.width - len(title_str)) // 2, title_str, curses.color_pair(3))
+        # Main Window
+        mw_height = 10
+        self.main_window = curses.newwin(8, self.width, tbw_height, begin_x)
+        self.main_window.scrollok(True)
+        self.main_window.idlok(True)
+        self.main_window.leaveok(True)
+        # for i in range(num_colors):
+        #     self.main_window.addstr(3, i, str(i), curses.color_pair(i))
+        # Logging Window
+        self.lw_height = maxy - mw_height - tbw_height
+        self.log_window = curses.newwin(self.lw_height, self.width, tbw_height+mw_height, begin_x)
+        self.log_window.scrollok(True)
+        self.log_window.idlok(True)
+        self.log_window.leaveok(True)
+        mh = CursesHandler(self.log_window)
+        mh.setFormatter('LogFile/'+logging.Formatter('|%(asctime)-8s|%(name)-10s|%(levelname)-7s|%(message)-s', '%H:%M:%S'))
+        self.logger = logging.getLogger("")
+        self.logger.addHandler(mh)
+        self.start()
+    def handle_packet(self, packet):
+        try:
+            w = self.main_window
+            w.erase()
+            if self.commander.serial_port != "DUMMY":
+                w.addstr(0, 2, "Serial " + self.commander.serial_port)
+            else:
+                w.addstr(0, 2, "Serial " + self.commander.serial_port, curses.color_pair(5))
+            status = self.commander.serial.is_open
+            color = curses.color_pair(3) if status else curses.color_pair(6)
+            status_txt = "OK" if status else "ERROR"
+            w.addstr(0, 10+len(self.commander.serial_port), status_txt, color)
+            w.addstr(1, 2, f"{self.commander.packets_per_second:06.1f} packets/s")
+            # Raw arrivals vs. successfully unpacked packets; a growing gap between
+            # the two means packets are coming in but not decoding.
+            w.addstr(2, 2, f"{self.commander.serial_dump.n_raw_packets} received, "
+                           f"{self.commander.n_packet} decoded")
+            w.addstr(4, 2, f"PacketID {packet.packetID}")
+            # w.refresh()
+        except KeyboardInterrupt:
+            logging.critical("INTERRUPT")
+            self.alive = False
+        except BaseException as e:
+            logging.error(f"packet printing fail: {e}")
+    def run(self):
+        while self.alive:
+            time.sleep(.1)
+            time_str = datetime.now().strftime("%H:%M:%S %d.%m.%Y")
+            self.tb_window.addstr(0, self.width-len(time_str), time_str)
+            curses.noecho()
+            if self.screen.getch() == ord('q'):
+                logging.info("User requested exit.")
+                self.alive = False
+            # try:
+            #     key = self.screen.getkey()
+            #     logging.info(key)
+            # except:
+            #     pass
+            # curses.echo()
+            self.tb_window.refresh()
+            self.main_window.refresh()
+            self.log_window.border()
+            self.log_window.refresh()
+if __name__ == '__main__':
+    screen = curses.initscr()
+    gui = CursesUI(screen=screen, commander=None, daemon=False)
+    curses.echo()

totalsync_webinterface/fake_picamera.py ADDED Viewed

@@ -0,0 +1,81 @@
+"""
+Create a fake picamera
+"""
+import time
+import numpy as np
+class BGR(object):
+    """Fake class"""
+    def __init__(self, sz):
+        self.array = np.random.rand(*sz)
+    def truncate(self, num):
+        # refreshes the fake image
+        self.array = np.random.rand(*self.array.shape)
+class PiCamera:
+    """Fake class"""
+    resolution = (0, 0)
+    def __init__(self, resolution=None, framerate=None, **options):
+        # **options absorbs the rest of the real PiCamera signature (sensor_mode,
+        # led_pin, ...); camera.py passes sensor_mode=, which would be a TypeError.
+        pass
+    def __enter__(self):
+        return self
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+    def start_preview(self, **options):
+        pass
+    def stop_preview(self):
+        pass
+    def add_overlay(self, *args, **kwargs):
+        pass
+    def remove_overlay(self, *args, **kwargs):
+        pass
+    def capture(self, output, format=None, use_video_port=False, resize=None, splitter_port=0, bayer=False, **options):
+        raise NotImplementedError
+    def start_recording(self, output, format=None, resize=None, splitter_port=1, **options):
+        pass
+    def split_recording(self, *args, **kwargs):
+        pass
+    def wait_recording(self, timeout=0, splitter_port=1):
+        if timeout:
+            time.sleep(timeout)
+    def stop_recording(self):
+        pass
+    def record_sequence(self, *args, **kwargs):
+        raise NotImplementedError
+    def capture_sequence(self, *args, **kwargs):
+        raise NotImplementedError
+    def capture_continuous(self, *args, **kwargs):
+        raise NotImplementedError
+    def close(self):
+        pass
+class array:
+    """Fake class"""
+    @staticmethod
+    def PiRGBArray(cam, size):
+        return BGR(size)

totalsync_webinterface/packet.py ADDED Viewed

@@ -0,0 +1,194 @@
+import base64
+import logging
+import struct
+import traceback
+from collections import namedtuple
+from cobs import cobs
+from serial.threaded import Packetizer
+# uint8_t type;          // 1 B, packet type
+# uint8_t size;          // 1 B, packet size
+# uint16_t crc16;        // 2 B, CRC16
+# unsigned long packetID;// 4 B, running packet count
+# unsigned long ts_start;// 4 B, gather start timestamp
+# unsigned long ts_end;  // 4 B, transmit timestamp
+# uint16_t analog[8];    // 16 B, ADC values
+# long states[8];        32 16 B, state variables (encoder, speed, etc)
+# uint16_t digitalIn;    // 2 B, digital inputs
+# uint16_t digitalOut;    // 2 B, digital outputs
+# uint8_t padding[1];    // 1 B, align to 4B
+DataPacketDesc = {'type': 'B',
+                  'size': 'B',
+                  'crc16': 'H',
+                  'packetID': 'I',
+                  'us_start': 'I',
+                  'us_end': 'I',
+                  'analog': '8H',
+                  'states': '8l',
+                  'digitalIn': '2H',
+                  'digitalOut': '3B',
+                  'padding': 'x'}
+DataPacket = namedtuple('DataPacket', DataPacketDesc.keys())
+DataPacketStruct = '<' + ''.join(DataPacketDesc.values())
+DataPacketSize = struct.calcsize(DataPacketStruct)
+Instructions = {'low': 0,
+                'high': 1,
+                'toggle': 2,
+                'pulse': 3,
+                'state': 4,
+                'unity': 5,
+                'handshake': 149,
+                'reset': 6}
+InstructionsStructs = {
+    'low': 'B',
+    'high': 'B',
+    'toggle': 'B',
+    'pulse': 'L',
+    'state': 'l',
+    'unity': 'B',
+    'reset': 'B'
+}
+CommandPacketHeaderDesc = {'type': 'B',
+                           'size': 'B',
+                           'crc16': 'H',
+                           'instruction': 'B'}
+CommandPacketHeader = namedtuple('CommandPacket', CommandPacketHeaderDesc.keys())
+CommandPacketHeaderStruct = '<' + ''.join(CommandPacketHeaderDesc.values())
+CommandPacketHeaderSize = struct.calcsize(CommandPacketHeaderStruct)
+PinPulsePacket = {'pin': 'B',
+                  'duration': 'H'}
+PinPulsePacketStruct = '<BHx'
+def pack_data_packet(packet_obj):
+    raise NotImplemented('data packing not ready.')
+def pack_command_packet(packet_obj):
+    logging.info(f'Packing CommandPacket {packet_obj}')
+    data = packet_obj['data']
+    instruction = packet_obj['instruction']
+    data_arr = b''
+    for ds in data:
+        data_arr += struct.pack('<B' + InstructionsStructs[instruction], *ds)
+    cmd_p = struct.pack(CommandPacketHeaderStruct,
+                        1, CommandPacketHeaderSize + len(data_arr), 0, Instructions[instruction])
+    arr = cmd_p + data_arr
+    logging.info(cobs.encode(arr) + b'\0');
+    return cobs.encode(arr) + b'\0'
+def pack_reset_packet():
+    logging.info(f'Packing CommandPacket ')
+    data = [(0,1)]
+    instruction = 'reset'
+    data_arr = b''
+    for ds in data:
+        data_arr += struct.pack('<B' + InstructionsStructs[instruction], *ds)
+    cmd_p = struct.pack(CommandPacketHeaderStruct,
+                        1, CommandPacketHeaderSize + len(data_arr), 0, Instructions[instruction])
+    arr = cmd_p + data_arr
+    logging.info(cobs.encode(arr) + b'\0');
+    return cobs.encode(arr) + b'\0'
+class PacketReceiver(Packetizer):
+    raw_callbacks = []
+    decoded_callbacks = []
+    packet_callbacks = []
+    def connection_made(self, transport):
+        super(PacketReceiver, self).connection_made(transport)
+    def handle_packet(self, encoded):
+        """Handle an incoming packet from the serial port. The Packetizer has stripped the
+        line-termination \0 byte from it already.
+        """
+        try:
+            assert (len(encoded))
+            for cb in self.raw_callbacks:
+                cb(encoded)
+        except BaseException as e:
+            logging.critical(e)
+        # COBS decode the array
+        try:
+            decoded = cobs.decode(encoded)
+        except cobs.DecodeError as e:
+            logging.warning(str(e))
+            return
+        try:
+            for cb in self.decoded_callbacks:
+                cb(encoded)
+        except BaseException as e:
+            logging.critical(e)
+        # Unpack given the type of data
+        packet_type = decoded[0]
+        if packet_type == 0:
+            self.unpack_data_packet(decoded)
+        elif packet_type == 1:
+            self.unpack_command_packet(decoded)
+        elif packet_type == 2:
+            logging.error(f'Received error packet {decoded}')
+        else:
+            logging.error(f'Received unknown packet type: {packet_type} in packet {decoded}')
+    def unpack_data_packet(self, arr):
+        """Handle a data packet by extracting its fields.
+        """
+        if len(arr) != DataPacketSize:
+            logging.warning(f"Incorrect data size. Is: {len(arr)}, expected: {DataPacketSize}. Packet: {arr}")
+            return
+        # stupid manual struct unpacking is stupid
+        s = struct.unpack(DataPacketStruct, arr)
+        dp = DataPacket(type=s[0], size=s[1], crc16=s[2], packetID=s[3], us_start=s[4], us_end=s[5],
+                        analog=s[6:14], states=s[14:22], digitalIn=s[22], digitalOut=s[23], padding=None)
+        # hand over packets to interested parties...
+        for fn_packet_callback in self.packet_callbacks:
+            try:
+                fn_packet_callback(dp)
+            # TODO: EVIL! DON'T! NO! NO! NO!
+            except BaseException as e:
+                logging.critical(e)
+                raise
+    def unpack_command_packet(self, arr):
+        """Handle a command packet by extracting its fields.
+        """
+        raise NotImplementedError
+        # if len(arr) != CommandPacketHeaderSize:
+        #     logging.warning(f"Incorrect data size. Is: {len(arr)}, expected: {CommandPacketHeaderSize}. Packet: {arr}")
+        #     return
+        #
+        # # stupid manual struct unpacking is stupid
+        # s = struct.unpack(CommandPacketHeaderStruct, arr)
+        # dp = CommandPacketHeader(type=s[0], size=s[1], crc16=s[2], instruction=s[3], target=s[4], message=s[5:18],
+        #                    padding=None)
+        #
+        # # hand over packets to interested parties...
+        # for fn_packet_callback in self.packet_callbacks:
+        #     try:
+        #         fn_packet_callback(dp)
+        #     except BaseException as e:
+        #         logging.critical(e)
+    def connection_lost(self, exc):
+        if exc:
+            print('Serial connection loss: ', exc)
+            logging.debug(f'Serial connection loss: {exc}')
+            traceback.print_exc()

totalsync_webinterface/pin_sheet.py ADDED Viewed

@@ -0,0 +1,101 @@
+"""Read a pinSheet.json and turn it into display labels for the web interface.
+The same file describes a recording for the .b64 reader utilities, so the channel
+names used here are the ones in the sheet's "name" fields ("digital_input_0",
+"analog_input_3", ...). Those happen to be exactly the names the web interface
+generates for its traces, which is what makes the substitution a plain lookup.
+A pin's "name" only says where it sits on the Teensy; "for" says what it is wired
+to in a given rig, and that is what the labels should show. "for" is null for the
+pins that are not used, and those keep their generated name.
+"""
+import json
+import logging
+from pathlib import Path
+def load_pin_labels(path):
+    """Map channel name -> display label for every channel the pin sheet describes.
+    Channels the sheet has no meaning for are simply absent from the result, so
+    the web interface falls back to its own name for them.
+    Raises SystemExit if the file cannot be read or is not a pin sheet. The
+    option is only ever given explicitly, so a mistyped path should be reported
+    rather than quietly ignored; individual unusable entries are only warned
+    about, since one bad line should not cost you the other labels.
+    """
+    path = Path(path)
+    try:
+        with path.open() as f:
+            sheet = json.load(f)
+    except OSError as e:
+        logging.error(f'Cannot read pin sheet {path}: {e}')
+        raise SystemExit(1)
+    except json.JSONDecodeError as e:
+        logging.error(f'Pin sheet {path} is not valid JSON: {e}')
+        raise SystemExit(1)
+    if not isinstance(sheet, dict):
+        logging.error(f'Pin sheet {path} should hold a JSON object, found {type(sheet).__name__}.')
+        raise SystemExit(1)
+    labels = _pin_labels(sheet.get('pins'), path)
+    labels.update(_state_labels(sheet.get('states'), path))
+    logging.info(f'Pin sheet {path} ({sheet.get("title", "untitled")}): '
+                 f'{len(labels)} channels labelled.')
+    return labels
+def _pin_labels(pins, path):
+    """Labels from the "pins" section, e.g. name 'digital_input_2', for 'Wheel Encoder A'."""
+    labels = {}
+    if pins is None:
+        logging.warning(f'Pin sheet {path} has no "pins" section.')
+        return labels
+    if not isinstance(pins, list):
+        logging.warning(f'Pin sheet {path}: "pins" should be a list, found '
+                        f'{type(pins).__name__}. Ignoring it.')
+        return labels
+    for entry in pins:
+        if not isinstance(entry, dict):
+            logging.warning(f'Pin sheet {path}: skipping non-object pin entry {entry!r}.')
+            continue
+        name, meaning = entry.get('name'), entry.get('for')
+        if not isinstance(name, str) or not name:
+            logging.warning(f'Pin sheet {path}: skipping pin entry without a "name": {entry!r}.')
+            continue
+        # An unused pin has "for": null, which is not an error: it just means the
+        # interface should go on calling that channel by its own name.
+        if isinstance(meaning, str) and meaning.strip():
+            labels[name] = meaning.strip()
+    return labels
+def _state_labels(states, path):
+    """Labels from the "states" section, e.g. idx 0, name 'uncorrected_distance'.
+    States have no "for" field: unlike a pin, a state's name already *is* its
+    meaning. The web interface numbers these channels states_0 ... states_7.
+    """
+    labels = {}
+    if states is None:
+        return labels
+    if not isinstance(states, list):
+        logging.warning(f'Pin sheet {path}: "states" should be a list, found '
+                        f'{type(states).__name__}. Ignoring it.')
+        return labels
+    for entry in states:
+        if not isinstance(entry, dict):
+            logging.warning(f'Pin sheet {path}: skipping non-object state entry {entry!r}.')
+            continue
+        idx, name = entry.get('idx'), entry.get('name')
+        # bool is an int subclass, and "idx": true is not an index.
+        if not isinstance(idx, int) or isinstance(idx, bool) or not isinstance(name, str) or not name.strip():
+            logging.warning(f'Pin sheet {path}: skipping unusable state entry {entry!r}.')
+            continue
+        labels[f'states_{idx}'] = name.strip()
+    return labels