Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

fix(pro): re-plug itself when the USB link is stuck, console on the driver (#1711)

0xdiego250df48fc38a45
diff --git a/devices/harness-pro/firmware/main/cable/cable_link.c b/devices/harness-pro/firmware/main/cable/cable_link.c
index 5ea9a745f..e4f2b5c24 100644
--- a/devices/harness-pro/firmware/main/cable/cable_link.c
+++ b/devices/harness-pro/firmware/main/cable/cable_link.c
@@ -6,6 +6,7 @@
#include <string.h>
#include "driver/usb_serial_jtag.h"
+#include "driver/usb_serial_jtag_vfs.h"
#include "esp_log.h"
#include "esp_timer.h"
#include "last_words.h"
@@ -13,6 +14,7 @@
#include "freertos/FreeRTOS.h"
#include "freertos/semphr.h"
#include "freertos/task.h"
+#include "hal/usb_serial_jtag_ll.h"
static const char *TAG = "cable";
@@ -71,6 +73,10 @@ static const char *TAG = "cable";
// the screen.
#define LOG_WRITE_WAIT_MS 5
+// How long cable_link_replug holds D+ low. A host sees a detach within microseconds and debounces the attach for 100 ms,
+// so this is a sure unplug without being a long one.
+#define REPLUG_LOW_MS 100
+
// Reader task stack: STACK_CABLE_LINK (task_stacks.h). The frame callback runs on this task, so it carries whatever
// the message layer does — JSON parsing, Pod's feeds, and during a firmware install esp_ota_write() plus a SHA-256
// over the image read back out of flash. The host proxy (test_pro_cable.c) measured the parser at 6.9 KB on Linux
@@ -232,12 +238,19 @@ bool cable_link_start(cable_frame_cb cb, cable_tick_cb tick, void *ctx)
return false;
}
+ // The console writes through the driver from here on, so the driver's ISR is the only writer of the TX FIFO. The
+ // no-driver console wrote the FIFO directly and raced the ISR, which skips its "FIFO empty" interrupt when it finds
+ // the FIFO full: a candidate for the cold-start link that sent nothing until a replug. Bounded like before: a host
+ // that is not reading costs one 50 ms wait, then the console drops until the FIFO moves again.
+ usb_serial_jtag_vfs_use_driver();
+
// The new task may receive a welcome before xTaskCreate returns. Make the
// installed driver/send path visible before that callback can run.
s_running = true;
if (xTaskCreate(reader_task, "cable_link", STACK_CABLE_LINK, NULL, 5, NULL) != pdPASS) {
s_running = false;
ESP_LOGE(TAG, "reader task create failed — no link to the daemon");
+ usb_serial_jtag_vfs_use_nonblocking(); // back off the driver before it goes
usb_serial_jtag_driver_uninstall();
vSemaphoreDelete(s_tx_lock);
s_tx_lock = NULL;
@@ -293,6 +306,21 @@ bool cable_link_host_present(void)
return s_running && usb_serial_jtag_is_connected();
}
+void cable_link_replug(void)
+{
+ if (!s_running) return;
+ // D+ without its pull-up is no device on the bus; the pull-downs stay off and leave the lines to the host's own.
+ const usb_serial_jtag_pull_override_vals_t off = { .dp_pu = false, .dm_pu = false, .dp_pd = false, .dm_pd = false };
+ usb_serial_jtag_ll_phy_enable_pull_override(&off);
+ vTaskDelay(pdMS_TO_TICKS(REPLUG_LOW_MS));
+ usb_serial_jtag_ll_phy_disable_pull_override();
+}
+
+bool cable_link_rx_pending(void)
+{
+ return s_decoder.len != 0; // the reader's own state, read on the reader (the tick)
+}
+
void cable_link_counters(uint32_t *corrupt_frames, uint32_t *discarded_bytes)
{
if (corrupt_frames) *corrupt_frames = s_decoder.corrupt_frames;
diff --git a/devices/harness-pro/firmware/main/cable/cable_link.h b/devices/harness-pro/firmware/main/cable/cable_link.h
index 04c999ac8..dce5dbba2 100644
--- a/devices/harness-pro/firmware/main/cable/cable_link.h
+++ b/devices/harness-pro/firmware/main/cable/cable_link.h
@@ -83,6 +83,16 @@ void cable_link_set_log_framing(bool on);
// with the cable still in is invisible here — see the hello cadence in pro_cable.c for what stands in.
bool cable_link_host_present(void);
+// Drop off the bus and come back: the D+ pull-up goes off for 100 ms, so the host sees an unplug and a fresh plug-in and
+// enumerates the port again. Blocks the caller for those 100 ms. For the session layer's self re-plug (pro_cable.c), when
+// a host drives the port but nothing on it has answered for a long time: the one fix that otherwise takes a hand.
+void cable_link_replug(void);
+
+// Whether part of a frame is in and the rest is still due: a link that is alive, mid-message. The reader hands the
+// tick at most one read (256 B) at a time, so a longer frame (a welcome) spans ticks. Bounded: the reader drops a
+// partial after 300 ms without bytes. Reader task only, like cable_link_reset_decoder.
+bool cable_link_rx_pending(void);
+
// Framing health, cumulative since boot. The RATE is the diagnosis, not the totals: a handful of discarded bytes
// right after boot is the bootloader's parting words and is expected, while a steady trickle during a session means
// the two sides disagree about the format or the cable is bad. Without a count those look identical.
diff --git a/devices/harness-pro/firmware/main/cable/pro_cable.c b/devices/harness-pro/firmware/main/cable/pro_cable.c
index 956d9be58..bf0d88bbb 100644
--- a/devices/harness-pro/firmware/main/cable/pro_cable.c
+++ b/devices/harness-pro/firmware/main/cable/pro_cable.c
@@ -41,6 +41,11 @@ static const char *TAG = "pro_cable";
#define HELLO_ALONE_MS 2000
#define HELLO_SESSION_MS 15000
#define SILENCE_MS 15000
+// Self re-plug (replug_tick). After a cold start beside a booting Mac the link could stay dead both ways until a hand
+// replugged the Pro; a fresh enumeration is that replug. A daemon greets within a hello or two, so a host driving the port
+// with no session for 30 s is stuck or has no daemon; the waits double to 10 min so the second case sees it rarely.
+#define REPLUG_ALONE_MS 30000
+#define REPLUG_MAX_MS 600000
#define NOTIF_ROWS 16 // notif.replace items kept (the daemon sends at most 8)
// Everything below runs on the cable_link task (12 KB stack) unless the comment says otherwise. Parsing therefore
@@ -60,6 +65,7 @@ static cable_machines_t s_machines;
static int64_t s_seq_last = -1; // -1: none seen this session
static uint32_t s_seq_gaps;
static bool s_resync_pending;
+static unsigned s_replugs; // self re-plugs since the last session
static bool s_seq_on; // the welcome carried a seq
// The id of the recording in flight: written by the voice task, read by the cable_link task to match a reply.
@@ -943,6 +949,8 @@ static void session_up(const cJSON *p)
// console and `idf.py monitor` behaves as it always has.
cable_link_set_log_framing(true);
ESP_LOGI(TAG, "session up: %s", s_machine_name);
+ if (s_replugs) ESP_LOGW(TAG, "usb: came back after %u self re-plug(s)", s_replugs);
+ s_replugs = 0;
fw_confirm_session_up((uint32_t)(esp_timer_get_time() / 1000)); // starts the clock a fresh image is confirmed on (fw_update.h)
}
if (was && !moved) return;
@@ -1117,6 +1125,28 @@ static void link_resync(void)
}
}
+// Before the silence check, so the clock starts at the session's last tick. Only a host that is there counts, but its
+// absence does not reset the wait: the re-plug itself makes the host vanish for a moment, and a reset would loop at 30 s.
+static void replug_tick(int64_t now)
+{
+ static int64_t since, wait = (int64_t)REPLUG_ALONE_MS * 1000;
+ if (atomic_load(&s_session)) wait = (int64_t)REPLUG_ALONE_MS * 1000;
+ // Never in the middle of an update or a recording: an unplug there loses the transfer.
+ if (atomic_load(&s_session) || !cable_link_host_present() || fw_update_active() || pro_voice_open()) {
+ since = now;
+ return;
+ }
+ // A frame half in is a link alive mid-message (a welcome spans two reads): wait for it. The reader drops a stale
+ // partial after 300 ms, so this defers by that at most, and whole pings in between never hold it off.
+ if (now - since < wait || cable_link_rx_pending()) return;
+ s_replugs++;
+ ESP_LOGW(TAG, "usb: no session for %llds with the host present: self re-plug #%u",
+ (long long)((now - since) / 1000000), s_replugs);
+ since = now;
+ if (wait < (int64_t)REPLUG_MAX_MS * 1000 / 2) wait *= 2; else wait = (int64_t)REPLUG_MAX_MS * 1000;
+ cable_link_replug();
+}
+
void pro_cable_tick(void *ctx)
{
(void)ctx;
@@ -1129,6 +1159,7 @@ void pro_cable_tick(void *ctx)
last_words_rx((uint32_t)(s_last_rx_us / 1000));
fw_update_tick((uint32_t)(esp_timer_get_time() / 1000));
link_resync();
+ replug_tick(esp_timer_get_time());
if (atomic_load(&s_session) && esp_timer_get_time() - s_last_rx_us > (int64_t)SILENCE_MS * 1000)
session_down("silence");
}
diff --git a/devices/harness-pro/firmware/test/host_esp/driver/usb_serial_jtag_vfs.h b/devices/harness-pro/firmware/test/host_esp/driver/usb_serial_jtag_vfs.h
new file mode 100644
index 000000000..2347accc0
--- /dev/null
+++ b/devices/harness-pro/firmware/test/host_esp/driver/usb_serial_jtag_vfs.h
@@ -0,0 +1,4 @@
+// Host-test stand-in for the USB-Serial-JTAG console header (test_cable_link.c defines the functions).
+#pragma once
+void usb_serial_jtag_vfs_use_driver(void);
+void usb_serial_jtag_vfs_use_nonblocking(void);
diff --git a/devices/harness-pro/firmware/test/host_esp/hal/usb_serial_jtag_ll.h b/devices/harness-pro/firmware/test/host_esp/hal/usb_serial_jtag_ll.h
new file mode 100644
index 000000000..a9459ac37
--- /dev/null
+++ b/devices/harness-pro/firmware/test/host_esp/hal/usb_serial_jtag_ll.h
@@ -0,0 +1,6 @@
+// Host-test stand-in for the USB-Serial-JTAG PHY pull override (test_cable_link.c defines the functions).
+#pragma once
+#include <stdbool.h>
+typedef struct { bool dp_pu, dm_pu, dp_pd, dm_pd; } usb_serial_jtag_pull_override_vals_t;
+void usb_serial_jtag_ll_phy_enable_pull_override(const usb_serial_jtag_pull_override_vals_t *vals);
+void usb_serial_jtag_ll_phy_disable_pull_override(void);
diff --git a/devices/harness-pro/firmware/test/test_cable_link.c b/devices/harness-pro/firmware/test/test_cable_link.c
index fe57d6930..9adc2e5be 100644
--- a/devices/harness-pro/firmware/test/test_cable_link.c
+++ b/devices/harness-pro/firmware/test/test_cable_link.c
@@ -29,6 +29,11 @@ BaseType_t xSemaphoreTake(SemaphoreHandle_t m, TickType_t w) { (void)m; (void)w;
BaseType_t xSemaphoreGive(SemaphoreHandle_t m) { (void)m; return pdTRUE; }
BaseType_t xTaskCreate(TaskFunction_t f, const char *n, uint32_t s, void *a, unsigned p, TaskHandle_t *o) { (void)f; (void)n; (void)s; (void)a; (void)p; (void)o; return pdPASS; }
const char *esp_err_to_name(esp_err_t e) { (void)e; return "err"; }
+void usb_serial_jtag_vfs_use_driver(void) {}
+void usb_serial_jtag_vfs_use_nonblocking(void) {}
+void usb_serial_jtag_ll_phy_enable_pull_override(const usb_serial_jtag_pull_override_vals_t *v) { (void)v; }
+void usb_serial_jtag_ll_phy_disable_pull_override(void) {}
+void vTaskDelay(TickType_t t) { (void)t; }
static int got;
static uint8_t got_type[8];
@@ -56,18 +61,18 @@ int main(void)
// Whole frames pass straight through.
reader_step(a, (int)la);
- CHECK(got == 1 && s_decoder.len == 0);
+ CHECK(got == 1 && s_decoder.len == 0 && !cable_link_rx_pending());
// The tail of a frame is lost (a dropped USB packet) and nothing follows: 300 ms later the partial is dropped,
// counted corrupt, and the next frame decodes at once. Before: it sat there for 15 s.
reader_step(a, 64);
- CHECK(s_decoder.len == 64);
+ CHECK(s_decoder.len == 64 && cable_link_rx_pending()); // the self re-plug waits on this
now_us += 299 * 1000;
reader_step(NULL, 0);
- CHECK(s_decoder.len == 64 && s_decoder.corrupt_frames == 0); // not yet
+ CHECK(s_decoder.len == 64 && s_decoder.corrupt_frames == 0 && cable_link_rx_pending()); // not yet
now_us += 2 * 1000;
reader_step(NULL, 0);
- CHECK(s_decoder.len == 0 && s_decoder.corrupt_frames == 1);
+ CHECK(s_decoder.len == 0 && s_decoder.corrupt_frames == 1 && !cable_link_rx_pending());
reader_step(b, (int)lb);
CHECK(got == 2);
@@ -106,9 +111,18 @@ int main(void)
reader_step(NULL, 0);
CHECK(s_decoder.len == 0 && s_decoder.corrupt_frames == 3);
+ // A frame longer than one read (a 295 B welcome over 256 B reads) is pending between the two reads, done after.
+ uint8_t w[1024];
+ const size_t lw = frame(w, 295 - 8);
+ CHECK(lw == 295 && lw > READ_CHUNK);
+ reader_step(w, READ_CHUNK);
+ CHECK(got == 6 && cable_link_rx_pending());
+ reader_step(w + READ_CHUNK, (int)(lw - READ_CHUNK));
+ CHECK(got == 7 && !cable_link_rx_pending());
+
// The driver's counters ride the stats.
cable_link_stats_t st = cable_link_stats();
- CHECK(st.isr_rx == 7 && st.ring_drop == 2 && st.frames_ok == 6);
+ CHECK(st.isr_rx == 7 && st.ring_drop == 2 && st.frames_ok == 7);
CHECK(st.corrupt_frames == 3 && st.rx_bytes > 0);
printf("test_cable_link: %d checks passed\n", checks);
diff --git a/devices/harness-pro/firmware/test/test_pro_cable.c b/devices/harness-pro/firmware/test/test_pro_cable.c
index 1433070aa..9cfcbcdce 100644
--- a/devices/harness-pro/firmware/test/test_pro_cable.c
+++ b/devices/harness-pro/firmware/test/test_pro_cable.c
@@ -158,6 +158,12 @@ bool cable_link_start(cable_frame_cb cb, cable_tick_cb tick, void *ctx) { (void)
void cable_link_set_log_framing(bool on) { (void)on; }
static int decoder_resets;
void cable_link_reset_decoder(void) { decoder_resets++; }
+static bool host_present; // off unless a test turns it on: with no host the self re-plug's clock never runs
+bool cable_link_host_present(void) { return host_present; }
+static int replugs;
+void cable_link_replug(void) { replugs++; }
+static bool rx_pending; // part of a frame is in (test_cable_link covers when the real reader says so)
+bool cable_link_rx_pending(void) { return rx_pending; }
static int64_t now_us = 1000000;
int64_t esp_timer_get_time(void) { return now_us; }
const esp_app_desc_t *esp_app_get_description(void) { static const esp_app_desc_t d = { .version = "0.0.0" }; return &d; }
@@ -1226,6 +1232,106 @@ static void test_swarm_cards(void)
CHECK(strstr(sent[1], "\"t\":\"supertab.open\"") && strstr(sent[1], "\"lead\":\"\""));
}
+// Ticks every 5 s for `s` seconds, answering each with a ping when `pings` (a Pro that hears the daemon but cannot greet it).
+static void alone_for(int s, bool pings)
+{
+ for (int t = 0; t < s; t += 5) {
+ now_us += 5 * 1000000;
+ if (pings) feed("{\"t\":\"ping\"}");
+ pro_cable_tick(NULL);
+ }
+}
+
+// The self re-plug: after a cold start beside a booting Mac the Pro's link stayed dead until a hand replugged it. With a host
+// driving the port and no session for 30 s, the Pro drops off the bus so the Mac enumerates it afresh; the waits double to
+// 10 min so a Mac with no daemon sees it rarely; never during a session, an update or an open recording.
+static void self_replug(void)
+{
+ if (pro_cable_connected()) end_session();
+ replugs = 0; offer_active = false; voice_is_open = false;
+ pro_cable_tick(NULL); // no host yet: nothing counts
+ host_present = true;
+ alone_for(25, true);
+ now_us += 4 * 1000000; pro_cable_tick(NULL);
+ CHECK(replugs == 0); // 29 s with pings but no welcome: not yet
+ now_us += 1 * 1000000; pro_cable_tick(NULL);
+ CHECK(replugs == 1); // 30 s
+ // Backoff: 60, 120, 240, 480, then 600 s each.
+ const int waits[] = { 60, 120, 240, 480, 600, 600 };
+ for (int i = 0; i < 6; i++) {
+ alone_for(waits[i] - 5, false);
+ CHECK(replugs == 1 + i);
+ alone_for(5, false);
+ CHECK(replugs == 2 + i);
+ }
+ // No host: an hour unplugged (or the Mac off) never counts, and does not reset the wait (the re-plug itself makes the
+ // host vanish for a moment, so a reset there would loop at 30 s).
+ host_present = false;
+ alone_for(3600, false);
+ CHECK(replugs == 7);
+ host_present = true;
+ alone_for(595, false);
+ CHECK(replugs == 7);
+ alone_for(5, false);
+ CHECK(replugs == 8);
+ // A session: never during it, and it resets the wait to 30 s after it ends.
+ welcome();
+ for (int t = 0; t < 900; t += 10) { now_us += 10 * 1000000; feed("{\"t\":\"ping\"}"); pro_cable_tick(NULL); }
+ CHECK(replugs == 8 && pro_cable_connected());
+ now_us += 10 * 1000000; pro_cable_tick(NULL); // the last tick of the session: 10 s since the ping
+ end_session(); // 26 s: silence ends it
+ alone_for(25, false);
+ CHECK(replugs == 8);
+ alone_for(5, false);
+ CHECK(replugs == 9); // 30 s after the session's last tick
+ // An update or a recording in flight: never, and the clock restarts when it ends.
+ offer_active = true;
+ alone_for(120, false);
+ CHECK(replugs == 9);
+ offer_active = false;
+ voice_is_open = true;
+ alone_for(120, false);
+ CHECK(replugs == 9);
+ voice_is_open = false;
+ alone_for(55, false);
+ CHECK(replugs == 9); // the wait is 60 s now, counted from the end of the recording
+ alone_for(5, false);
+ CHECK(replugs == 10);
+ host_present = false;
+}
+
+// A welcome is longer than one read (295 B with the features, the reader hands over 256 B at a time), so its first read can
+// land at the 30 s deadline with the rest still due. That is a link coming up: the re-plug waits for the frame. A partial
+// that never completes is dropped by the reader after 300 ms, and the re-plug goes ahead on the next tick.
+static void replug_spares_a_frame_in_flight(void)
+{
+ if (pro_cable_connected()) end_session();
+ welcome(); end_session(); // a session resets the wait to 30 s from its last tick
+ replugs = 0; host_present = true;
+ alone_for(25, false);
+ now_us += 5 * 1000000;
+ rx_pending = true; // 256 B of the welcome are in
+ pro_cable_tick(NULL);
+ CHECK(replugs == 0);
+ rx_pending = false; // the rest: the session comes up
+ now_us += 10 * 1000;
+ welcome();
+ pro_cable_tick(NULL);
+ CHECK(replugs == 0 && pro_cable_connected());
+ // The stale partial: the tail never comes.
+ end_session();
+ alone_for(25, false);
+ now_us += 5 * 1000000;
+ rx_pending = true;
+ pro_cable_tick(NULL);
+ CHECK(replugs == 0);
+ now_us += 300 * 1000;
+ rx_pending = false; // the reader dropped it
+ pro_cable_tick(NULL);
+ CHECK(replugs == 1 && !pro_cable_connected());
+ host_present = false;
+}
+
int main(void)
{
pro_cable_start(); // the lock and the machine table; no tasks run on the host
@@ -1250,6 +1356,8 @@ int main(void)
link_resync();
seq_gaps();
test_swarm_cards();
+ self_replug();
+ replug_spares_a_frame_in_flight();
printf("test_pro_cable: %d checks passed\n", checks);
return 0;
}