feat(usb_tcpm): add beta Type-C TCPM component with FUSB302 backend

[igi540]

Summary

• Add a new type_c/usb_tcpm component (v0.1.0-beta1) providing a minimal USB Type-C CC/TCPM layer:
  • attach/detach detection
  • cable orientation (CC1/CC2 via cc2_active)
  • power-role handling (SNK/SRC/DRP policy at port bring-up)
  • advertised/observed Rp current reporting (rp_current_ma)
  • event-driven notifications via esp_event (USB_TCPM_EVENT)
  • optional status snapshot via usb_tcpm_get_status()
• Runtime model was updated to a shared worker task (configured via usb_tcpm_install_config_t.task_stack/task_prio) instead of per-port task settings.
• Add/keep the initial FUSB302 backend (I2C + INT GPIO) behind a backend abstraction (typec_port_backend_t).
• Keep an experimental HUSB320 private stub for follow-up work (not wired as a public/production backend).
• Add an example app: type_c/usb_tcpm/examples/pd_fusb302 showing I2C bus bring-up, library install, port creation, event handling, and one-shot status read.
• Add a Unity target test app: type_c/usb_tcpm/test_apps/pd_fusb302 with setup/teardown create-destroy flow and leak checks (TEST_CASE("memory_leakage", "[type_c]")).
• Register the component in .github/workflows/upload_component.yml and add type_c/** in .build-test-rules.yml (disabled on linux and on targets without I2C support).

Motivation

We need a small, reusable Type-C CC layer in esp-usb to unblock early USB-PD stack work and to standardize integration of TCPC backends (starting with FUSB302).

User-visible API

Public headers:

• type_c/usb_tcpm/include/usb/usb_tcpm.h
• type_c/usb_tcpm/include/usb/fusb302.h

Key APIs:

• usb_tcpm_install() / usb_tcpm_uninstall()
• usb_tcpm_port_create_fusb302() / usb_tcpm_port_destroy()
• usb_tcpm_get_status()

Notable API details:

• usb_tcpm_install_config_t now contains:
  • task_stack (shared worker stack, 0 = default)
  • task_prio (shared worker priority, 0 = default)
• usb_tcpm_port_config_t contains:
  • default_power_role, rp_current
  • optional board VBUS controls: src_vbus_gpio, src_vbus_gpio_n
• Event payloads:
  • attach events use usb_tcpm_evt_attached_t (port, cc2_active, rp_current_ma)
  • detach events use usb_tcpm_evt_detached_t (port)

Events:

• Base: USB_TCPM_EVENT
• IDs:
  • USB_TCPM_EVENT_SINK_ATTACHED (payload: usb_tcpm_evt_attached_t)
  • USB_TCPM_EVENT_SINK_DETACHED (payload: usb_tcpm_evt_detached_t)
  • USB_TCPM_EVENT_SINK_RP_CURRENT_CHANGED (reserved, not emitted yet)
  • USB_TCPM_EVENT_SOURCE_ATTACHED (payload: usb_tcpm_evt_attached_t)
  • USB_TCPM_EVENT_SOURCE_DETACHED (payload: usb_tcpm_evt_detached_t)
  • USB_TCPM_EVENT_ERROR (reserved/TBD)

Notes / Limitations

• Beta / experimental: component version is 0.1.0-beta1; API may evolve before v1.0.
• Scope is Type-C CC/TCPM only (attach/detach/orientation/role/current snapshot/events), not a full USB-PD policy engine.
• USB_TCPM_EVENT_SINK_RP_CURRENT_CHANGED and USB_TCPM_EVENT_ERROR are defined but not emitted yet.
• VBUS power-path is board-specific; use:
  • usb_tcpm_port_config_t::src_vbus_gpio (active-high, GPIO_NUM_NC if unused)
  • usb_tcpm_port_config_t::src_vbus_gpio_n (active-low, GPIO_NUM_NC if unused)
• The HUSB320 code is an experimental private stub (not production-ready backend).
• Component manifest requires idf >= 5.4.

How to test

1. Build and flash the example:

   cd type_c/usb_tcpm/examples/pd_fusb302
   idf.py -p <PORT> flash monitor

2. Wire up FUSB302 I2C + INT as configured in menuconfig defaults (or adjust via menuconfig):
   • SDA=7, SCL=8, INT=9, addr=0x22 (7-bit)
3. Connect/disconnect a Type-C partner and confirm logs:
   • SNK ATTACHED: cc2=<0|1>, rp=<...> mA / SRC ATTACHED: ...
   • SNK DETACHED / SRC DETACHED
   • A one-shot status line prints ~5s after startup (usb_tcpm_get_status()).

Optional (Unity test app, requires FUSB302 hardware connected):

cd type_c/usb_tcpm/test_apps/pd_fusb302
idf.py -p <PORT> flash monitor
# run "memory_leakage" from the Unity menu

Related

• Closes IDF-14242

---

Note

Medium Risk
Large new component with concurrency/ISR + I2C/GPIO interactions and event-driven state transitions; issues could manifest as flaky attach/detach behavior or resource leaks on supported targets.

Overview
Adds a new beta type_c/usb_tcpm ESP-IDF component that implements a minimal USB Type-C TCPM/CC layer with usb_tcpm_install()/usb_tcpm_uninstall(), port lifecycle APIs, USB_TCPM_EVENT attach/detach notifications, and a status snapshot API.

Includes a first backend for the FUSB302 TCPC (I2C + INT) behind a backend abstraction, plus an example (examples/pd_fusb302) and a Unity target test app (test_apps/pd_fusb302). CI/packaging is updated to build/publish the new component and to skip type_c/** tests on linux or targets without I2C support.

^{Written by Cursor Bugbot for commit cbec63d. This will update automatically on new commits. Configure here.}

[peter-marcisovsky]

FYI, to fix the failing linux host test, update the .build-test-rules.yml in the root dir with something like:

type_c:
  disable:
    - if: IDF_TARGET in ["linux"]

type_c_manager:
  enable:
    - if: SOC_USB_OTG_SUPPORTED == 1

Since the type_c component does not depend on USB_OTG peripheral, it will be usable with any target.. if I remember correctly.

And the type_c_manager will work directly with usb and esp_tinyusb components.

The idf-build-apps find --target linux in build_and_run_host_test.yml searches for buildable apps in the whole repo. Since the newly added type_c and type_c_manager build rules have not been set yet, the ..host_test.yml is trying to build it for linux target.

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[tore-espressif]

@igi540 Good job on finalizing this feature!

[peter-marcisovsky]

LGTM

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 3 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}