dsh-linkr-bee
Verifieddsh-linkr-bee Β· v1.2.0 Β· Apache-2.0 Β· Web UI
Linkr Bee (BLE/UART wireless serial bridge) as a DeepSeek Harness plugin: a live xterm console in the right column, driven by keystrokes, plus agent tools that run commands on the target board through bee-cli.
Install
dsh plugin add dsh-linkr-bee Confirm the layer applied with dsh --profile default --dump-config β see the install guide.
Source
Tags
Creators
Readme
dsh-linkr-bee
A Linkr Bee wireless serial bridge as a DeepSeek Harness plugin: a live serial console in the Web UI's right column, plus agent tools that run commands on the target board β the person and the agent share one board and one link.
What you get
| Part | What it does |
|---|---|
| Reading / Raw views | Like the Web terminal, the panel has a Reading view (default) that hides the agent's internal probe and setup echoes and turns LINKR_RC_* completion markers into one [Agent] exit=N line, while keeping every byte of device output; Raw shows the complete stream. Switching views is local, never sends serial input, and each view keeps its own history (persisted under linkr-log-view). |
| Serial console panel | A real terminal (xterm.js) in the right column: click it and type, exactly like a local terminal. ANSI colour, cursor movement, \r progress and bracketed paste all work; dragging selects text and βC/Ctrl+C copies it. It appears as a card next to Workspace files / New terminal on the start page, and as a tab in the right column. The agent can open, focus and clear it (POST /linkr-bee/panel), and the tab puts its last screen back after a remount or a page reload. |
| Live link | While the panel is open, one resident bee-cli --serve session holds the bridge and streams the target's own bytes (watch) β a boot log, a prompt, a service printing on its own β with no polling. The panel's size is sent with resize, so full-screen programs get the right tty. |
| Agent tools | linkr_bee_console (drive this console: open, focus, clear, type text, press a named key, read what the board said, state, resize β the same pane the person is looking at), linkr_bee_exec (run a shell command on the target console and return its output and exit code), linkr_bee_query (bridge diagnostics, UART/WiFi/WebDAV/BLE-name/LAN settings, link state, doctor, scans), linkr_bee_send (deliver input and capture the reply window), linkr_bee_set (change bridge settings over the BLE management channel). |
| Connection settings | The panel's β: transport (BLE / LAN / loopback), scan for a nearby board, LAN host and token, per-call timeout, and UART settings (baud, data bits, parity, stop bits, flow control). The UART card reads the bridge's current values and applies a new baud,data,parity,stop,flow spec over the Bluetooth LE management channel; on LAN/loopback links it says so instead of offering controls that cannot work. Saving writes the plugin's row in the active profile's cordis.patch.yml through the Harness config editor, so it survives restarts. |
Requirements
DeepSeek Harness
>=0.2.0-rc.1 <0.3.0(engines.dsh).bee-cli, the Linkr Bee command-line client, version 1.2.0 or newer with thewatchandresizeoperations (this plugin's streaming depends on them; a build without them falls back to one dial per command and shows no unsolicited output). Install it from npm β the package fetches, verifies and caches the prebuilt binary for your platform:npm install -g linkr-bee-cli # puts `bee-cli` on PATH npx linkr-bee-cli --scan # or run it without installingOr build it from source:
git clone https://github.com/radxa/linkr-bee cd linkr-bee/tools/linkr-tui cargo build --release --no-default-features --features cli # install it under the name the plugin looks for rm -f target/release/bee-cli && cp target/release/bee target/release/bee-cliThe plugin resolves it as:
cliPath(below) β$LINKR_BEE_CLIβ thelinkr-bee-clilauncher this plugin depends on (it fetches and checks the release binary) βtools/linkr-tui/target/release/bee-cliin the source checkout βbee-clionPATH. Keep the same path across restarts; replace the file withrm/cprather than overwriting it in place (macOS may refuse to run a binary that was rewritten under the same inode).
Install
From the Harness UI: Plugins β install, with the spec dsh-linkr-bee.
From a terminal:
dsh plugin --profile <profile> add dsh-linkr-bee
Then restart the app (or reload the page) so the new bundle layer loads.
Use
- Open the right column (Open right sidebar) and pick Serial monitor (or click its card on the start page).
- Type. The panel sends every keystroke to the console as it is typed; the target's echo and output come back through the same link.
- The header shows what the console is attached to (
ble Β· Linkr Bee 36E8,lan, oroffline), the live tty size (86Γ45),Clearand the β connection settings. When the link drops, one compact banner says so and carries a Reconnect button that re-arms the session β and reports why if it cannot.
The console is raw: the board's own shell handles Enter, Ctrl-C, Tab, job
control and colour. If the board is sitting at a login prompt, log in by typing
in the panel.
Configuration
The panel's β writes these fields; they can also be set by hand in the profile's
cordis.patch.yml under the linkr-bee row:
| Field | Meaning |
|---|---|
transport |
ble (a nearby board over Bluetooth), lan (the bridge's WebSocket), or loopback (offline simulator, no hardware) |
bleName |
name fragment to dial; empty = the plugin scans, then dials the board it finds by name (macOS hides real MACs, so address redials do not connect). The name is remembered for five minutes and forgotten after a failed dial, so a renamed or swapped board is found again instead of being dialled forever |
bleAddress |
board MAC, e.g. EE:C7:42:34:48:CF; empty = discover by name |
lanHost / lanToken |
bridge WebSocket address (host, host:port or ws://β¦) and its 32-hex token, sent through LINKR_LAN_TOKEN. Required when transport is lan: without it the plugin refuses the call instead of silently falling back to BLE |
cliPath |
bee-cli binary (on Windows a real .exe, not the npm .cmd shim); empty = auto-detect as described above |
timeoutMs |
per-call budget for one bee-cli request (default 30000) |
sendCaptureMs |
how long linkr_bee_send keeps the link open after the line has been delivered, to capture the reply (default 1500) |
Bridge notes from the firmware: management queries and settings are Bluetooth-only; a LAN link carries serial bytes only; a board accepts two concurrent WebSocket clients and one Bluetooth connection.
Behaviour worth knowing
- Settings writes commit in order. Commands wait for pending settings writes before preparing connection arguments and retain that target until they finish. A connection change is refused while work is active or queued; later partial settings edits preserve values committed by earlier edits.
- Captured answers have limits. One-shot and resident JSON event capture retains at most 1 MiB and 4096 frames. Truncated answers are labelled, and final result/error frames take precedence over older output. Diagnostic stdout/stderr tails are separately bounded; live console output continues.
- The panel holds the Bluetooth link while it is open. Close the panel (or switch the tab away) to release it for your phone app or another tool.
- Two views of one console.
GET /linkr-bee/console/read?view=reading|rawand the SSEsnapshot/streamrecords both carry the reading-filtered text alongside the raw bytes; the panel's Reading/Raw switch picks one. The filter is display-only and fail-open: it recognises only thesh -c β¦ LINKR_RC_<nonce>wrapper this plugin's own exec path emits, and passes through anything it cannot classify so device output is never lost. - The agent shares the console you are typing in. A tool call injects its
command into the same shell; a half-typed line can be disturbed. That is the
cost of one board and one link. An agent can also open the pane itself
(
linkr_bee_console {action:"open"}), so a task that needs the console shows it instead of describing it. - The header tells you where the link stands.
β ble Β· Linkr Bee 36E8orlan/loopback/offline, the live tty size (86Γ45, the same number the target runs with),Clear, and β. When the session drops the header turns amber and a one-line banner offers Reconnect; the reason is shown inline if reconnecting fails (a wrongbee-clipath, a board out of range). - The pane keeps its screen. Switching tabs or reloading the page replays
what the board said (
GET /linkr-bee/console/read); a Clear β yours or an agent's β moves the cutoff so cleared output does not come back. - Reading and Raw share one stream position. Switching views repaints
locally cached history and sends no serial input. Reading only hides exact
command echoes and completion markers registered by the CLI's
dispatchevent; older CLIs without this metadata show the original text. Older UART replies that report only baud remain usable, with the other fields unknown. - Console output is untrusted device data. The tools say so explicitly: exit code 0 means the command completed, not that the target's state was verified, and a delivered command is not a completed one.
- UART settings are a bridge setting, not a target command. Use β β UART settings, or
GET/POST /linkr-bee/uartwith{"value":"115200,8,n,1,none"}. The agent'slinkr_bee_query target=uartandlinkr_bee_set target=uartspeak the same management channel. - Local surface only. The plugin serves
/linkr-bee/*on the Harness web server (loopback) and refuses requests whoseOriginis not the page's own host. The LAN token is never echoed back to the page β it is masked. - If the terminal cannot start, the panel says so and falls back to a plain text
renderer; the Host also records browser-side diagnostics in
$DSH_HOME/logs/linkr-bee-diag.jsonl.
Development
The plugin is two plain files: index.js (Host: tools, routes, the resident
session) and client.js (Web UI: xterm panel, generated as a CJS factory for the
Harness module loader). There is no build step. xterm.js and its fit addon are
inlined in client.js because the shell's shared module table exposes no
terminal library; both are MIT-licensed (see THIRD_PARTY_NOTICES.md).
License
Apache-2.0. client.js embeds xterm.js 6.0.0 and @xterm/addon-fit 0.11.0
(MIT); their notices are in THIRD_PARTY_NOTICES.md.