Files
MeshCore/tools/hil/ethernet_kiss_probe.py
T

336 lines
15 KiB
Python

#!/usr/bin/env python3
"""Byte-exact Ethernet-over-KISS RF probe; no flashing or radio configuration.
TRANSMITS RF through the two explicitly selected KISS endpoints. Configure the
isolated lab radios first: 909.5 MHz / 500 kHz / SF5 / CR5, low TX power. This
script never changes those settings, opens Companion port 5000, or creates TAPs.
Examples (TCP port forwards may point at another computer or the Mercerwood Pi):
python3 ethernet_kiss_probe.py --a tcp://192.168.4.1:5003 --b tcp://127.0.0.1:15003
python3 ethernet_kiss_probe.py --a tcp://192.168.4.1:5003 --b serial:///dev/ttyUSB0
python3 ethernet_kiss_probe.py --plan
Works with Companion KISS-over-TCP and a stock port-0 KISS raw-Ethernet peer.
Checksums in generated ARP/IPv4/UDP/TCP/ICMP frames are real. Passing synthetic
TCP frames is NOT a TCP connection or an SSH test; use Linux TAP/tncattach and a
real SSH session separately. --duplex intentionally overlaps half-duplex RF TX
and is a stress test, not the baseline. No automatic retries conceal RF loss.
"""
from __future__ import annotations
import argparse
from collections import Counter
from datetime import datetime, timezone
import hashlib
import ipaddress
import json
import queue
import socket
import struct
import threading
import time
from urllib.parse import urlparse
from serial_session import assert_port_idle, open_configured_session
FEND, FESC, TFEND, TFESC = 0xC0, 0xDB, 0xDC, 0xDD
def checksum(data: bytes) -> int:
if len(data) % 2:
data += b"\0"
total = sum(struct.unpack("!" + "H" * (len(data) // 2), data))
while total >> 16:
total = (total & 0xFFFF) + (total >> 16)
return ~total & 0xFFFF
def kiss_encode(frame: bytes, *, port: int = 0) -> bytes:
if type(port) is not int or port not in (0, 1):
raise ValueError("Select KISS data port 0 or 1")
return bytes((FEND, port << 4)) + frame.replace(b"\xdb", b"\xdb\xdd").replace(
b"\xc0", b"\xdb\xdc") + bytes((FEND,))
class KissDecoder:
"""Bounded streaming decoder: ignore control frames and reject bad escapes."""
def __init__(self, port: int = 0, control=None):
if type(port) is not int or port not in (0, 1):
raise ValueError("Select KISS data port 0 or 1")
self.port = port
self.control = control
self.buffer = bytearray()
self.started = self.escaped = self.discard = False
self.errors = 0
def feed(self, data: bytes) -> list[bytes]:
frames = []
for byte in data:
if byte == FEND:
if self.started and self.buffer and not self.discard:
if self.escaped:
self.errors += 1
elif self.buffer[0] == self.port << 4:
frames.append(bytes(self.buffer[1:]))
elif self.buffer[0] & 15 and self.control is not None:
self.control(self.buffer[0], bytes(self.buffer[1:]))
self.buffer.clear()
self.started = True
self.escaped = self.discard = False
elif not self.started or self.discard:
continue
elif self.escaped:
self.escaped = False
if byte not in (TFEND, TFESC):
self.errors += 1
self.discard = True
else:
self.buffer.append(FEND if byte == TFEND else FESC)
elif byte == FESC:
self.escaped = True
else:
self.buffer.append(byte)
if len(self.buffer) > 256:
self.errors += 1
self.discard = True
return frames
def make_frame(kind: str, size: int, sequence: int, reverse: bool = False) -> bytes:
"""Produce independently identifiable, valid network test frames up to 255B."""
source = bytes.fromhex("0200c0db0001")
destination = bytes.fromhex("0200c0db0002")
src_ip = ipaddress.ip_address("192.0.2.1").packed
dst_ip = ipaddress.ip_address("192.0.2.2").packed
if reverse:
source, destination = destination, source
src_ip, dst_ip = dst_ip, src_ip
if kind == "arp":
# Vary sender protocol address to distinguish every repeated ARP probe.
src_ip = bytes((192, 0, (sequence >> 8) & 255, sequence & 255))
arp = struct.pack("!HHBBH", 1, 0x0800, 6, 4, 1)
arp += source + src_ip + b"\0" * 6 + dst_ip
return b"\xff" * 6 + source + b"\x08\x06" + arp + b"\0" * max(0, size - 42)
minimum = {"raw": 14, "udp": 42, "icmp": 42, "tcp": 54}[kind]
if not minimum <= size <= 255:
raise ValueError(f"{kind} frame requires {minimum}..255 bytes")
payload_size = size - minimum
seed = b"ETHK" + struct.pack("!I?", sequence, reverse) + bytes((FEND, FESC))
payload = (seed + bytes(range(256))) * ((payload_size // 267) + 1)
payload = payload[:payload_size]
if kind == "raw":
# Even a minimum 14-byte frame must be unique across repetitions:
# otherwise a delayed duplicate could impersonate a later probe.
source = source[:2] + struct.pack("!I", sequence)
return destination + source + b"\x88\xb5" + payload
protocol = {"udp": 17, "tcp": 6, "icmp": 1}[kind]
if kind == "udp":
transport = struct.pack("!HHHH", 49152, 22, 8 + len(payload), 0) + payload
elif kind == "tcp":
transport = struct.pack("!HHIIHHHH", 49152, 22, sequence, 0, 0x5002, 4096, 0, 0) + payload
else:
transport = struct.pack("!BBHHH", 8, 0, 0, 0xC0DB, sequence & 0xFFFF) + payload
pseudo = src_ip + dst_ip + struct.pack("!BBH", 0, protocol, len(transport))
check = checksum(transport if kind == "icmp" else pseudo + transport)
offset = {"udp": 6, "tcp": 16, "icmp": 2}[kind]
# UDP checksum zero means disabled; wire representation of computed zero is FFFF.
if kind == "udp" and not check:
check = 0xFFFF
transport = transport[:offset] + struct.pack("!H", check) + transport[offset + 2:]
header = struct.pack("!BBHHHBBH4s4s", 0x45, 0, 20 + len(transport), sequence & 0xFFFF,
0x4000, 64, protocol, 0, src_ip, dst_ip)
header = header[:10] + struct.pack("!H", checksum(header)) + header[12:]
return destination + source + b"\x08\x00" + header + transport
CASES = (("raw", 14), ("arp", 60), ("icmp", 60), ("udp", 64), ("tcp", 74),
("udp", 244), ("raw", 255), ("tcp", 255))
class KissEndpoint:
def __init__(self, url: str, baud: int = 115200):
self.url = url
self.decoder = KissDecoder()
self.received = queue.Queue(maxsize=256)
self.overflow = 0
self.error = None
self.closed = threading.Event()
self.serial = None
self.socket = None
parsed = urlparse(url)
if parsed.scheme == "tcp":
self.socket = socket.create_connection((parsed.hostname, parsed.port or 5003), timeout=5)
self.socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
self.socket.settimeout(0.1)
elif parsed.scheme == "serial":
import serial # Optional: pure TCP/--plan needs only Python stdlib.
port = (parsed.netloc + parsed.path) if parsed.netloc else parsed.path
if port.startswith("/COM"):
port = port[1:]
self.serial = serial.Serial()
self.serial.baudrate = baud
self.serial.timeout = self.serial.write_timeout = 0.1
self.serial.dtr = self.serial.rts = False
self.serial.port = port
assert_port_idle(port)
open_configured_session(self.serial)
else:
raise ValueError("endpoint must be tcp://host:port or serial:///device")
self.thread = threading.Thread(target=self._read, daemon=True)
self.thread.start()
def _read(self):
try:
while not self.closed.is_set():
try:
data = self.socket.recv(1024) if self.socket else self.serial.read(1024)
except socket.timeout:
continue
if not data and self.socket:
raise ConnectionError("KISS TCP peer disconnected")
for frame in self.decoder.feed(data):
try:
self.received.put_nowait((frame, time.monotonic()))
except queue.Full:
self.overflow += 1
except Exception as error:
if not self.closed.is_set():
self.error = str(error)
def send(self, frame: bytes, fragment: int = 0):
encoded = kiss_encode(frame)
step = fragment or len(encoded)
for at in range(0, len(encoded), step):
chunk = encoded[at:at + step]
if self.socket:
self.socket.sendall(chunk)
elif self.serial.write(chunk) != len(chunk):
raise IOError("short serial write")
def receive(self, timeout: float):
if self.error:
raise ConnectionError(self.error)
try:
return self.received.get(timeout=timeout)
except queue.Empty:
return None
def close(self):
self.closed.set()
if self.socket:
self.socket.close()
if self.serial:
self.serial.close()
self.thread.join(timeout=1)
def run_probe(a, b, *, count=3, timeout=3.0, interval=0.05, duplex=False, fragment=0):
report = {"started_utc": datetime.now(timezone.utc).isoformat(),
"baseline": "909.5 MHz / 500 kHz / SF5 / CR5 (operator configured; not verified)",
"duplex_stress": duplex, "retries": 0, "transfers": [], "unexpected": []}
endpoints = {"a": a, "b": b}
sequence = 0
for repetition in range(count):
for kind, size in CASES:
pending = []
for source, destination in (("a", "b"), ("b", "a")):
sequence += 1
frame = make_frame(kind, size, sequence, source == "b")
item = {"source": source, "destination": destination, "repetition": repetition,
"kind": kind, "size": len(frame), "sequence": sequence,
"sha256": hashlib.sha256(frame).hexdigest(), "received": False,
"sent_hex": frame.hex()}
sent = time.monotonic()
endpoints[source].send(frame, fragment)
pending.append((item, frame, sent))
if not duplex:
_collect(endpoints, pending, timeout, report)
pending = []
time.sleep(interval)
if pending:
_collect(endpoints, pending, timeout, report)
time.sleep(interval)
counts = Counter()
for item in report["transfers"]:
direction = item["source"] + "_to_" + item["destination"]
counts[direction + "_attempted"] += 1
counts[direction + "_received"] += bool(item["received"])
report["counts"] = dict(counts)
report["passed"] = all(item["received"] for item in report["transfers"])
report["note"] = "Exact Ethernet bytes verified; this is not an established TCP/SSH session."
return report
def _collect(endpoints, pending, timeout, report):
deadline = max(item[2] for item in pending) + timeout
while any(not item[0]["received"] for item in pending) and time.monotonic() < deadline:
for name, endpoint in endpoints.items():
received = endpoint.receive(min(0.01, max(0, deadline - time.monotonic())))
if received is None:
continue
frame, timestamp = received
match = next((item for item in pending
if item[0]["destination"] == name and item[1] == frame
and not item[0]["received"]), None)
if match:
match[0].update(received=True, received_hex=frame.hex(),
latency_ms=round((timestamp - match[2]) * 1000, 3))
else:
report["unexpected"].append({"at": name, "size": len(frame), "hex": frame.hex()})
report["transfers"].extend(item[0] for item in pending)
def main(argv=None):
parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument("--a", help="first KISS TCP or serial endpoint")
parser.add_argument("--b", help="second KISS TCP or serial endpoint")
parser.add_argument("--baud", type=int, default=115200)
parser.add_argument("--count", type=int, default=3, help="repetitions per frame type and direction")
parser.add_argument("--timeout", type=float, default=3.0)
parser.add_argument("--interval", type=float, default=0.05)
parser.add_argument("--fragment", type=int, default=0, help="split host KISS writes into N-byte chunks")
parser.add_argument("--duplex", action="store_true", help="simultaneous TX collision stress test")
parser.add_argument("--report", help="save complete byte-exact JSON evidence")
parser.add_argument("--plan", action="store_true", help="show cases without opening any endpoint")
args = parser.parse_args(argv)
if args.count <= 0 or args.timeout <= 0 or args.interval < 0 or args.fragment < 0:
parser.error("count/timeout must be positive; interval/fragment must be nonnegative")
if args.plan:
print(json.dumps({"cases": CASES, "frames_each_direction": args.count * len(CASES),
"radio_settings": "909.5 MHz / 500 kHz / SF5 / CR5; manually verified"}, indent=2))
return 0
if not args.a or not args.b:
parser.error("both --a and --b are required, unless using --plan")
if args.a == args.b:
parser.error("--a and --b must be different endpoints")
a = b = None
try:
a = KissEndpoint(args.a, args.baud)
b = KissEndpoint(args.b, args.baud)
result = run_probe(a, b, count=args.count, timeout=args.timeout, interval=args.interval,
duplex=args.duplex, fragment=args.fragment)
result["endpoints"] = {"a": args.a, "b": args.b}
result["host_diagnostics"] = {
name: {"decode_errors": endpoint.decoder.errors, "queue_overflows": endpoint.overflow}
for name, endpoint in (("a", a), ("b", b))}
result["passed"] = result["passed"] and not any(
value for diag in result["host_diagnostics"].values() for value in diag.values())
output = json.dumps(result, indent=2)
if args.report:
with open(args.report, "w", encoding="utf-8") as destination:
destination.write(output + "\n")
print(output)
return 0 if result["passed"] else 1
finally:
if b:
b.close()
if a:
a.close()
if __name__ == "__main__":
raise SystemExit(main())