{"record":{"id":"0e4f8e713a42dd95","repo":"commaai/openpilot","slug":"chestnut-did-not-enumerate-within-timeout-g-s","errorCode":null,"errorMessage":"chestnut did not enumerate within {timeout:g}s","messagePattern":"chestnut did not enumerate within (.+?)s","errorType":"console","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"openpilot/system/hardware/chestnut/flash.py","lineNumber":166,"sourceCode":"    self.fd = -1\n\n  def close(self):\n    if self.fd >= 0:\n      os.close(self.fd)\n      self.fd = -1\n\n  def connect(self, timeout=5.0):\n    self.close()\n    deadline = time.monotonic() + timeout\n    while time.monotonic() < deadline:\n      path, vid_pid, product = find_chestnut()\n      if in_rom_bootloader(vid_pid, product):\n        raise RomFallback(\"chestnut fell back to the ROM bootloader\")\n      if path is not None:\n        self.fd = claim_interface(path)\n        return\n      time.sleep(0.1)\n    raise RuntimeError(f\"chestnut did not enumerate within {timeout:g}s\")\n\n  def reg_write(self, addr, value):\n    fcntl.ioctl(self.fd, USBDEVFS_CONTROL,\n                Ctrl(0x40, 0xE5, addr & 0xFFFF, value & 0xFFFF, 0, 2000, None))\n\n  def reg_read(self, addr, length=1):\n    buf = (ctypes.c_ubyte * length)()\n    fcntl.ioctl(self.fd, USBDEVFS_CONTROL,\n                Ctrl(0xC0, 0xE4, addr & 0xFFFF, 0, length, 2000, ctypes.cast(buf, ctypes.c_void_p)))\n    return bytes(buf)\n\n  def write_buffer(self, data):\n    for i, value in enumerate(data):\n      self.reg_write(0x7000 + i, value)\n\n  def wait_controller(self, timeout=2.0):\n    deadline = time.monotonic() + timeout\n    while time.monotonic() < deadline:","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/commaai/openpilot/blob/516ec1e68203439a73f340f1d0b3b91eabc626ee/openpilot/system/hardware/chestnut/flash.py#L148-L184","documentation":"Raised by Flash.connect() when, within the timeout window (default 5.0s, polled every 0.1s), find_chestnut() never returns a usable device path. The script scanned /sys/bus/usb/devices/* for the known VID:PID pairs (3801:0001/add1:0001 runtime, 174c:2464/2463 ROM) and found nothing - the chestnut bridge is not enumerated on USB.","triggerScenarios":"Flash.connect(timeout) called when the enclosure is unplugged or powered off (no VBUS), the USB-C cable/port is bad, the device is enumerating slowly after a port reset/replug and the 5s deadline expires, or the device is in a VID:PID not in the table.","commonSituations":"Cable or dock that does not carry data; wrong USB port on the host; device still booting after power-on; a hub hiding the device; device that hard-hung and needs a physical replug; racing connect() immediately after a port reset (rom_write sleeps 3s for exactly this reason).","solutions":["Check /sys/bus/usb/devices and lsusb for any 3801:0001, add1:0001 or 174c:2464 entry; if absent, reseat the USB-C cable and enclosure and retry","Pass a longer timeout: flash.connect(timeout=15.0) for slow-enumerating or just-reset devices","If a USBDEVFS_RESET was just issued, wait for re-enumeration before connecting (the ROM path sleeps 3 seconds)","Try a different port/cable, ideally a direct connection to the host controller, no hubs"],"exampleFix":"# before\nflash.connect()  # 5s default too short after reset\n\n# after\nflash.connect(timeout=15.0)","handlingStrategy":"retry","validationCode":"from flash import find_chestnut\n\nif find_chestnut()[0] is None:\n    raise SystemExit('chestnut not on USB bus - check cable/power before continuing')","typeGuard":null,"tryCatchPattern":"try:\n    flash.connect(timeout=15.0)\nexcept RuntimeError as e:\n    if 'did not enumerate' in str(e):\n        reseat_and_retry()\n    raise","preventionTips":["Verify the device appears in lsusb before launching the flasher","Use generous timeouts after port resets or replugs","Prefer direct host-controller ports over hubs"],"tags":["usb","enumeration","timeout","hardware"],"backgroundTag":null,"analyzedSha":"516ec1e68203439a73f340f1d0b3b91eabc626ee","analyzedAt":"2026-08-15T00:17:37.461Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}