starting with commands

suspend_fix_notes.md

@@ -0,0 +1,42 @@
+# TinyUSB Host Keyboard Suspend/Freeze Issues on RP2040
+
+## Common Issues
+1. **Device Auto-Suspend:** Some keyboards automatically enter a low-power suspend mode if they don't detect activity or if the host stops sending Start-Of-Frame (SOF) packets.
+2. **Host Controller Freeze:** The RP2040 USB host controller can sometimes get into a state where it stops processing events, especially if there are signal integrity issues or if the `tuh_task()` is blocked for too long.
+3. **Missing Keep-Alive:** If the host doesn't send SOFs, the device will suspend. The RP2040 host should send SOFs automatically when configured as host.
+
+## `tuh_task` Usage
+- **Requirement:** `tuh_task()` must be called continuously and frequently in the main loop.
+- **Blocking:** It should not be blocked by long delays (like `sleep_ms` or blocking display updates) in the same thread.
+- **Current Code:** Your `hello_usb.cpp` calls `tuh_task()` in a tight loop, which is correct. The display updates are offloaded to Core 1, and the FIFO push is non-blocking (checked with `multicore_fifo_wready`), so Core 0 should remain responsive.
+
+## Potential Fixes & Debugging
+
+### 1. Handle Suspend/Resume Callbacks
+TinyUSB provides callbacks to notify the application when a device suspends or resumes. Implementing these can help determine if the device is actually suspending.
+
+Add these to your `hello_usb.cpp`:
+
+```cpp
+// Invoked when device is suspended
+void tuh_device_suspend_cb(uint8_t dev_addr) {
+    printf("Device address = %d suspended\r\n", dev_addr);
+}
+
+// Invoked when device is resumed
+void tuh_device_resume_cb(uint8_t dev_addr) {
+    printf("Device address = %d resumed\r\n", dev_addr);
+}
+```
+
+### 2. Force Resume
+If the device suspends and doesn't wake up, you might need to force a resume from the host side, although usually the device initiates resume (remote wakeup) or the host keeps it awake.
+
+### 3. Check Power
+Ensure the keyboard is receiving sufficient power. Some mechanical keyboards with LEDs draw significant current, potentially causing voltage drops that reset the USB connection or cause a freeze.
+
+### 4. Disable Suspend (Device Side)
+Some devices have internal settings to disable sleep, but this is device-specific.
+
+### 5. SDK/TinyUSB Version
+Ensure you are using a recent version of the Pico SDK and TinyUSB, as there have been fixes for RP2040 host mode stability.