API Reference¶

Auto-generated from the source docstrings. Everything below is importable from the top-level package, e.g. from franklinwh_direct_connect_api import LocalClient.

High-level client¶

The friendliest entry point: connect, log in, call named reads.

franklinwh_direct_connect_api.client.LocalClient `module-attribute` ¶

LocalClient = DirectConnectClient

Transport¶

Lower-level framed TCP client (login + request/response, full Frame objects).

franklinwh_direct_connect_api.transport.LocalTransport `module-attribute` ¶

LocalTransport = DirectConnectTransport

franklinwh_direct_connect_api.transport.TransportError ¶

Bases: RuntimeError

Protocol¶

Cipher, frame encode/decode, the streaming reader, and the pcap reader.

franklinwh_direct_connect_api.protocol.Frame `dataclass` ¶

verify ¶

verify() -> bool

True if declared len/crc match the dataArea exactly as received.

franklinwh_direct_connect_api.protocol.encode_frame ¶

encode_frame(cmd_type: int, equip_no: str, data_area: Any, *, type: int = 0, time_stamp: int = 0, snno: int = 0, seed: int | None = None, cipher: bool = True) -> bytes

Build a complete on-the-wire frame.

seed defaults to the value appropriate for equip_no. Pass cipher=False for the cleartext cloud-REST body.

franklinwh_direct_connect_api.protocol.decode_frame ¶

decode_frame(raw: bytes, *, cipher: bool = True, seed: int | None = None) -> Frame

Parse one complete frame (cleartext header + (ciphered) remainder).

franklinwh_direct_connect_api.protocol.detect_seed ¶

detect_seed(cipher: bytes) -> int

Recover the seed from a ciphered region (plaintext[0] is always '"').

franklinwh_direct_connect_api.protocol.FrameStream ¶

Feed raw bytes from one direction of a TCP connection; pull complete Frames.

Handles frames split across reads and several frames per read. The seed is detected per frame, so logins and normal frames decode transparently.

franklinwh_direct_connect_api.protocol.iter_pcap_frames ¶

iter_pcap_frames(path: str, port: int = 9000, cipher: bool = True) -> Iterator[Frame]

Yield decoded Frames from a classic-format pcap, with TCP reassembly.

Command catalog¶

franklinwh_direct_connect_api.catalog.Cmd ¶

Bases: IntEnum

Known request cmdType codes (the reply is value + 1).

franklinwh_direct_connect_api.catalog.CmdInfo `dataclass` ¶

franklinwh_direct_connect_api.catalog.describe ¶

describe(cmd_type: int) -> str

Human-readable label for a request or response cmdType.

franklinwh_direct_connect_api.catalog.response_for ¶

response_for(cmd_type: int) -> int | None

The response code paired with a request code.

Known requests use the catalogued response. Unknown odd requests fall back to the protocol convention (response = request + 1) so a caller can still match the reply frame — important when probing un-catalogued cmdTypes. Returns None for even (non-request) codes.

Discovery (LAN scan)¶

franklinwh_direct_connect_api.discover.scan ¶

scan(targets: Iterable[str], *, ports: tuple[int, ...] = (PORT_SENDMQTT, PORT_MODBUS), timeout: float = 0.5, workers: int = 128, probe: bool = True) -> list[HostResult]

Scan targets; return one HostResult per host with an open target port.

Raises KeyboardInterrupt (after cancelling in-flight threads) if the user hits Ctrl-C so the caller can print a clean exit message.

franklinwh_direct_connect_api.discover.HostResult `dataclass` ¶

franklinwh_direct_connect_api.discover.expand_targets ¶

expand_targets(spec: str) -> list[str]

Expand a target spec into host strings.

Accepts a single host/IP, a CIDR (10.0.0.0/24), a hyphen range (10.0.0.1-10.0.0.50), or a comma-separated mix of the above.

Raises ValueError for tokens that look like bare integers (e.g. 502 instead of an IP address) to catch common confusion between ports and hosts.

franklinwh_direct_connect_api.discover.default_gateway ¶

default_gateway() -> str | None

Best-effort guess of the current default-gateway IP (the hotspot gateway, when joined to the FranklinWH AP). Uses a UDP socket trick — no traffic is actually sent. Returns the local /24's .1 as a heuristic.

franklinwh_direct_connect_api.discover.probe_sendmqtt ¶

probe_sendmqtt(host: str, port: int = PORT_SENDMQTT, timeout: float = 2.0) -> dict | None

Confirm a sendMqtt broker by performing the 1101 login and reading 1102. Returns the manifest dataArea on success, else None.

franklinwh_direct_connect_api.discover.probe_modbus ¶

probe_modbus(host: str, port: int = PORT_MODBUS, timeout: float = 1.0) -> bool

Send a minimal Modbus read and verify a valid MBAP response.

Emulator¶

franklinwh_direct_connect_api.emulator.Emulator ¶

A threaded fake broker. Use as a context manager or call serve_forever().