klein-bt 0.8.0__py3-none-any.whl

klein/__init__.py

@@ -0,0 +1,8 @@
+"""klein — a lightweight CLI telemetry dashboard for BehaviorTree.CPP v4.
+
+Connects to a running robot node over ZeroMQ (the Groot2 publisher protocol),
+unrolls nested subtrees, and streams live status and blackboard values to an
+interactive D3.js browser dashboard. Run ``klein-bt --help`` for options.
+"""
+
+__version__ = "0.8.0"

klein/btlog.py

@@ -0,0 +1,186 @@
+"""klein.btlog — FileLogger2 ``.btlog`` files, read and written in memory.
+
+The format BehaviorTree.CPP's ``FileLogger2`` writes and Groot2 opens
+(``bt_file_logger_v2.cpp``; the header comment in ``bt_file_logger_v2.h``
+leaves out the magic and the version byte — the .cpp is authoritative).
+All little-endian::
+
+    b"BTCPP4-FileLogger2" | u8 version (1) | i32 xml_len | xml (UTF-8)
+    | i64 first_timestamp (µs since the epoch)
+    | N x 9-byte records: u48 offset_us (from first_timestamp) | u16 uid | u8 status
+
+A record is exactly a GET_TRANSITIONS record, so the packing is shared with
+``groot2_protocol``. Statuses are live NodeStatus ints (IDLE is a plain 0).
+
+``export_run`` and ``export_blackboard`` save one tree run of a ``Recording``
+(docs/protocol.md, "Saving a recording"); ``load_btlog`` turns a file and its
+sidecar back into one (``klein-bt --open``, docs/protocol.md, "Opening a file").
+"""
+
+import collections
+import itertools
+import json
+import struct
+
+from .groot2_protocol import TRANSITION_RECORD_SIZE, decode_transitions, encode_transition
+from .recording import Recording, apply_transition, diff_to_transitions
+
+MAGIC = b"BTCPP4-FileLogger2"
+VERSION = 1
+_XML_OFFSET = len(MAGIC) + 1 + 4        # the XML starts after magic, version, xml_len
+_TIMESTAMP_SIZE = 8
+
+BtlogFile = collections.namedtuple("BtlogFile", "xml first_timestamp records trailing")
+BtlogFile.__doc__ = ("A parsed ``.btlog``. ``records`` are ``(offset_us, uid, status)``; "
+                     "``trailing`` counts the bytes of an incomplete last record.")
+
+
+class BtlogError(ValueError):
+    """The data is not a FileLogger2 ``.btlog`` klein can read."""
+
+
+def read_btlog(data):
+    """Parse ``.btlog`` bytes into a ``BtlogFile``.
+
+    A trailing partial record — a robot stopped mid-write — is left out of
+    ``records`` and counted in ``trailing``, not raised.
+    """
+    if not data.startswith(MAGIC):
+        raise BtlogError("not a FileLogger2 .btlog (no BTCPP4-FileLogger2 magic)")
+    version = data[len(MAGIC):len(MAGIC) + 1]
+    if version != bytes([VERSION]):
+        shown = version[0] if version else "missing"
+        raise BtlogError(f"unknown .btlog format version {shown}")
+    xml_len = int.from_bytes(data[len(MAGIC) + 1:_XML_OFFSET], "little", signed=True)
+    if not 0 <= xml_len <= len(data) - _XML_OFFSET - _TIMESTAMP_SIZE:
+        raise BtlogError(f"XML length {xml_len} does not fit the file")
+    body = _XML_OFFSET + xml_len + _TIMESTAMP_SIZE     # where the records start
+    xml = data[_XML_OFFSET:_XML_OFFSET + xml_len].decode("utf-8")
+    (first_timestamp,) = struct.unpack_from("<q", data, body - _TIMESTAMP_SIZE)
+    records = data[body:]
+    return BtlogFile(xml, first_timestamp, decode_transitions(records),
+                     len(records) % TRANSITION_RECORD_SIZE)
+
+
+def _header(xml, first_timestamp):
+    body = xml.encode("utf-8")
+    return b"".join([MAGIC, bytes([VERSION]), struct.pack("<i", len(body)), body,
+                     struct.pack("<q", first_timestamp)])
+
+
+def write_btlog(xml, first_timestamp, records):
+    """Serialize a ``.btlog``; ``records`` are ``(offset_us, uid, status)``."""
+    return b"".join([_header(xml, first_timestamp)]
+                    + [encode_transition(*record) for record in records])
+
+
+def export_run(run, xml):
+    """One tree run (``Recording.runs()``) as ``.btlog`` bytes.
+
+    ``first_timestamp`` is the run's retained start. Replayed from all-IDLE, as
+    Groot2 and klein start a file, the file gives the recorded state at every
+    retained time: each segment opens with the transitions from the state
+    before it (all-IDLE for the first) to its retained start — the prefix at
+    offset 0, and at each restart or re-arm inside the run.
+
+    A record ``apply_transition`` ignores (an IDLE on a node already idle: an
+    arm-overlap record the baseline already held) is left out, so a reader
+    with the plain publisher rule never sees "was IDLE".
+    """
+    first = run[0].t_start
+    state = bytearray(len(run[0].baseline))     # the file's state, as written so far
+    out = bytearray(_header(xml, first))
+    for segment in run:
+        start = segment.state_at_seq(segment.start_seq)
+        opening = [(segment.t_start, uid, status)
+                   for uid, status in diff_to_transitions(state, start)]
+        recorded = ((ts, uid, status) for _seq, ts, uid, status
+                    in segment.iter_records(segment.start_seq, segment.head_seq))
+        for ts, uid, status in itertools.chain(opening, recorded):
+            if apply_transition(state, uid, status):
+                out += encode_transition(ts - first, uid, status)
+    return bytes(out)
+
+
+def export_blackboard(run, tree_id):
+    """One tree run's blackboard history as ``.bb.jsonl`` bytes: a header line,
+    then one line per change at its offset from the run's retained start.
+
+    Each segment opens with the lines that turn the previous values (none, for
+    the first) into its values at its retained start, so the file stands alone
+    after eviction and across restarts.
+    """
+    first = run[0].t_start
+    lines = [json.dumps({"klein_blackboard": 1, "first_timestamp": first, "tree_id": tree_id})]
+    values = {}                             # (board, key) -> JSON text, as of the last line
+
+    def line(t, board, key, text):
+        entry = json.dumps({"t": t - first, "board": board, "key": key})[:-1]
+        if text is None:
+            del values[board, key]
+            lines.append(f'{entry}, "removed": true}}')
+        else:
+            values[board, key] = text       # the stored JSON text goes in as it is
+            lines.append(f'{entry}, "value": {text}}}')
+
+    for segment in run:
+        track = segment.blackboard
+        if track.t_start is None:
+            continue
+        base = max(track.t_start, first)
+        at_base, later = {}, []
+        for t, board, key, text in track.changes():
+            if t <= base:
+                at_base[board, key] = text
+            else:
+                later.append((t, board, key, text))
+        for name in [name for name in values if at_base.get(name) is None]:
+            line(base, *name, None)
+        for name, text in at_base.items():
+            if text is not None and values.get(name) != text:
+                line(base, *name, text)
+        for change in later:
+            line(*change)
+    return "".join(entry + "\n" for entry in lines).encode("utf-8")
+
+
+def load_btlog(log, layout, sidecar=None):
+    """A ``Recording`` of one parsed file (``read_btlog``), as the gateway
+    would have recorded it: one ended segment from ``first_timestamp``,
+    replayed from all-IDLE as Groot2 starts a file, with its head at the last
+    record.
+
+    ``layout`` is the file's ``TreeLayout`` (``parse_layout`` of its XML),
+    the segment's layout. ``sidecar`` is the ``.bb.jsonl`` text
+    (``export_blackboard``), or None. Its lines become blackboard samples
+    holding every board in the layout's ``blackboard_names``, so a board with
+    no lines (no keys of its own) still shows, empty, as it does live. The
+    first sample is at the first line, or at the sidecar's start when it has
+    none.
+    """
+    recording = Recording()
+    segment = recording.begin_segment(layout, log.first_timestamp, bytes(layout.size))
+    recording.append([(log.first_timestamp + offset, uid, status)
+                      for offset, uid, status in log.records])
+    if sidecar is not None:
+        _load_blackboard(recording, sidecar, layout.blackboard_names)
+    recording.end_segment(segment.last_ts)
+    recording.advance_head(segment.last_ts)
+    return recording
+
+
+def _load_blackboard(recording, text, boards):
+    header, *lines = [json.loads(line) for line in text.splitlines() if line.strip()]
+    first = header["first_timestamp"]
+    values = {board: {} for board in boards}
+    by_time = collections.defaultdict(list)
+    for line in lines:
+        by_time[line["t"]].append(line)
+    for t in sorted(by_time) or [0]:
+        for line in by_time[t]:
+            entries = values.setdefault(line["board"], {})
+            if line.get("removed"):
+                entries.pop(line["key"], None)
+            else:
+                entries[line["key"]] = line["value"]
+        recording.add_blackboard(first + t, values)

klein/cli.py

@@ -0,0 +1,113 @@
+"""klein.cli — the ``klein-bt`` command: parse the flags, build the gateway
+(``klein/gateway.py``) and run it until Ctrl-C."""
+
+import argparse
+import asyncio
+import math
+import socket
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+from .btlog import BtlogError
+from .gateway import KleinGateway
+from .recording import Recording
+
+
+def _duration_us(text):
+    """``--record-buffer`` value -> µs: ``90s``, ``10m``, ``1h``; a bare number
+    is seconds, and ``0`` turns recording off."""
+    units = {"s": 1, "m": 60, "h": 3600}
+    text = text.strip().lower()
+    scale = units.get(text[-1:])
+    try:
+        value = float(text[:-1] if scale else text)
+    except ValueError:
+        value = math.nan
+    if not math.isfinite(value):
+        raise argparse.ArgumentTypeError(f"not a duration: {text!r} (try 90s, 10m, 1h)")
+    if value < 0:
+        raise argparse.ArgumentTypeError("the duration must not be negative")
+    return round(value * (scale or 1) * 1_000_000)
+
+
+def _port_available(port):
+    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    # Match the asyncio server's bind semantics (SO_REUSEADDR): reject a port
+    # only when a live listener holds it, not when harmless TIME_WAIT sockets
+    # linger from a just-closed session (which would block an immediate restart).
+    probe.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    try:
+        probe.bind(("0.0.0.0", port))
+        return True
+    except OSError:
+        return False
+    finally:
+        probe.close()
+
+
+def main_cli():
+    parser = argparse.ArgumentParser(
+        prog="klein-bt",
+        description="Live BehaviorTree.CPP v4 telemetry dashboard over ZeroMQ.",
+    )
+    parser.add_argument("--robot-host", default="127.0.0.1",
+                        help="IP address of the C++ robot node (default: 127.0.0.1)")
+    parser.add_argument("--robot-port", type=int, default=1667,
+                        help="ZeroMQ REQ/REP port on the robot (default: 1667)")
+    parser.add_argument("--port", type=int, default=8080,
+                        help="port for the klein dashboard + telemetry server (default: 8080)")
+    parser.add_argument("--no-browser", action="store_true",
+                        help="do not auto-open the system browser")
+    parser.add_argument("--record-buffer", type=_duration_us, default="10m",
+                        metavar="DURATION",
+                        help="how much recent history to record, e.g. 90s, 30m, 1h; 0 turns "
+                             "recording off and polls the robot only while a dashboard is "
+                             "open (default: 10m)")
+    parser.add_argument("--debug", action="store_true",
+                        help="serve a read-only JSON dump of the recording at /debug/state")
+    parser.add_argument("--open", metavar="FILE.btlog", type=Path,
+                        help="show a saved FileLogger2 recording (and its FILE.bb.jsonl "
+                             "blackboard, if present) instead of a robot")
+    args = parser.parse_args()
+
+    recording = None
+    if args.open is None and args.record_buffer:
+        # Size caps are Recording's defaults: 200 MiB in all, 64 MiB of it blackboard.
+        recording = Recording(keep_us=args.record_buffer)
+    gateway = KleinGateway(args.robot_host, args.robot_port, args.port,
+                           recording=recording, debug=args.debug)
+    if args.open is not None:
+        try:
+            trailing = gateway.open_file(args.open)
+        except (OSError, BtlogError, ET.ParseError, ValueError) as exc:
+            print(f"[klein] cannot open {args.open}: {exc}", file=sys.stderr)
+            sys.exit(1)
+        if trailing:
+            print(f"[klein] {args.open}: ignored a partial last record "
+                  f"({trailing} byte{'s' if trailing > 1 else ''}).")
+
+    if not _port_available(args.port):
+        print(f"[klein] port {args.port} is already in use — try a different --port.",
+              file=sys.stderr)
+        sys.exit(1)
+
+    print()
+    print("  klein — BehaviorTree.CPP telemetry")
+    if args.open is not None:
+        print(f"  file      : {args.open} (no robot)")
+    else:
+        print(f"  robot     : tcp://{args.robot_host}:{args.robot_port}")
+    print(f"  dashboard : http://localhost:{args.port}")
+    print()
+
+    try:
+        # The browser is opened from inside run(), once the server is listening,
+        # so it never races ahead of the socket being ready.
+        asyncio.run(gateway.run(open_browser=not args.no_browser))
+    except KeyboardInterrupt:
+        print("\n[klein] shutting down.")
+
+
+if __name__ == "__main__":
+    main_cli()