From 1761c20f228aecbcd08005d7162e58b55de45475 Mon Sep 17 00:00:00 2001
From: mikecarper <mikecarper@gmail.com>
Date: Sun, 13 Sep 2026 13:44:43 -0700
Subject: [PATCH] Add Companion picocom connection and recovery instructions to
 picker

---
 docs/_javascript/firmware_picker.js | 11 ++++++++++-
 docs/firmware_picker.md             | 25 +++++++++++++++++++++++++
 2 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/docs/_javascript/firmware_picker.js b/docs/_javascript/firmware_picker.js
index 2cd734e6..e01e5a9a 100644
--- a/docs/_javascript/firmware_picker.js
+++ b/docs/_javascript/firmware_picker.js
@@ -1089,6 +1089,15 @@
       }
       section("Restore the selected logging mode", actions, loggingNote);
     }
+    if (companion && ["full", "usb", "usb-ble"].includes(profile.mode)) {
+      const picocom = "picocom -b 115200 --imap spchex --initstring $'\\r+++MESHCORE-TERM-START\\r' /dev/ttyACM0";
+      section("Companion USB terminal (Linux / Bash)", [
+        { label: "Connect", commands: [picocom],
+          text: "Run this in Bash on the Linux computer connected to the radio. The init string opens the ASCII CLI; the leading carriage return clears an unfinished input line. spchex displays binary control bytes safely during the transition." },
+        { label: "Recover scrambled terminal", commands: ["reset", picocom],
+          text: "First exit picocom with Ctrl+A, then Ctrl+X. Run these commands in your Linux shell: reset repairs the terminal display, then picocom reconnects with safe input mapping." },
+      ], "Replace /dev/ttyACM0 with your radio's port, such as /dev/ttyACM1 or /dev/ttyUSB0. Use the primary USB data interface (00 when multiple interfaces appear), and close other apps using that port. At the radio prompt, run version and board to identify the node. Exit picocom with Ctrl+A, then Ctrl+X.");
+    }
     if (!info) return sections;
     if (full || infrastructure) {
       toggle("Device power saving", "set powersaving", "get powersaving",
@@ -1181,7 +1190,7 @@
     panel.appendChild(links);
     if (isFullCompanion(profile) || ["repeater", "room", "sensor"].includes(profile.role)) {
       panel.appendChild(createElement("p", "Use a data-capable USB cable and 115200 baud. Full Companion and infrastructure start in ASCII mode. " + (profile.role === "companion"
-        ? "If already in binary mode, send +++MESHCORE-TERM-START. Use board and version to identify the node."
+        ? "Open Companion USB terminal below for Linux connection and recovery commands. Use board and version to identify the node."
         : "Use board and ver to identify the node.")));
     }
     if (!profile.controls) panel.appendChild(createElement("p", "Additional hardware controls have not been verified for this exact release image. Use the role guide for those settings."));
diff --git a/docs/firmware_picker.md b/docs/firmware_picker.md
index cd27f81b..75b9c579 100644
--- a/docs/firmware_picker.md
+++ b/docs/firmware_picker.md
@@ -294,6 +294,31 @@ it while the Repeater/Room Server bridge is running; check `get mqtt.running`.
 The workaround is not added to nRF52 directions. See [logging by role](role_feature_switches.md)
 for the saved settings and the original firmware's USB sleep issue.
 
+## Companion USB terminal on Linux
+
+Full, USB and USB + Bluetooth Companion results include **Companion USB terminal
+(Linux / Bash)** under **Restore your settings after flashing**, with copyable
+connection and recovery commands.
+
+Run this in Bash on the Linux computer connected to your radio:
+
+```bash
+picocom -b 115200 --imap spchex \
+  --initstring $'\r+++MESHCORE-TERM-START\r' \
+  /dev/ttyACM0
+```
+
+Replace `/dev/ttyACM0` with your radio's port, such as `/dev/ttyACM1` or
+`/dev/ttyUSB0`. Use the primary USB data interface (`00` when multiple interfaces
+appear), and close other apps using it. The init string opens the ASCII CLI;
+its leading carriage return clears an unfinished input line. `--imap spchex`
+displays binary control bytes safely during the transition.
+
+If the terminal display is scrambled, exit picocom with **Ctrl+A, then Ctrl+X**,
+run `reset` in your Linux shell, then reconnect with the command above. At the
+radio prompt, run `version` and `board` to identify the node. See the
+[Companion USB mode guide](terminal_chat_cli.md#companion-usb-mode).
+
 ## Installation methods
 
 | File | Use |