Host and Network

Host and Network

One serial owner

The first long-running WebUI, TUI, shell, or IPC server that authenticates a board becomes its primary host. Other local clients call that primary over IPC. They must not race it for the COM port.

The primary owns discovery/reconnect, serial I/O, command validation, programming coordination, automations, integrations, and the authoritative event stream. A physical key, RF key, virtual button, board output, or host action is distributed to every active surface through that shared state path.

Edge-machine model

An edge instance is the PC physically connected to a board. Another PC on the same trusted local network can discover and interact with it through authenticated REST, JSON-RPC, standard WebSocket, Socket.IO compatibility, or a configured outbound bridge. Each edge retains ownership of its own serial device; bridges forward correlated calls and events rather than opening another machine's COM port.

Typical paths are:

Board UART -> edge primary -> local IPC/WebUI/TUI
                         -> authenticated LAN API/WebSocket
                         -> configured peer bridge -> another PCController instance

Remote initialization, backups, firmware artifacts, and executable/package transfer remain guarded operations. Verify artifact hashes, authorization policy, exact target identity, and backup evidence before permitting a write.

Exposure and authentication

Loopback is the safe default. Before binding to a LAN address:

• configure a strong token through a secret reference rather than plain committed text;
• list explicit browser origins—never use a wildcard for credentialed browser access;
• grant only the remote capabilities needed for that peer;
• keep programming, shutdown/power, virtual keys, host actions, and bridge calls denied unless explicitly authorized;
• use firewall rules that limit access to the intended private network and devices.

Durable credentials do not belong in URLs. Browser WebSocket clients use a short-lived, origin-bound subprotocol ticket; native clients use the supported authorization header.

Discovery and bridges

PCController advertises the configured service through mDNS/SSDP and can maintain authenticated outbound WebSocket or Socket.IO bridge clients. Calls use the same JSON-RPC methods as local IPC. Recursive bridge calls are rejected to prevent loops.

The generic opcode exchange can transport a newly added board operation through an older generic-capable bridge, but it still passes through authorization and safety checks. Typed APIs should be added for stable product features.

Proxy behavior

Set HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY (upper- or lower-case forms) in the process environment. Do not hardcode a proxy executable or address into source or configuration defaults. PCController preserves the caller's bypasses and adds loopback, .local, IPv4 private ranges, and IPv6 local/link-local ranges so LAN control does not travel through an Internet proxy.

Operator surfaces

• WebUI: visual state, settings, diagnostics, artifacts, and programming review.
• TUI: local keyboard-first control; local console window size/font management does not apply through SSH or another remote terminal.
• CLI/shell: one-shot operations, scripts, and support.
• IPC/REST/WebSocket/bridge: secondary processes and cross-machine integration.

See Protocol and Network API for exact routes, methods, events, and authorization gates.