readerboard 0.1.1__py3-none-any.whl

readerboard/protocol/frames.py

@@ -0,0 +1,250 @@
+"""Build the byte strings the sign expects.
+
+Everything in this module is pure: bytes in, bytes out, no input or output. That
+is what makes the golden byte tests in ``tests/test_frames.py`` worth having,
+because they pin the wire format against the protocol document without needing a
+sign to be plugged in.
+
+A complete transmission looks like this:
+
+    WAKEUP  SOH  sign type  address  STX  payload  EOT
+
+The payload is one command. ``A`` writes a TEXT file and ``E`` writes a special
+function; the special function's own label follows immediately after the ``E``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from readerboard.protocol import constants as c
+
+
+class ProtocolError(ValueError):
+    """A frame could not be built as asked."""
+
+
+@dataclass(frozen=True, slots=True)
+class FileAllocation:
+    """One entry in a memory configuration.
+
+    ``capacity`` is the file's size in bytes. ``locked`` decides whether the
+    sign's own infrared keyboard may edit the file; leaving it unlocked is the
+    friendlier default for a sign hanging on a wall.
+    """
+
+    label: bytes
+    capacity: int
+    file_type: bytes = c.FILE_TYPE_TEXT
+    locked: bool = False
+    schedule: bytes = c.TEXT_SCHEDULE_ALWAYS
+
+    def __post_init__(self) -> None:
+        """Reject an allocation the sign could not accept."""
+        if len(self.label) != 1:
+            raise ProtocolError("a file label is exactly one byte, got %r" % self.label)
+        if self.label == c.FILE_PRIORITY:
+            raise ProtocolError(
+                "the priority file '0' is allocated by the sign and must not appear "
+                "in a memory configuration"
+            )
+        if not 0 < self.capacity <= 0xFFFF:
+            raise ProtocolError("file capacity must be between 1 and 65535, got %d" % self.capacity)
+        if len(self.schedule) != 4:
+            raise ProtocolError("a file schedule is exactly four bytes, got %r" % self.schedule)
+
+    def encode(self) -> bytes:
+        """Render this entry as its eleven protocol characters."""
+        lock = c.FILE_LOCKED if self.locked else c.FILE_UNLOCKED
+        return b"%s%s%s%04X%s" % (
+            self.label,
+            self.file_type,
+            lock,
+            self.capacity,
+            self.schedule,
+        )
+
+
+def packet(
+    payload: bytes,
+    *,
+    sign_type: bytes = c.SIGN_TYPE_BETABRITE,
+    address: bytes = c.SIGN_ADDRESS_BROADCAST,
+) -> bytes:
+    """Wrap a payload in the framing bytes and return the whole transmission."""
+    return c.WAKEUP + c.SOH + sign_type + address + c.STX + payload + c.EOT
+
+
+def write_text_file(
+    label: bytes,
+    body: bytes,
+    *,
+    mode: bytes = c.MODE_HOLD,
+    position: bytes = c.TEXT_POS_MIDDLE,
+) -> bytes:
+    """Build the payload that writes ``body`` into the TEXT file ``label``.
+
+    An empty ``body`` blanks the file. Writing an empty body to the priority
+    file is how an alert is released, so it is explicitly allowed.
+    """
+    if len(label) != 1:
+        raise ProtocolError("a file label is exactly one byte, got %r" % label)
+    if label == c.FILE_PRIORITY and len(body) > c.PRIORITY_FILE_CAPACITY:
+        raise ProtocolError(
+            "the priority file holds %d bytes and the sign will not let that change; "
+            "this message needs %d" % (c.PRIORITY_FILE_CAPACITY, len(body))
+        )
+    return c.COMMAND_WRITE_TEXT + label + c.SOM + position + mode + body
+
+
+def clear_priority_file() -> bytes:
+    """Build the payload that releases a priority takeover.
+
+    Writing nothing to file ``0`` is what tells the sign to go back to playing
+    its run sequence. There is no separate release command.
+    """
+    return write_text_file(c.FILE_PRIORITY, b"")
+
+
+def write_special(label: bytes, parameter: bytes = b"") -> bytes:
+    """Build the payload for a special function."""
+    if len(label) != 1:
+        raise ProtocolError("a special function label is exactly one byte, got %r" % label)
+    return c.COMMAND_WRITE_SPECIAL + label + parameter
+
+
+def clear_memory() -> bytes:
+    """Build the payload that clears the sign's memory outright.
+
+    The protocol spells this "E$" with nothing after it. It is separate from
+    :func:`set_memory_config` on purpose, so that an accidentally empty list of
+    allocations cannot wipe the sign by mistake.
+    """
+    return write_special(c.SF_SET_MEMORY_CONFIG)
+
+
+def memory_claimed(allocations: list[FileAllocation]) -> int:
+    """Bytes of the sign's memory pool a configuration would take.
+
+    The protocol charges each configured file eleven bytes of directory
+    overhead on top of its own size, and the total has to fit the pool.
+    """
+    return sum(entry.capacity + c.FILE_OVERHEAD_BYTES for entry in allocations)
+
+
+def set_memory_config(allocations: list[FileAllocation]) -> bytes:
+    """Build the payload that allocates the sign's files.
+
+    This erases every file already on the sign, so the whole pool has to be
+    described in one call. Note also that, apart from the priority file and the
+    default file ``A``, no file can be written at all until a memory
+    configuration has been written. See docs/protocol-notes.md.
+    """
+    if not allocations:
+        raise ProtocolError(
+            "a memory configuration needs at least one file; use clear_memory() to "
+            "deliberately wipe the sign"
+        )
+
+    labels = [entry.label for entry in allocations]
+    if len(set(labels)) != len(labels):
+        raise ProtocolError("a memory configuration cannot name the same file twice")
+
+    body = b"".join(entry.encode() for entry in allocations)
+    return write_special(c.SF_SET_MEMORY_CONFIG, body)
+
+
+def set_run_sequence(
+    labels: list[bytes],
+    *,
+    mode: bytes = c.RUN_SEQ_IGNORE_TIME,
+    locked: bool = False,
+) -> bytes:
+    """Build the payload that decides which TEXT files play, and in what order.
+
+    An empty ``labels`` is meaningful: it stops the sign playing anything from
+    the pool, which is what an emptied registry should look like.
+
+    The default mode ignores each file's own start and stop time. The service
+    allocates every file as always eligible, so the two modes behave the same
+    for it, but being explicit means a file that later gains a schedule does not
+    silently change how the rotation behaves.
+    """
+    for label in labels:
+        if len(label) != 1:
+            raise ProtocolError("a file label is exactly one byte, got %r" % label)
+    if len(set(labels)) != len(labels):
+        raise ProtocolError("a run sequence cannot name the same file twice")
+
+    parameter = mode + (c.FILE_LOCKED if locked else c.FILE_UNLOCKED) + b"".join(labels)
+    return write_special(c.SF_SET_RUN_SEQUENCE, parameter)
+
+
+def set_time(hour: int, minute: int) -> bytes:
+    """Build the payload that sets the sign's clock, as HHMM on a 24 hour clock."""
+    if not 0 <= hour <= 23:
+        raise ProtocolError("hour must be between 0 and 23, got %d" % hour)
+    if not 0 <= minute <= 59:
+        raise ProtocolError("minute must be between 0 and 59, got %d" % minute)
+    return write_special(c.CMD_SET_TIME, b"%02d%02d" % (hour, minute))
+
+
+def set_day_of_week(day: int) -> bytes:
+    """Build the payload that sets the sign's day of week, 1 for Sunday to 7 for Saturday."""
+    if not 1 <= day <= 7:
+        raise ProtocolError("day of week must be between 1 and 7, got %d" % day)
+    return write_special(c.CMD_SET_DAY_OF_WEEK, b"%d" % day)
+
+
+def set_time_format(military: bool) -> bytes:
+    """Build the payload that chooses a 24 hour or 12 hour clock on the sign."""
+    return write_special(c.CMD_SET_TIME_FORMAT, b"M" if military else b"S")
+
+
+# ===========================================================================
+# Reading state back from the sign.
+#
+# These exist so that divergence between what the service believes and what the
+# sign actually holds can be detected rather than assumed. Whether this sign
+# answers them through the Ethernet to RS-232 adapter is the one genuinely
+# unproven thing left; two-way traffic over that path has never been tried.
+# scripts/protocol_spike.py settles it. Until then the service reconciles by
+# re-pushing on a timer, which needs no reply.
+# ===========================================================================
+
+
+def read_special(label: bytes) -> bytes:
+    """Build the payload that asks the sign for a special function's value."""
+    if len(label) != 1:
+        raise ProtocolError("a special function label is exactly one byte, got %r" % label)
+    return c.COMMAND_READ_SPECIAL + label
+
+
+def read_memory_config() -> bytes:
+    """Ask the sign for its memory configuration table.
+
+    Note when comparing the reply against a plan: the sign hands whatever is
+    left of the memory pool to the first file in the configuration once it
+    starts running, so the first file's size will not match what was sent.
+    Compare the plan semantically, not byte for byte.
+    """
+    return read_special(c.SF_SET_MEMORY_CONFIG)
+
+
+def read_memory_pool_size() -> bytes:
+    """Ask the sign for the total and unused size of its memory pool."""
+    return read_special(c.SF_MEMORY_POOL_SIZE)
+
+
+def read_run_sequence() -> bytes:
+    """Ask the sign which files it is currently playing, and in what order."""
+    return read_special(c.SF_SET_RUN_SEQUENCE)
+
+
+def read_run_time_table() -> bytes:
+    """Ask the sign for its run time table.
+
+    The reply also carries whether a priority message is running, which is the
+    only way to ask the sign whether an alert is still up.
+    """
+    return read_special(c.SF_RUN_TIME_TABLE)

readerboard/protocol/markup.py

@@ -0,0 +1,173 @@
+"""Turn a markup string into the bytes a TEXT file holds.
+
+The message language is deliberately small: printable text, plus tokens written
+as ``<name>``. ``<red>Hello <degree>`` is a colour change, the word Hello, and a
+degree symbol.
+
+Two rules here are load bearing, and both have an obvious wrong answer.
+
+First, the cursor advances on every branch. A tokenizer that only moves forward
+inside the branch that found a closing ``>`` will spin forever on a message
+containing a bare ``<``, wedging whichever thread is rendering it. The loop body
+below always moves ``index``, whatever it decided about the character it just
+looked at.
+
+Second, text is encoded against the sign's own character table, not as UTF-8.
+The sign does not understand UTF-8, so encoding it that way puts two bytes of
+noise on the display in place of each accented letter. Characters the sign can
+render are mapped to it, and characters it cannot are either rejected or
+replaced depending on how strict the caller asked us to be.
+"""
+
+from __future__ import annotations
+
+from readerboard.protocol import constants as c
+from readerboard.protocol.tokens import MARKUP_BY_TEXT
+
+
+class MarkupError(ValueError):
+    """A message could not be rendered exactly as written."""
+
+
+# Characters outside plain ASCII that the sign can render, mapped to the single
+# byte that renders them. Taken from the extended character table in the
+# protocol document.
+EXTENDED_CHARACTERS: dict[str, bytes] = {
+    "°": c.DEGREES,
+    "¢": c.CENTS,
+    "£": c.POUNDS,
+    "¥": c.YEN,
+    "¿": c.INVERT_QUESTION,
+    "¡": c.INVERT_EXCLAIM,
+    "Ä": c.A_UMLAUT,
+    "Å": c.A_CIRCLE,
+    "Æ": c.AE_LIGATURE,
+    "Ç": c.C_TAIL,
+    "É": c.E_ACCENT,
+    "Ñ": c.N_TILDE,
+    "Õ": c.O_TILDE,
+    "Ö": c.O_UMLAUT,
+    "Ü": c.U_UMLAUT,
+    "ß": c.BETA,
+    "à": c.a_GRAVE,
+    "á": c.a_ACCENT,
+    "â": c.a_CIRCUMFLEX,
+    "ä": c.a_UMLAUT,
+    "å": c.a_CIRCLE,
+    "æ": c.ae_LIGATURE,
+    "ç": c.c_TAIL,
+    "è": c.e_GRAVE,
+    "é": c.e_ACCENT,
+    "ê": c.e_CIRCUMFLEX,
+    "ë": c.e_UMLAUT,
+    "ì": c.i_GRAVE,
+    "í": c.i_ACCENT,
+    "î": c.i_CIRCUMFLEX,
+    "ï": c.i_UMLAUT,
+    "ñ": c.n_TILDE,
+    "ò": c.o_GRAVE,
+    "ó": c.o_ACCENT,
+    "ô": c.o_CIRCUMFLEX,
+    "õ": c.o_TILDE,
+    "ö": c.o_UMLAUT,
+    "ù": c.u_GRAVE,
+    "ú": c.u_ACCENT,
+    "û": c.u_CIRCUMFLEX,
+    "ü": c.u_UMLAUT,
+    "ÿ": c.y_UMLAUT,
+}
+
+# What an unrenderable character becomes when the caller is not being strict.
+REPLACEMENT = b"?"
+
+# The tag name may only contain these, which keeps a stray "<" in prose such as
+# "a < b" from being mistaken for the start of a tag that runs to the next ">".
+_TAG_CHARACTERS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_")
+
+
+def render(message: str, *, strict: bool = True) -> bytes:
+    """Render ``message`` to sign bytes.
+
+    When ``strict`` is true an unknown tag, an unterminated tag or a character
+    the sign cannot display raises :class:`MarkupError`. When it is false each
+    of those is passed through as literal text instead, which is what the
+    simple endpoints need so that payloads that worked against the old
+    server keep working against this one.
+    """
+    out = bytearray()
+    index = 0
+    length = len(message)
+
+    while index < length:
+        char = message[index]
+
+        if char == "<":
+            tag, after = _read_tag(message, index)
+            if tag is None:
+                # Not a tag at all, just a less-than sign in the text.
+                if strict:
+                    raise MarkupError(
+                        "unterminated tag at position %d; write a complete tag such as "
+                        "<red>, or remove the '<'" % index
+                    )
+                out += _encode_character("<", strict=False)
+                index += 1
+                continue
+
+            token = MARKUP_BY_TEXT.get(tag)
+            if token is None:
+                if strict:
+                    raise MarkupError("unknown markup token %r" % tag)
+                out += _encode_text(tag, strict=False)
+            else:
+                out += token.value
+            index = after
+            continue
+
+        out += _encode_character(char, strict=strict)
+        index += 1
+
+    return bytes(out)
+
+
+def _read_tag(message: str, start: int) -> tuple[str | None, int]:
+    """Read a ``<name>`` beginning at ``start``.
+
+    Returns the tag including its brackets and the index just past it, or
+    ``(None, start)`` when what follows is not a well formed tag.
+    """
+    index = start + 1
+    length = len(message)
+    while index < length and message[index] in _TAG_CHARACTERS:
+        index += 1
+
+    if index < length and message[index] == ">" and index > start + 1:
+        return message[start : index + 1], index + 1
+
+    return None, start
+
+
+def _encode_text(text: str, *, strict: bool) -> bytes:
+    out = bytearray()
+    for char in text:
+        out += _encode_character(char, strict=strict)
+    return bytes(out)
+
+
+def _encode_character(char: str, *, strict: bool) -> bytes:
+    code = ord(char)
+    if 0x20 <= code <= 0x7E:
+        return char.encode("ascii")
+
+    mapped = EXTENDED_CHARACTERS.get(char)
+    if mapped is not None:
+        return mapped
+
+    if char == "\n":
+        return c.CR
+
+    if strict:
+        raise MarkupError(
+            "the sign cannot display %r (U+%04X); use a markup token or plain ASCII" % (char, code)
+        )
+    return REPLACEMENT

readerboard/protocol/tokens.py

@@ -0,0 +1,166 @@
+"""The vocabulary a caller can use: markup tokens, display modes, control commands.
+
+Every name here is part of the service's public surface, so renaming one is a
+breaking change for whatever is already sending it. The table covers what the
+sign can actually do rather than a convenient subset, because a mode missing
+from here is a mode nobody can reach.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from readerboard.protocol import constants as c
+
+
+@dataclass(frozen=True, slots=True)
+class Token:
+    """One named thing a caller can ask for, and the bytes it turns into."""
+
+    text: str
+    value: bytes
+    description: str
+
+
+# ===========================================================================
+# Markup tokens, written inline in a message as <name>.
+# ===========================================================================
+
+MARKUP_TOKENS: tuple[Token, ...] = (
+    Token("<red>", c.TEXT_COLOR_RED, "Set text colour to red"),
+    Token("<green>", c.TEXT_COLOR_GREEN, "Set text colour to green"),
+    Token("<amber>", c.TEXT_COLOR_AMBER, "Set text colour to amber"),
+    Token("<dimred>", c.TEXT_COLOR_DIMRED, "Set text colour to dim red"),
+    Token("<dimgreen>", c.TEXT_COLOR_DIMGREEN, "Set text colour to dim green"),
+    Token("<brown>", c.TEXT_COLOR_BROWN, "Set text colour to brown"),
+    Token("<orange>", c.TEXT_COLOR_ORANGE, "Set text colour to orange"),
+    Token("<yellow>", c.TEXT_COLOR_YELLOW, "Set text colour to yellow"),
+    Token("<rainbow1>", c.TEXT_COLOR_RAINBOW1, "Colour the whole message as a rainbow"),
+    Token("<rainbow2>", c.TEXT_COLOR_RAINBOW2, "Colour each character as a rainbow"),
+    Token("<color_mix>", c.TEXT_COLOR_MIX, "Give each character a different colour"),
+    Token("<color_auto>", c.TEXT_COLOR_AUTO, "Cycle through the colour modes"),
+    Token("<flash_on>", c.CHAR_FLASH_ON, "Characters after this token flash"),
+    Token("<flash_off>", c.CHAR_FLASH_OFF, "Characters after this token stop flashing"),
+    Token("<wide_on>", c.WIDE_CHARS_ON, "Characters after this token are wide"),
+    Token("<wide_off>", c.WIDE_CHARS_OFF, "Characters after this token are normal width"),
+    Token(
+        "<dbl_height_on>",
+        c.DBL_HEIGHT_CHARS_ON,
+        "Characters after this token are double height",
+    ),
+    Token("<dbl_height_off>", c.DBL_HEIGHT_CHARS_OFF, "Return to single height characters"),
+    Token("<fixed_width>", c.FIXED_WIDTH_ON, "Left justify and make text fixed width; put this first"),
+    Token("<proportional>", c.FIXED_WIDTH_OFF, "Return to proportionally spaced text"),
+    Token("<degree>", c.XC_DEGREES, "Degree symbol"),
+    Token("<block>", c.BLOCK_CHAR, "A solid square block character"),
+    Token("<half_space>", c.TILDE, "A half width space"),
+    Token("<time>", c.CURTIME_INSERT, "Insert the sign's current time"),
+    Token("<week_day>", c.CURDATE_WEEKDAYY, "Insert the current day of the week"),
+    Token("<date>", c.CURDATE_MMDDYY_SLASH, "Insert the current date as MM/DD/YY"),
+    Token("<date_dmy>", c.CURDATE_DDMMYY_SLASH, "Insert the current date as DD/MM/YY"),
+    Token("<date_long>", c.CURDATE_MMMDDYYYY, "Insert the current date as MMM.DD, YYYY"),
+    Token("<newline>", c.CR, "Start a new line"),
+    Token("<new_page>", c.NEW_PAGE, "Start the next display page"),
+    Token("<no_hold_speed>", c.NO_HOLD_SPEED, "Do not pause after the mode finishes"),
+    Token("<speed1>", c.SPEED_1, "Set the scroll speed to 1, the slowest"),
+    Token("<speed2>", c.SPEED_2, "Set the scroll speed to 2"),
+    Token("<speed3>", c.SPEED_3, "Set the scroll speed to 3"),
+    Token("<speed4>", c.SPEED_4, "Set the scroll speed to 4"),
+    Token("<speed5>", c.SPEED_5, "Set the scroll speed to 5, the fastest"),
+)
+
+
+# ===========================================================================
+# Display modes, chosen per message rather than written inline.
+# ===========================================================================
+
+DISPLAY_MODES: tuple[Token, ...] = (
+    Token(
+        "HOLD",
+        c.MODE_HOLD,
+        "Hold the message still, unless it is wider than the sign, in which case "
+        "the sign scrolls it repeatedly",
+    ),
+    Token("FLASH", c.MODE_FLASH, "Hold the message still and flash it repeatedly"),
+    Token("ROTATE", c.MODE_ROTATE, "Scroll the message across the sign repeatedly"),
+    Token("ROLLUP", c.MODE_ROLLUP, "Push the old message up with the new one"),
+    Token("ROLLDOWN", c.MODE_ROLLDOWN, "Push the old message down with the new one"),
+    Token("ROLLLEFT", c.MODE_ROLLLEFT, "Push the old message left with the new one"),
+    Token("ROLLRIGHT", c.MODE_ROLLRIGHT, "Push the old message right with the new one"),
+    Token("WIPEUP", c.MODE_WIPEUP, "Wipe the new message up over the old one"),
+    Token("WIPEDOWN", c.MODE_WIPEDOWN, "Wipe the new message down over the old one"),
+    Token("WIPELEFT", c.MODE_WIPELEFT, "Wipe the new message left over the old one"),
+    Token("WIPERIGHT", c.MODE_WIPERIGHT, "Wipe the new message right over the old one"),
+    Token("ROLLIN", c.MODE_ROLLIN, "Push the new message inward"),
+    Token("ROLLOUT", c.MODE_ROLLOUT, "Push the new message outward"),
+    Token("WIPEIN", c.MODE_WIPEIN, "Wipe the new message inward over the old one"),
+    Token("WIPEOUT", c.MODE_WIPEOUT, "Wipe the new message outward over the old one"),
+    Token("COMPRESSED_ROTATE", c.MODE_CMPRSROT, "Scroll the message at half width"),
+    Token("AUTO", c.MODE_AUTO, "Let the sign pick a mode at random"),
+    Token("TWINKLE", c.MODE_TWINKLE, "Twinkle the message"),
+    Token("SPARKLE", c.MODE_SPARKLE, "Sparkle the new message over the old one"),
+    Token("SNOW", c.MODE_SNOW, "Snow the new message onto the sign"),
+    Token("INTERLOCK", c.MODE_INTERLOCK, "Interlock the new message over the old one"),
+    Token("SWITCH", c.MODE_SWITCH, "Switch the old message off and the new one on, character by character"),
+    Token("SLIDE", c.MODE_SLIDE, "Slide characters in one at a time, right to left"),
+    Token("SPRAY", c.MODE_SPRAY, "Spray the message on right to left"),
+    Token("STARBURST", c.MODE_STARBURST, "Explode the new message onto the sign"),
+    Token("WELCOME", c.MODE_WELCOME, "Display a script \"Welcome\""),
+    Token("SLOTMACHINE", c.MODE_SLOTMACHINE, "Display slot machine reels"),
+    Token("NEWSFLASH", c.MODE_NEWSFLASH, "Display a \"Newsflash\" animation"),
+    Token("TRUMPET", c.MODE_TRUMPET, "Display a trumpet animation"),
+    Token("THANKYOU", c.MODE_THANKYOU, "Display a script \"Thank You\""),
+    Token("NOSMOKING", c.MODE_NOSMOKING, "Display a \"No Smoking\" animation"),
+    Token("DRINKDRIVE", c.MODE_DRINKDRIVE, "Display a \"Don't Drink and Drive\" animation"),
+    Token("FISH", c.MODE_FISH, "Display swimming fish"),
+    Token("FIREWORKS", c.MODE_FIREWORKS, "Display a fireworks animation"),
+    Token("BALLOONS", c.MODE_BALLOONS, "Display a balloon animation"),
+    Token("CHERRYBOMB", c.MODE_CHERRYBOMB, "Display a cherry bomb animation"),
+)
+
+
+# ===========================================================================
+# Control commands, sent on their own rather than as part of a message.
+# ===========================================================================
+
+CONTROL_COMMANDS: tuple[Token, ...] = (
+    Token(
+        "SET_TIME",
+        c.CMD_SET_TIME,
+        "Set the sign's internal clock. The parameter is the time as HHMM on a 24 hour clock",
+    ),
+    Token(
+        "SET_TIME_FORMAT",
+        c.CMD_SET_TIME_FORMAT,
+        "Set how the sign renders the time. The parameter is 'S' for standard or 'M' for military",
+    ),
+    Token(
+        "SET_DAY_OF_WEEK",
+        c.CMD_SET_DAY_OF_WEEK,
+        "Set the sign's day of the week. The parameter is a single digit, "
+        "1 for Sunday through 7 for Saturday",
+    ),
+)
+
+
+# ===========================================================================
+# Vertical position of text within a TEXT file.
+# ===========================================================================
+
+TEXT_POSITIONS: tuple[Token, ...] = (
+    Token("MIDDLE", c.TEXT_POS_MIDDLE, "Centre the text vertically"),
+    Token("TOP", c.TEXT_POS_TOP, "Begin the text at the top of the sign"),
+    Token("BOTTOM", c.TEXT_POS_BOTTOM, "Place the text immediately below the top"),
+    Token("FILL", c.TEXT_POS_FILL, "Centre vertically and use every available line"),
+)
+
+
+MARKUP_BY_TEXT: dict[str, Token] = {token.text: token for token in MARKUP_TOKENS}
+MODE_BY_NAME: dict[str, Token] = {token.text: token for token in DISPLAY_MODES}
+COMMAND_BY_NAME: dict[str, Token] = {token.text: token for token in CONTROL_COMMANDS}
+POSITION_BY_NAME: dict[str, Token] = {token.text: token for token in TEXT_POSITIONS}
+
+
+def describe(tokens: tuple[Token, ...], key: str) -> list[dict[str, str]]:
+    """Render a token table as the list of dicts the enumeration endpoints return."""
+    return [{key: token.text, "description": token.description} for token in tokens]

readerboard/services/__init__.py

@@ -0,0 +1 @@
+"""What the sign is asked to show: the registry, alerts, and the clock."""