From 7b38e47834654ec9106eb5bff7faf4ac68534fc7 Mon Sep 17 00:00:00 2001 From: "igor.masar" Date: Mon, 23 Feb 2026 14:07:22 +0100 Subject: [PATCH 1/2] docs(usb): Move USB docs to esp-usb and add redirects Remove USB Host/Device content from ESP-IDF pages and keep only links to ESP-USB documentation. Add redirects for legacy USB pages to ESP-USB with target-aware URL substitution in docs config. Drop obsolete USB host notes references from docs_not_updated lists. --- .gitlab/CODEOWNERS | 1 - .../diagrams/usb/usb_vbus_voltage_monitor.png | Bin 5528 -> 0 bytes docs/_static/usb-board-connection.png | Bin 94085 -> 0 bytes .../usb_device/ext_phy_schematic_stusb03e.png | Bin 50353 -> 0 bytes docs/_static/usb_device/usb_fs_phy_sp5301.png | Bin 127282 -> 0 bytes docs/_static/usb_host/dwc-otg-operation.png | Bin 62017 -> 0 bytes .../usb_host/dwc-otg-scatter-gather.png | Bin 42495 -> 0 bytes .../usb_host/ext_phy_schematic_stusb03e.png | Bin 1257040 -> 0 bytes docs/_static/usb_host/poweron-timings.png | Bin 39353 -> 0 bytes docs/_static/usb_host/stack-overview.png | Bin 19318 -> 0 bytes docs/_static/usb_host_lib_entities.png | Bin 65445 -> 0 bytes docs/_static/usb_host_lib_lifecycle.png | Bin 24787 -> 0 bytes docs/conf_common.py | 24 +- docs/docs_not_updated/esp32c61.txt | 5 - docs/docs_not_updated/esp32h21.txt | 8 - .../api-reference/peripherals/usb_device.rst | 468 +---------- .../en/api-reference/peripherals/usb_host.rst | 732 +----------------- .../usb_host/usb_host_notes_arch.rst | 60 -- .../usb_host/usb_host_notes_design.rst | 144 ---- .../usb_host/usb_host_notes_dwc_otg.rst | 224 ------ .../usb_host/usb_host_notes_enum.rst | 121 --- .../usb_host/usb_host_notes_ext_hub.rst | 65 -- .../usb_host/usb_host_notes_ext_port.rst | 85 -- .../usb_host/usb_host_notes_index.rst | 43 - .../usb_host/usb_host_notes_usbh.rst | 117 --- docs/page_redirects.txt | 2 + .../api-reference/peripherals/usb_device.rst | 468 +---------- .../api-reference/peripherals/usb_host.rst | 732 +----------------- .../usb_host/usb_host_notes_arch.rst | 60 -- .../usb_host/usb_host_notes_design.rst | 144 ---- .../usb_host/usb_host_notes_dwc_otg.rst | 224 ------ .../usb_host/usb_host_notes_enum.rst | 3 - .../usb_host/usb_host_notes_ext_hub.rst | 1 - .../usb_host/usb_host_notes_ext_port.rst | 1 - .../usb_host/usb_host_notes_index.rst | 1 - .../usb_host/usb_host_notes_usbh.rst | 3 - 36 files changed, 24 insertions(+), 3712 deletions(-) delete mode 100644 docs/_static/diagrams/usb/usb_vbus_voltage_monitor.png delete mode 100644 docs/_static/usb-board-connection.png delete mode 100644 docs/_static/usb_device/ext_phy_schematic_stusb03e.png delete mode 100644 docs/_static/usb_device/usb_fs_phy_sp5301.png delete mode 100644 docs/_static/usb_host/dwc-otg-operation.png delete mode 100644 docs/_static/usb_host/dwc-otg-scatter-gather.png delete mode 100644 docs/_static/usb_host/ext_phy_schematic_stusb03e.png delete mode 100644 docs/_static/usb_host/poweron-timings.png delete mode 100644 docs/_static/usb_host/stack-overview.png delete mode 100644 docs/_static/usb_host_lib_entities.png delete mode 100644 docs/_static/usb_host_lib_lifecycle.png delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_design.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_design.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS index 455a15ead9..eba6b025a3 100644 --- a/.gitlab/CODEOWNERS +++ b/.gitlab/CODEOWNERS @@ -178,7 +178,6 @@ /docs/**/api-reference/network/ @esp-idf-codeowners/network @esp-idf-codeowners/wifi /docs/**/api-reference/peripherals/ @esp-idf-codeowners/peripherals /docs/**/api-reference/peripherals/usb* @esp-idf-codeowners/peripherals @esp-idf-codeowners/peripherals/usb -/docs/**/api-reference/peripherals/usb*/ @esp-idf-codeowners/peripherals @esp-idf-codeowners/peripherals/usb /docs/**/api-reference/protocols/ @esp-idf-codeowners/network @esp-idf-codeowners/app-utilities /docs/**/api-reference/provisioning/ @esp-idf-codeowners/app-utilities/provisioning /docs/**/api-reference/storage/ @esp-idf-codeowners/storage diff --git a/docs/_static/diagrams/usb/usb_vbus_voltage_monitor.png b/docs/_static/diagrams/usb/usb_vbus_voltage_monitor.png deleted file mode 100644 index e6302c1cb2fd83af51931ff810e78634b2097c1e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 5528 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%0DVIMfgaJ|9l=SwLA&O#4& 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

cfuS0s1q?{<$2RWBiK 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 diff --git a/docs/_static/usb_device/ext_phy_schematic_stusb03e.png b/docs/_static/usb_device/ext_phy_schematic_stusb03e.png deleted file mode 100644 index 9f4340083261cf409f7fac1a47ffe21e3241b28a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 50353 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 z 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 CCN&`d diff --git a/docs/_static/usb_host/dwc-otg-operation.png b/docs/_static/usb_host/dwc-otg-operation.png deleted file mode 100644 index 505335745bdf2795bb963c007c81a7a4f73cd5ad..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 62017 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 diff --git a/docs/_static/usb_host/dwc-otg-scatter-gather.png b/docs/_static/usb_host/dwc-otg-scatter-gather.png deleted file mode 100644 index 85c1fa5ea04f7469f4fad7bc62e20765f600e2f0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 42495 zcmeFYbzGF~x;8w(NQlA!N_PqZ0)uojG!oKE$Iu-^NlGIKN-IbjG$P#yh?1iM0umxA zDIg)jca8BZpS9Q8d%t@>dwuWk_ip|g?z!%JuIudMIL|vqOGD}GY3kDu2;{7aGU6%( zf{lhiu;lP@!IjC6VqOpk1HYGop_j8S(%#7i!UmWB@rezt06tsWTiAM7II{`x*;}*0 z5o`hiI#<<{wXYzB+^(r=JNdh47#TUj!DX<*#lqR<#~LjQTN@sJ%+>D?arRa6uyC`x z;%aT<1lC#m{#eB?%qQ~WPHVp(SA+!xe_XKj`1Nz&pCZ7Axu9e3|MU6$d_R|Y+gsas z{(RbxOJ1(7PG0tIf4*qt>f&N!<@Kk979Jk1s6Q`5x;p(l@oVkRm7aDM)~=`@w|~F%U2Yz(uHa6E z?<$eEal**%msoz>r}$64{bTzcHZDJZ``^Do;O8Aa7Eazj&-O!{o?d>x4r}Y->h1R9 zs*jC_m(4FN{i3BdWj|AB9it}b5x?D|jh=NAF%Fbc2-b|~v)Z|edc?B$C2Rci}RyFa$| zPc`+sMtJcQ-Z)R#r&>>KNkLXlyLbU>i`p4elx@WvhabN<-h;^4{G2q z5xU5K=m-M80?F?>;QuQe0SFr-@89BpyqyIIo*?%8ogP5Qa>H1>wS||3j+d*)_fYvC zJA<#yuQ-nJo!_0~cl}t~dw_Ut?~1W)lnrpf|BBQ6V<*A5*zd0NSE%grFF*MiyMAf# zH@D&cwd5~X+0X3zo66+8kw_a4phg`p3oma^@Il+#!rIB^|F%d5%7ec?W`SV(L#6+R zx`6+@?Y|SjepWC4NEKSH_AXu+rTm>6{g=bpUy@7yB^vl6F#SjF@K>ndpCt0XO6tD{ zslPsrJKI|WHw9ktR|F-2Us33%Bm5D8epACgOeDV&{C~$2gnypk@9L@lRfE7EBL7#Y z;TKT)Eg~U6z6KfLSC069NhAM}#D6)=f5-6of2QN#Dpnh702+VdsGm{$H+*2@Ywu+U z${ar6_L$E`n9sbIfBuKSfTLeuAuyi&{T~;AoG>?GYA68lJp6vU3-j;aZu|bh19zQGsPY(<<12EvR9B-1$9Q|6AbVVdG@sW$*Ln=l>&pe!mrL)&he- ze=TssBxz7Df%7VSN8R7EHduhs0=WDK_Q41gvw!#x%<=~g{}0yxjI4hHr9U?C{l~sT zRHa|o^>3H{J=FSdQTzYH-u+7_zhKb6#M^(G=Kp&8_jvG^c>B)^?oZzSPne^BvA6%s z5C2(j|5b4PW$q4gH6~sEZ!*Wk?4R!bM@ascxcg6v>VMt+uXFdGNa0WJ{@u`jrr$yf$s(A|4=Cj(!{@8CjMti%^$M)KQ1Nt z|B<N{)1Zb@7D|csq_TZt)}0+&a`4vdWjXWp z8o4TKp1Xxw2vVl&a#cr^3Ty##sk$$&s#sr<FS~A|QB2PC-!%Z43N#jb)DGJFCz4w=yIa-l@ecg%)dNkkXR@j zCL;zVq7%Dm|GKDaW2*V<;QszT2iEGj+tn;u_>gAQjsyeVkWK($o))Zv9edJy)`ieU zAfy;#vVX4Tm#P= z;kWAk=)c4i85o0){Y8GJxV)vKEfhzk$T8Y>{NdJOkFrkGqH~01=0~I~V;#u_$c!n( zF|08QEiTI_LZZxqPD)C`3)o%J(~uZ$7ac-h+#`8l>;LjDXVizeIakyPZ#|kIGyy`5 zwST59AS|Ad5#Ksih6i#3azr%a+!K6C0GtjV20gi?oHl3^FD> zLL65}m!&6c2J5-TeK9sxHnw^A!-xm3#faK0A=7v!g9Y+H0F3zf*kK`rQ00ON-Ez|# zhw)VKJSZF3%RWWu`uoP7wXw=M(O&rdWgTtYHby1=u;b51m^;X!^rtpOLQs&^;XLiT zm@Az4AERSq59@3Pv-{bE#?J*R*h5&_43{74JmkF<7w1UQ_MUHI=LAwWO)_Ecb3M-t zRzZdxpA{ri6)zz z!PrJ8v%t9lopFIoo{~6gE*yfQOW8WZXZT`{SUAZd!DWH-_~QFr705BPqThY#_5BhU zH?N!|Ay)N3!40I%!5eMw~D4w!_S)<^6je0o6)=b=HBvnPpymFd|FCAj+PV4NFb9FOT|MaJqxSu)z%&n zL^;GrF7=(}y@XWG+33L&=F4x7y#I;(s%D1=8vtSUZWahax6M#JHfHf;%50 zBjPYpdzFxp8K>Ni?@X=H4RbqK@1P=NXTg^BUYsyi9dR2^!tKPJQ9reUvywZwqo=fp z+DIsT>eLG0r`H|`fAfn9N?ypJtK3#!>^7XlIvdn_XpT`jFebSTsyF2|S+sbIY`RdZ@HiN%_k#kI8@(GbH@a5LN8zX(q1 z8dEJ>LZ$yX#)={;$}0zVh_-DJLJzGt-G+cLKt%9oREH8Xjb*DeZ`_mpS_q=WP9|8 zrI31USfzjiX9f>vuIj|+YM&dl$n`q$gS+`B>US>iqYrc7!xw{egb^BcJ{K0AOWLFa`YlTtThPo66vnB z>Z4@L-`sd9U8dk{qHrgUAwr2G38{?VsgUhXTVVYK7U|Acnv>M68C|_Nm{2U9p1Da6 zxwN9gnF+;`ZKDA@4G7Piw8DIt(^n!Vpcgo|MTDi_b8q1VQ~x>NvVs(rV7NSM{5hY2 z(L?HS+2mJaj`aFj#Tm*pE2?XjOpd6`0!KZF~ zWcb9iL2JsvJ)cM7&vN+L8VeEk43o8V&MMdlCCaz7bD;=<=QG}J#>Y<@Fg+^tj$<*m zV(y3GAQS9tx0p_|Zg zgeI8!39)PB!A)zC#$u}k*g|aRQ&o@J771>8I4|JyWp#-|xWt=I-ku8Zvj%4YX%*v* zcmswpg}_0t#O#nlB+h-&5t8A(avCFTOvu9u2c8>3#lU|gJ@ z7_(;>^d+`Pwu((3WH~aO6CX;BEmwf!*!29GG>f@Bv&kFn=&nI!HP2ruTxNy|wu3la zewfn@()Mdbc2-uXwzl>KgEHEcH;=rkW}He{zf*&LG+FPNZ{3^hyECjb+~Dmv z=|y&N%b%S?GyC~Wd-&G&p!D2&<3{&gP8~km0op*Ys?KBnG`nVY{L0%5Z#7m)Y#~;3 z999!IUg}2^81%c0VbChYHgd$_=4|KEL~Xeoi>N3Ss06xD(>J1;1NOM&B;7wC&he-! z-Lw6C{B^@>ao~QspnbBfa6?@tV*K66n>V_~b#7RnM$3Cbaq!M11uYk*Nw_#3?Qa=Y zm}B9dp$wUDZKbn$c~_f(M6Xz1;p>+*?Mh39kApeWR?R+j?U9JgQ?d=JyjJ28@6kPs z@{HJRf)Ki}5;HWNY#SPXEKHd}+~-VA@bSS}9N92cP3L8F;nr*vL)esqW`S92(Eitr z)@P*4@lM}9mA9UYk@8+SC*(32Jv5}H+4uZnc~e;F^;#}Dje~D{)5CcRggYD444P8Q z*HfQ5j+Pm9=Wmc)a4~g~XKsebh(kDCRs{SSmk2a7o`(k?MP(S01Ym=jE2JLT_KqwT=g zGmGAfp^o4%(Tpg>7rLA>%dwOeY%lFGWTfG-O z$KSs4doHL8+6~E&xV&r+$2%{|YuZ%zd6k^oP%Ar9fqJBvmd{81^j$OG(=v-*J+}lx`MAWBC}%x-+D?fVFFcH$S&*!;Y`(TA88ykbVi}=3nEi~qQnU9{U{N! z_dJG-5{``jtRd{QzY+BfK!+6JePBx(+XF)OXsFGr)GLH*=IZdy3(75KzOxb4471t!7V=w+^*t@JJ$!YFbB})2) zk4_D1CfgUKtDde265owVIhzP|KPhnh6+A+OK!C(~Ip+`H3%6OzBwNMKbAfxIHoldNr- zuoh*n1R3+)ea?uE=e%Ur(o};t%oQv3ZAXXYUT2ERD+u3NbuP&6ak{m*_sNTXVn{1Q zneXxa9fw;%2aiSV6+wvo5x0#o+j?Zy+VZ(Wz&f>v%rR%O@$>Sniifpj;dnNl$wgl*6PjDQ+QhHr+J}ra&pO?9UZ*$FH=6*Sz3M&j){pe zgBafL7uP?UL4F}30YQC}47-K{Eit*bKbKg%nZP6;88S7OEgA43J78TqYBly8XI@j= znc5jmBqGy-vM;Q?GbFwonJLB^Gk;Wa)Q~GYMKj5kLl{Su^g|V(swvMw(&W8+0 zT{CKtxYpsE^j&HT4S=PIm2=XkE7SJEB0|K|7GLHR||D*WKOFrWx2LI z=E9wF@1a{ko%v)QxD7UYt{2IsV32GyLWCr;h!=!gZ$cR571FB`4%00RqGAZt``^scWakguAQ1e2ori=|gQ^+9lJ+Pu8pSAJJca2;S&`@)^ z5T>A~$bMA~6_wnFbBCQA3*Nd_KIu`VcH~e21jx5yH=ebDc=mXero`#RId3v{b>;0a zD#YD_6wa-s*>5x9#BD=(`U0!(8*5)Kw2Rm$>ml1150LTRzP@#;OdvV$J#HO#lyIGr z&`ZsN-i_K-ezL4Lpo}&U`gnQgHX1kbE~V&`jizl4Z*gz_X1eATb@{zcV(CXXcf@^G zwXz*pTC2tB?Th>!Ul-l_ta?Wf&PJ~m3+E7eJxRqt=);J{T_+!4F?r`clT;*NeiGk( z(0|EDyrZ-8;dx%;x;5aP`CPh>9t;O+v*8=!VTs9@-q?Lx_xhpcpqje+k??G*xB59X zOgd45I>{EGHjv2?!4dB`l_fGhBvcL$Y^Ck&Bnu`ZwjMC4IlxosdN(`=B_Dp6H4KcP zcUUkgO3Q$zoeZ|ZqXgwIDXXiLQQ7u;Im9O+>+pLIqDfecNtZ!2B-CwxCmxE-AFGBDYSJUGHnDh$Tt8%;H14oqGQFq98+do z?=b-~v%)gJK{Y;hXsApgz2t{4tM9C8Y_C=MK)dG{^>Il+kr-~rS9tM|q=GLAX-h1A z`Z)r-uHf+=61lddpNEKXCnV>FX;v4tlU@!Dhe*B#Wle&(|IP(ea$jtQ(5}3Q+Yq_h zDXbF=1rThgriK+A(iO9V%kGJ_$p8`OCUVWVefxF}sO;#t_=m|EIQa(!p_K6V^`5r$ zG9T@|;8lM3NkYy$h)TxW{9rTly)dYNY}*IK;SC5Kr1})!^h+EnDysS>=ZTstY~oQV zN-9pROw|YVrA6o{Wh~~c_ zBc|SdP|YOj@lghWxG6T%r<$MdKpAtNSk{g$<*OaKb+r#XU3|v|dLSBXrp37Dz zYw+7fDm(!XE`HJy3*e^CO+;IS)=0ve`v$C>U z^k-hqy;?aGz@4#D1&WvGgamy(!#IjdLH7j~GC8o2a9+4oNiV;|-O9ew~1r4h1^V1bOI?h1~xKY@lmK*&UUX%Q8BsZwCjMZ*If z|8(I7P+SkH7)H5PjFg)(061eV!yRdWR&Lj^gY~RHI@VkmI8?TW7_I`st@6Fmo?bnj$>!(-V z7C*Es0NCUn=efS!z-2UBAgJGkjTbK_ft0E@%f>nc%F(A^Z`&=m5^Tp=uMG(ZvQ$ z?z4Jds78@Ohj@;Hs;8S(uU|Nrk{@Qohe~6jT5x<}loX?RhumWLW#LH&+@ukE25*9- zk&vZIs~+8JjdBsEEdcQ?{G20497XiL5!JK&`eDkbSpL3^S@ce#^l`M*jl)N(v3<16 zcxNx4;ewDYP%xqWBNag~bzuR~&iTjUi%$+eUDETrJ>LW;Ma5KWzq>7#&Tl>4a$~H{J^wUM2A>5smwt(zdjWQj z#I0>L$`B#QODqwndCP*_rBIwFhFtjjR6smIxW<`;+)zPYFQnJx8RpWJh0D&6I#KetJg~{2-f)Qcc?mK ziFeZZtu|k+Ck6N%Wz~b>uZ}XIG|KwU1T9JW**H@3=@gjJJx5# zd(y$Ch0lwx7M@1-rIRq~$7KxQ+cBc=L;41wdPN5B<~iQ%;fO3Te(9rUX2u`G5F9m> z$mN1sd^^LXCg<_{U;8$d)kcU=w`*Tqc5U7zUl`0u1QGoMIJ zGHe0>!7TjzBp}f!)VjP^chc7VgplbxN={MouV;`%vq3~o_*QRz77CFPb0;$i3rWF5 z*ur7hb?&H;$cTYHDS{*+GLvB*{Pg&c$b+sY{Ae56sU?nkjI7fz5@;9^IFYPy0h;MP z=0skZcTCf$5Fin!i(2Mghq=iCb$sA*RKkONdP=pa2+g=V%Zfih^IvDa4bbriLnkLE^?HxKIbO{3aIvF^=;VMAC33K`o~ymU zC0D>B#%Gy|3Fg!>)x)$;Z4h;@YjVn|2+biOy%5t)&k6KBMsqG~(Y(Aosr7eHZ9&5+ zD{K7r1qvwk+0a6@G)q7vsm*=(aLw?I53nKYwTdP4IHUHc5CX)ty@X`mAtUa{gR*6w zR-Lq~!z}oQSXkZ4wU14k4|k~GNQ6;4W2G#t;xsmJ&BO`dvz`ggSBul*$zu3o(= zMHtQuKtVW55dpRllR0+M0O5>>{u=W2v{Bg+6XXP|f+fr8Hu4nK8b0N+9qz~zJ;xyc z*AEIW0L!Eg1=K;e>r|6pHA}=Dy)C|Qj9C^Z)Qp|?!UvRkY5ee4NV-ZvX$0z^BtB;h zsSQPc7E@GIq+bOVCK{7cv!onj6eJ%~IjmEpE_#lEA-Hjxdbf-T<7Sj<1Z$fvPV>Ap zjOK7==k7q8@P~*7J8$ScvH}CbvuEFn0q-#;mVEx6f<(402tRQ5tpTNo8>7zDTS&$0 z5BTYod<01~`w!y$+QWgE$DbI9i`XIi4BEH(lr^!*Lw8alS0W=L%V_z`Wq7yL@mAAg zXHA)9G`O2A8s}($VwJ;Q zJhHa^Q_EIaG-T;~nTHO9sVzJL&?IrwfWylH<(VdK2*+XM5(v)U z;%cke@zX7YmFBZKiHxA>hteeGT^(~hiB5F~b0L9{MN&NI@e9QMJ zs-t|=bEN2kPreEJe_73te56)fBRc~)sIgjChV_=OE;@(Yh;d=V{QP_~9=#`T;sC;n z{Q`2aGagjxaEYZ4kSlZZuhO0&-wf58k6X|dBx0gd1znP9rRAxXg9Vy13{tf99=!|c zDfEisV{(?I+x75Jvt4U?-OPuD0Iz znp}Z56Q@5E>x9J|H>t*JB!O7^2nH&esDh=PlTPFwC=EnH2Bp59xpBBNj2i*WF2P8A zeIVuHC@Ke(c6Q)5s&C!8a9RVpPmfw1@XG6Y-wZWK6aTJD`@U4k~kv+vj*}pBqzr8QUV7Gf7mn^#4`Kiyj3tBTf4`jnn z_qwE%YZgkbmm8E%EpIOlqVOvEM(GKYzMPk>H-o*9g7z_@QwPSk0DJTyNr}E!>Up8f zb(T%Qp32$oV_fUyoK<&V%E&aBTo?hZ{0*=#?%EVt*hEPvq?nSJUSi)3gc?yZ9$=#v z!#r9UZ{NVU=W;^j8|rbu#H8Pl=inj4wtq~pRz;M>Z)UPbnZj-KISVlF)1v?$`87d9 zxk)heXQB%z7H~tfjZE+Lp7QYvz0t0`ejZv98$v~R2WI~(^2{XFn2aQN5qHsnQtzul ziJ|+Qf&1YP0yYcePlrwipU{B~s;gYNGOtlGibouw{0fH+AIgi3gxRavu7McxKx~zb z8Q&TY`xf=(jwgD>)t8-rcz$U)1h~FS#U(JIQseOU$y(G|8uFsozQgD5;m0#bANQdP z)eKA;efmE+pJ76`A2=zOuZD)0k+U=8f|JhX^LR8e&X8d@$j9AO{whdY=0fx;OL!xL zQ>W--vF_t!&a+FpFF#xbm3tScNWV7|KF_~;61zZ$nv`|rbQmeg7?}hN?oe|8DxOZ9 z+QZ;w8s~|kCv2eT)3Lu59o>dQED@4s7DQ!Xks)47#2{5d9trC24=DzwDqr^kHkuco zMM#_>qoIid{K7@L^IW=GHIp8%c$8IC+JPA)M4qKVK0bM^DXnma{Yq8SzR* z7vu{1sY(D7>|XZXW47Z|xnVQR-m_bw`ZV^jOxqb|=ZO+JR&>7Nt*akzd3;$l+W9m} z38X%gJr%Fhpz9@!_Y_X(z{ftuM0$vE03mw1uKc)X*_6EKnX>>d_u^@#}y-DH{) zp=xQokA*;YBl6qVJ*%Ci;poIf15-P zFi=s&fCFF1)3|C@sCwQ;$6qrLluRj6@oVCQ8z3(|r*Un{#mADI*qT+D z_n_ZUY28bTP*C7Rw|Q(XOQJz%rVFGx_w`9pfEn??4wL|g?7C$8fL0LBRNc8M+C%XT z(?{C-xjSllZNqLd|RnH*hOMy8?{VC#_JBBofOor9gZ(p+f z&3w;JZ%~-}$~JFD4rNK+IP?nKdylH~-D1Y%w(#%E;#qU5HsCzE9zE(L@aS{5xBbGccy_2_dPbI!mCdkh;DN5;Yj z8`$JX>Gk4ZPyYGo*JS#>RE^YYZze~++9Pn0JSz=SoV--XZGHkP}U4o>PG8Hwy06c zqBxv+?d1TVh#vq|$5Oh@&PVkE%XDQ#@1Wr>cNw6p^OK+1XOYH_J*7*xW05W~ASJ9D ziI?F>fYQ1LF!j0>mJ(Y455M&s5Y0Dwigb~z!c8hOZ5I2y&|f@-3TpdomB}#TI8vhB zy4d4ZtY3PrH|Tq>i)xx;fG{vBikP8n+{&Hl_#1FHU52;!96{N`=QPGgEAGR6C8u$; z(xltXv!`$9RYmQ|w~gSJy=}yiw{OGLNbNs>ChaFR@PLKf&cyfBupR}u0!dl5GLSSP zLZ}eqHAdn~r`F#Vr!kkX-eI+kH~N^@IqfH3;CHE$PRwWZQ8umrjU|h`9?&DTpegH6 z1k~#T zaA!Hc$@`cQo&2oxA;D1m0oTRwYpI+%$ORCYxhXDQapfPR#x$5;UR+C{1a>=uVY?e6 zX7wh|Gv_XR4fyb!;8}hbs^ft6)LiAk@uta~xb@PUgmBQ&zTgeqUg4ekfcJo%dE3-| zpEL3vd-J$%pOW-ck2#uit3-dKY#1BGY5j3iHs< zV;)~q2y?+n3C|Pvv2t(}hez+=S4yw@7ub_gkgUu!10qguYHD+HQ}A`&l~-L`ahF=O z@bd0O&=-S#8P|jW3%YEzpeNgcX6L5%lH^>+C-nlg6s|%kv3s3Dz@VOdP+rd6#!DKZ zyJj7x1d!EL{lp@U;K9^`Co-YfQMg33zBDMq5>~~)9gdv9FwmfFw8@mU6Gd%yzJ;}X zniRG2rIvNjaI4cZlT;uwzkT%Kq%h|_ zbA|~tjeW1h3sSI=zU`9}Ut+VQ^_r-W==5lI_nNwa0}N*(W~iXx96z#C^zQQ*u0C-+M9BcN1zOi=IVQ%%Z151tX7Tc?g-7(dhcpr_t#wu6`WQqkz5OJm^PLDGgQec-0-uIcp*WiUvv_!z{K zNp}#e1171@K>$;%pjt)-Er|j?35Wm@%L2c;L{szQq1P|R<}i%mnxTKOQDl15H(&zl zj$PprXXYOmWJcjpfkvNi28n&L4{!D4X`2gp6f#qYi>y;=F-=z*IJ$HjR5qGWpaZspgC$aUr5vD^G3 z)iJF1P5oVz;6hnGB73h(4DIL?w&d9Tx zIijACcXF;TCxB{l?pBfz6w4EnKhVvWOWv}SPOvOVa4&Bw-`PyPWCq3=7&GR-u%2Am z;2_@M<4rpW0(jYkUZ@}_{3!X%9lK;*kL#D=%>7@LXQ;&c(rw2(d>y*o;AZenZc3E1 zZyKfk7N&Wnvt``p`zV@;-YM(hX8?8{5WxgK;S--j1KV#k^Q)w)=}5OLdM1wPDc^j` zGrk5Xm&B$A_7q_#ezHS2mCKpzHF z3iq~^;YZ9G6@4$>hW*T_;ZrGWpHw-^K~pygbveJ90fr z^PUL*n^Kx1HxlA=@X1^-!M$Q4{CQMdxPOQ(623*X=n~(E$lMT+_NOZABDRxXs$9UU zH$r6QvfX<+#`|=mj^h?#{4V63Kp+~U1OO_9yc5IpWwbDuh~9bQrioz$%=U}O`x zdXKa$d?HSt7fZT#O`*;avB59-{7kF4FDa@ROfwe_*tqq?)z91tk60(Y)~(oju#jc0 zPm{f6zH|p#YNP8hIYDW^ep_<8557{tC%G&^AxqlNC+I&zMcuQR zAj60Tbi|2sd)O&Q$j*xuKN9Bq=jA@5WZN3>tv_{qWaqvnFFxs{!@CWJm9Z9m__xjB zrwl6M)`ytMB+w10yIw^0K7$5bpmD2Fa=n%puQRHIb%z#S5|gXPIw)~Qo%CgR^8j7~ z7*sjKVs(L{Q`~pxwy7^Y)LMl4sXHGc*21#8KB7coa=k`PT_t__MiDC0)GgANa@K4o zOb0tu`Slk7OxPb56_G<>Y45fH(WUBo2lNqrBV~LpsjnMe{I1~45E({*I;_`Td{k*z ztC?tV8LzhQkFQ#SKF7JBcz8aPUef=l3UHyE5O#v3FBf;v>5MbNKlLzMt9>UDn;ffm zeD?KF2EUn~wU(}~ZZjw^%MF`+-P4tXUv||X%)t;y?~SitB=6n5t7{rv&BK7TTz&RW zzG@e43)n3Ss5<^yg`2BIci_BxFz7e>uG|uyy3oNa#T+K1k1yynwmAs59grX}&o6dl zt7f@)ZXWO_-Xy^5s|1r4WOI{Pl%53kGKYmolg!9+56o9Mj8=$Z?0IxAf@F2u|dyM>%Ws`|G8Wgf58}-ydiGl28Ax zwZkP7%O6;{xcCh~{qwhO@Yj3Hi&cTa1}$<<5)#mP3^7v51oLU>ph!#XVuCm5OQ1iW zA;1oe3(+Gl>Vp9!Oj0M$mWn5UUE zM61zy1sygRO%SOGJ~>Xq>Z4$GZk$ac!V|@=VMlZ8wvpBiD4YokY$^;)j4IgMVbAmD@m6IvB(jVbp`ZYs^918Q$oL&;8{OA2z6DR^w2pc4 z4Johy=~(#Ghf=;>;EnqFpm7d&T7UA}yOIH4Fm>Cw^`8PTlR){Mkw1xq#l|4Hhvk_b{0da0#WpB& zX@HW-A_Um!fu&gzD6{TduW_pHrC{?YmxPG~A4>qF={64v{{_*TpAeP>Yg=cOFNKp~ z74xW5<#OlJwI8gilnY`8Epeiy9$hf1`q&Gm(I|>RG9$kBQNNLK2msS*jckc`bZv_R zH^`Zt(>P=fsp2t{oZZ?fQtxoFfaI*#HfNT>P{_+DAk(0g2ny598Q%IgW%%mpe6uf_ z{I;cVhs>g@O>(f8Q58&pXd{X)p=%eqjb;d71{7?Kz-<8OTE5gGfpUfVbEM60V}X4~VV zgIz9iXW1ATK=zb@nlue-^Wm^8plDy_rfR%{f>wnPmEAJZ4fE5$rs$=(`1$#zcR(BV z+I=x^i6$N1S{7`;x=B@{Hm0N?srX4Xb7YJ+h=eds1RQTHn{+vG6u+RTh*^nf`{)Wg z%>KQ&s;O04`z>$`sR;@a5`G}HqE1kYFFxhfHs^u%`38e2f%}4h-&uwn`pXqe0L=SL zT}7o{n4iDW&BMck*HM;j1Rpz_2}Vur&m$pm#Pc-i0r;6|XH_xo=GX7&-UIc&tHr-5$hCaUepP?fd? z9O$>;ot)YPDmZ%@_f@G|X_K^VfAmLs1=UQ9-ou^6nd#aRQ`6~Z@Q1Q4TfcyTx0e(r zun<4|^MmL`lZKt>6Y$ASZ$RAGnsc zjiF~6R*Nw?s60#5vxxUbUQZbQl7DdP$#H3>&A^Xq}1;`Z6X0<|;j-y=4AOnVf$bMi(l5azv&O zdv18-N*0OzMNo8rPF+G7C^~c}X0UG`sB&bsd_wOYgMmVF5C_E4l9R9U-BON}q@0ELiNa+0biJmA6%kBZ0P0Q&iiU!47)ME2jFyAGo&HmkoC=`D5@z7V69br_S81oRs>Mc-AP?aBV+-bboFkn z-EiJRz?d5pfOh`4*UP}dv#PH+9flsX$2_$ilp>n>N(&l4410h@tADO|-R0i%2TqD1 zm1r;>Z9+{!@o?`#?Nrbjp3LW0A2;J&zvy91b5|LZ_*!&dNJ*eoIH6$E7T_G?nKe{N z>@E$97oDxN!5B3i=y$BX7nAR?Zb1u4TsyZM7~JT!>|qVOTH=0#h!O(vymD-8jFRBf zkbp)WYc$NzPjGNln zUuEfBdhOZfRu4ly1_n<^`K(e7+!v2}qDOU_=3bsB6T2KH4KQ>x;9cDdEbMOyJ4HxT zY}R@_1bTXhCGf_DVsI{MK%Vdh9Us`5la=rn&>akZ+ znKdX$FM!ufi#%foagsDb2lh~4ATF&)<32Uvj6%1v<9q+N@7;$v@U1zp*}1`>g)M0a z1#Rp_oH0j57Soj-zaWc-%2CsRvtV9810H%a0s5L>$}|&s?95uun${iGaSC{si+Xu9 zNDVd)G9UxAdl?%;K~#M3QdjzbmCzN*GZ0tc?(KiwZWMH(+8kU4rB4EjR0ngU6PK2j zsw0H+;}-j~@JOQpXt8mAFc%xY>h*QOsZMM3ad4*>7(po}v-f%bWLvKh%w9JOJG{A& zqgsR<4Se>Kf?w&}Z$0@|?oW|+$t(dg;}%XVCDWVC_IipkXvc%sBE?W1O=g8GVpPcn z?*>fyEz;>e?s&R(qKZU_f#HXvfT<>lubGuY13+`OqQonK{oXCDULNt3{FYn51h0Vs z8d24}i%T#*3oshO!uudH{?sN>2pRJ7La1p@v>-)z4}HL@7^!ph6@g}_cLHhwMX&D| zj8B0fx zo*J@;*@5Xh{WG9P*jQIrM-5)oao%}u+KL$_vMu`Nj1~CNj*+0veINsp;O_?8LP976 zsYT=I4PEEK`!6Qtz2%_N)M`%mP4w` z4tE=lKo6`PbZGSU2`1QvFGufyX^uCRlJ;oU-2l?#Q-tI*&3jWixg6Cg;3bhps>qJ6 zw1SLp??H=b3QVWXn>>sP04*bjukQv(&9~#$bJ6@}%hk)Nz`_$ii1>V%+gElF%TRr^ z$tF8Lko2^|_XRlD+eU|Ij_(urD^~X{SU}EIe?3c-v~Z*tHkh~|;rDq4^xE_avaMS| zZ*4_htoXj@eVh`VQ4j~8=W*kak&>>1E+3iEFqp%D&d3?yw-rNH9MxlN-?_7?>_t4v zde5J1;BT!=S-%OU@i_wk>abVvYGy+3>?iM_b*}gUnWQXc_^Z^Yc)+jSLzCG@z65W( zfCPYdrHS;{EWpcc^<)h>mx7Z#;S72q|J(Ot1SMB!gsUD=wBgjpbI!{xs~2Rv3*%n{ zohtoNlX{Pc#j~4hwbNl4XT~Bqm>7|XcN!19vkz^vutZwx2vZtIdjscruVxtUfpJmV=o1Z|?1xL9Yx_j4vqTw(nyUDc9 zO*TRk)686Y{V>r0ky#*Q))I(MK%k9GUPXsH`<8-I{1z#jA;*lr3gGv|>gwDbFN4X! zIpGj7QXl~0=1Ul^u5xZiWe}AniZUr=?vxVxzOt!15^CGFVs@G+s7)c^sXmL z51cCrWfLR5n1LuL&3?x66l)LJf3e2{xU)WP; z%gmxr2(^CiwUGaZBzBcx@P^S{rE$NsS9Hu*65;Y)A{3Ot*XEPL11uw z@d#k>2{E0AASSeF6Sqg)4H&)~^IE@*5g4xW>8AC^F;)Ed_Mn34WI*eD^0i3k+t1Nt zeG0ebTwOnnl%D7JIX~W>?w+h4=}|!8U*LC`UHNu>>_gz$HS?tice$J?Yu?lykpR^K zm6FlY>rsGC{)8*ORA_04|CPiJt| zT(hoId&xBY|kzz#`S!!Js`91;hjjid-raWTtVrf zYMe=`40v&=OYB!?cqkyco_WwAUk6v`qE+(eZF= zLtF|t=@g)XxLgx2Au{nO{TQS9(badrm!(aM*#VQxXk%I`c@^Tz&6negt+{ypd-gV_ z%Ox!1iHWV5OSj(uWb|I=*5IK>L}Vm8D8F|PJ5SL+=?9LRt2?=tOOYNGdceDV|LgS0 z@k63>0h!Oj5lQ_0tmr1`Z&8inpf&Sq@}0nf#JGI9Xy>5vA=T&E!Om{6X*2q~GSCh4 zaBy(YU_#TkuzJ)tgYNv=w(nQK@P;O(rQoe9Kf&Qo{Qv5D??9^izkeKAnFnQL9V^)i zDSJC2GE25(WR{V=SCLir<`~)8BT_=cJR&0`8OJ80Q2m~#xp16i z-tX6VJ|F8Xe)Q7gTC4`n*Jtn?*>qLI)CW-ly})NHxgOfbjBPt8_mKI}w_Sdweak|& zEMnlcRYH&0!F?iX^5EO>Mz?rs7WDOT0Oqdseo_%L_$yICtlAk#=a4%a=|Kj9Q39NX z?40NFd%%z4UTA~|B(G&uLs=*0xpe?M<>$FY5CL2dK$nO#r>3iCu>UwUz$+7_SevOk z;Sq*nZYibg`);K}eeqV^4-Rci-}gJ_y%n+)>o}sGb4ey#>*&+fRqSf>^7Gv9GvG7$ zgx{(WU9WAUdVPokx6ymX-VmLOR^w_wICQa1o2;HW;wvM>kEf}bJN|NBEwF>*+@b&* zv8@qHWc-7)sNn5iWQiB4Zw<2$l8(FOkFef)>IqOFNhC5F1i2x>1Ny(~XCuF9dQoJy zIp6t)Vy1+upxX>7SN^Geo+|N;Jn6E3P&b#54#>055?nN07QBj{X1Um+g%BmepO)r4 z+b0r|)zJ0i{5OTCDU1%(lVW>%^d8n3TE#Oq5z2`{a;E9sDp9D|da6^ZQ9`)mzfQ^p zWXs{<;l~X)9E@vYU?rR3h%lrNG1P((i)#c`##;zB`EAs)#Tp1@Ux&%5OK1E+n03jl zp`-|A!rMu!K|7T1IuTC5ZJzh_Fa62f(kNs#OsX8q5viGjzRvnpUEJV^HM4$>WWda153Yc2E6<~c8HKnT1I1m)l^R&*+!a;NrsJ2fp z;aWVo3F4aV1_!ZirU;1d2t*H4E*;h zicWwR(s_^m)gTQD{8vIx1N0*o?{ou&LcIdTyb{RSn8;S@%nJUv=-DW2_|Mb7w;I*3 zh}cf1WWM-Sv5OQ>qhrOr)dF|*Z2wc0I-kePWOCkLQBgQJ(wrKrFz#BZkEu3m8@m!+ zKQK&drWl3$eq$A^{z$lq3?3js(=eN3?NQ#}`)EO$Q*e2pk?g z1m3#Q9{Z0f>sjzf#}iPQ=lKuRR8=d%B*{vx+x!;*W!OkL z@!tTb5Ow9_Bq*m$VFRnNDlAtX2z0-K^0h)M+@{UtMf zhzLL+o>C}1C%4z?24{q@677UTwoRT`%)%S!*UgD*ZbaAj6I-;dGT~MaEW}IsX5iue zx&%VpD5KJAFY6Q&%85ddik82B{apUkB6h2A6R%U0pC$%*4OW;wm_Y?NzdcqZe*MK3 zT(zHH!|$<^Yy}L_fh9cfOxyiUZRRA9695R851?(SehJkXNf)Pd#`j=>g7^DhhVW{P zNVbemQi^4UL=8$;sQ=Q}d ziP02kDO_oF?1^WOhqBhPGZ?@5=l+y#u@=)Fjc&soLr?Ew=#mp+$(XwMRVL?qg+`du zuD3!!k#ot_%wnPLC+6g;nMg}20vz}@1(<`(<8NxfkZnd*-!L%vFbv$jMyT)RR^6!C z*M$E9SrS;Ah!SmyGNAW6jtn`gSX9yo(+CHMDY`a5hJ=N@=-Vc3&g{fWC}dJOhXwiC z?#`>l$LK!ac_+ZX#Brqgzis6|(7a|Hb2ojBLnqqol{qVA9n}w`B8_D>o_`x4hJK57 zuwKVC_Y(^#saxC{h}k}YXFyJjLsQ+CwC|HH8DVpK!?S(R@3gxtYE7KmqF0cfJ^;SE zj`6)39`!^HiViRGlIRC3@V4;#hu%BfbpW}lnNOvN`SWOiU7jB2gYHHdlvW=k1bwt< zolyXd4L#N8P1xNLeam3sk3Z%)`2RPb51#qIn9mugRYjE*ZCR`?PU+lXq29W~Yc)nzb#0p>DijpJ^ zLix&n?^Btf!0X=L`3bvRLk{*ViXTOjd5R}goB2qn*$lpdfa=S;I+Gep#nWsrce(+1 z#jB$ewF$M!K!aLHDdM`#VtaoqN{mFLi4IQ9qRIQIsF8vDGd?7MA9n#pnUI!7N`JyK zn)HEu3_0l6kQ^NNT1U!X2C0enm%w2964qm~WY*06cL1uV$U2pr9P+^;Dk3gFx97o`Jz)=kiO4o{Vm?T}Y?$`mg(Y%mi zf^lMz^{qdYE&sly9KwF;m}6p5r{<*WaJ=mPIHkFty1Yj5d*T+m$%+crDz@Ycu$R!e ze|@7{0*$oK4{eR-fi>-h`&jBF#}v+AAX^j${Q3fVWwRvNfhMZHQd=BvKIckJn+U zWOR+V>xJet(Bz3-P^V%e`oQbI2@18ho=HVtA4j01YbyUwZ@q!>4YIlb(Y3I!j%T@CfGX#RHMBM4_I;>vj|R zbzHADuS|UMm}_xn-ou7OxoR)lI@W%Pmple0jQUTuwdUt28jV zJY!I8;N-EHv^+WTj^Ej$^`2Uc51Gljb9OP;D#gwot)^qRGs^8tMeJ z`TP4+5fR|3Xa`M~>BZ#3J*V!R3;?Bua;CV$g|%)53-NBYoWugLN6(dBzaSm*>l5#l zTD9rRk(G9UsXT&@PUM-QbLb&{j09T8kTq|@Mh%@qOfTviQkNA^2*3V*>|-XIo2yRhv}OPd*@7Kiw12*E)KVARA+fl<<_l18 z4#es7oa=Mr-LGFC4?$saM@uTtB+WZGYQJS)(>ue(L-u0{mzgUZ_BuG9Yj5AZ5(L^Ghe8#d(8RZ4Z14Y{K7A5_PNjec7dm{Pn0{zemsB9| zR?v~;))pgIKLwKv-kWPQ#TA8ewrQfTYhLPeUTyPnJsh|5y_QB*?RT)T(#1LcK>RL6 zLIrC({?)6{LN>mNH? zQdJqWwAhlflSPtk$vF{&7c&_Eq*xzz<1q)W^htu!hqyDhkrRV0C(4n&ukHM7cwtb# z73bxT$vq!^PD4Qd%W&5bAclsGux3=7pmB3iCp&wNE z(Hn}+GC|3c=crc`4Mxhd64BL8Zydi9sWLO_S${3<_%7Bq;Oy3i4LB4@g+FI^*{(|EnDCTAo1vacJ-Y1gJfq2JF zRKpn!TvAepF;Jw*zZ&Ah1zdb*z#kZexPXCFP$^SX9p{HgypedHEYRct6m^c_E%FMv zhYeK1-CJfkir@C}zCh{wrfnYx>+5%kN9ozH(``(c!)j4!q6fVCpYDd-pShP`l8R2` zen>)Tte5$84HcN{w{dxE2rs63NV#8#**9Io?Z@w9>85*(zKYgY?)6`CEY`mjE8eAw z8c>gAoJ&HLG$l8l*Uq%bYC%6bL2lr-^HoE&z()t@1TtPLC7&Mu5w^va;${%bvL5x+ zobt^}?+!mdO#FkIoLs+kO$q%7zt;P9*I)O!;Q}LNfv4joLBTZ)?B`tEXK!}BiGG-; z6fB($rHm$yP-8G)CC?i$c&fM11q6otLRQtq;64U@S(V_`mT&kv)UG8Xd;jDCvqmbD z`gvb{6+3aBN;!GzryW|Ra!tZyg!trKmamREjiqH6HZ%^M!b3FU^eI*%PUV> z(8ZctpKUrxK=#MR`zAvX?K!D#1_mN7{=-nvLEtR3E^@43gkw*X5Bhc8$9qt@Ua?p8)#P*%6R2T!9R}#UvyLl!ZB`r_Qmhpc;6yWe!u13WJA0KZgwWo z#5os-dFa{e2^vd_<2yv25hgUXhl0=~3#jSS*Z6PNpTiN6^-dEzQm(^*0@pxKCD?B{ z;6tBmP35!LDH*Ox&Ized8@|3hIo@9$)W0$`=1(U7q=fs<2T?U9KS^t1tYKn#+JG%1 z-#@7DNuNw!f2QPh)uHd^m&sSP62@y+YI#*An^PLtmj9dPai7T}c@9$RvJE16Qt)Ty z-_aCZ0$pu`8SUY&_dRVZ(+f*3zll?FJp$Tl z)W55h5&B1?%>cuf5Dy_BXodp5bG;f$hty)O|YSO zza)-5XkI3hBGdv;@vVAxy!nilRCQV>iA0!-TsW3V)w{(~R8lBLRd=~)&iZwwnbG7+r4^W=13fd~xL#9AE zf>`;}Hj4Qp+vR&IKGjSYm0sP627LH+$~WAOXSntq@P;y!>`6iSW(@<`ZItV$W*Xq< z4cV7J^!|t$^aog8w?vy2PEe(Y+JuTE#E9naUiP41!yFB?vCL*ss=3~1cB+s`@#5uQ zAGc7Dfcl3L;IC5O(P_)hhFGDr|0(!urpP@7HbIABntIZ-njvh@9pdut6E`UGl3f;k`u$620sZ+oubeZ*7f+deuhC@B;4Jw)$*LdW0w+HIOW>uWJ=kUZbzaz;kuW#WCaEUQH zSyo)o5NLllgTR7^2B(9$@glIDvj8HzXw7K-ja(OdeL+__`4e6Myg)hPw9)NiXrqXB zy+_*mFGst_ZR_fYNZy}X7X2KTN%LaBC+6dA6*SYGS0@UeK<&v#E%CNqVEe42I@D{w zW!x7j^k)JVu2dr&Ml5(7kO_ZwLQ0bM;mE0H=kYf09UVI+S5>f9@XZo;u7UNS02aDK zl(okROOgP!G~y;ltn2`)c?;8~>}v4)*GIz|!_*@sw2!>(h-q^((b1%1^#s1x$Ppvn zw-_wr_qq^Bw)O>ivBfj*ZR-J@iL+3k>AQb{Ssel`>kldE<(G?D*sS7yx_EJoLwz0D zA{h)t$yPXOWWJA8I8rYG$L^T>_`9|&&{xY~z+9^PEi#cQ!u;-rSEANqlvsF|8yVwo z9WBNcD;EDxb$0O?t`{H&G>UTiLHhn~%^VOeNzg$1UETgRO15vAf$>=!+1*8If zs|KFA+h^nStX>i)PbW&T;EfY_4lbI$C~UUdXKa|y{`2G*;dbR1`tuqwj&qHI?HK5T zTIM({9*Cd57h;=r(etthW}oHstRE}#Tg)bFLv-YnOWXP?KoVn4(8DyEyuP38wdE96 z2l_sIC~geC6>-3g^>xK&XJ5Me#nX5CW3fNF z(^Z%+CTNY6TcRCzUR^YqdF4jt;&;y^spMFUF4DzqZjPS+R&ll}N#f#{4k&|}8y`7e z7Cj^7{O4>njn{kzi9K|%>fXQf4hllq8cUB=nU%lce7g#U$-DvXA@ZLfF`$OVoekKQ zs#`tck5S(O=P4qFb?!&w;^T@hL~iAAEjdgoQ*VPk_Y{-u8-PKiHEn&FycA6s-zip$ z&!;gpO+&g#Dw_k_SsO+s<-Ro4uMkp5qCC~?CAyel?$o0=@@<1Jai80fWPTinDP(12 z+(am3Asm99pU0?O`@@x=)%K|S$Ccyt;<4;~MsmtdxgJ?^&r`9vd&)NnUViYfIUbLC z79qyfre=Hp3{B~-3GtYoF79xCvi`g znE_md#y&Mnnf=Of-2JiDi=Kci8sz`Uq6|+v->3HdhHq$2;tbShrN8dV6+~rjV<<)} z_o=V5IYjyn5eM44QOzqV<-Gs?^|4N80%MQKx56+IDp?*(PV5nI_dx(8;WzF3+IZ&T zguJLkfSL=PhS67g6)^O+Llh%4(mU znaN-_^1jYVfF4KxJVxteayp}r5f*zzq=VMMw~x_WiJ;%vh-MZxq(G4LGf`-Q*p7G_ z_R=mmB^g(aN?WR58ji*7o=LNg+oZq0#!^%|?aKY8>bcuo=#_|G1eNbAtc>Li(vi;jU8!RY|q6G`HGhIL%@{>tgWY{vF6B zy5RKkP1zhj;p^+1S4AX8ZauRnXu7ZJuihC6t2@spKOX>~APVM-7214RZ~jXQa88-B zf$`9QO}cXpW;ceT+QO1d zZ7&xP*+`#pj>VkI2SmE+&CFG zH8}9YLE`?X(TdZh7vBT?|EEi-YSrRsn%_ZG8sQf8zpO^5n*?-DCJw|6Ke>2<7@t|# zLn>Ol_xcXXG4LJJQD3En?fmC4UiasEX$Q${6`(59yp4|vDw`4QGUIeMxcD`okFge{ zIG#6i*f@$`ehE2C1EB??FHm4KSJux{2vG(Y{rMxFr$2?#Z?A7P31Qd_Rt74lG(ea4 zWeo_h8P-m{`{w~66V|(zErdI8>ZIZXH}upB6ZIypaix(^v0Uq>fLbX61pcKXtEP+_ zFMbDlEDzy>-dNbgJryM_@FrVY5|<9aU-WEcqj zdbK>~``fekW%2?qsAk+ffuDk8hi+L161pUdW#4`UIe<&BKbt8=)wh1vJ~-LsqE@ip91;NAkR6gR7X%Mq_%Nfnk2 z1aRsjuff6mtyfvA)NB+>D zUM<8MLfmJR&#ybeO87~~>HH=71=xUKvde)^n7k)=N3@{4g6(VuM_IcHZr-M%d;(1X zGzw%sZ>^$XM0x6&BmsaL`b(OZ)Gs94t6}~bs%uLp_;rTg{U>22HsVhE%wGe*U4tmNSkd(mCzC=R<5POeVl=SNZ$Z32Tjm2 zXX{quT=AcP|JHl+CW~XxKwt#R!_8gl&dqdEj0VJ9E;wXP$hGfQ|BpXW{#Z>t-$Jbo zNX$8jpK=wd=+$lDMZdiKP%U@}3U{?IA+vsSoC-9l;RNabOcK!Br>ZI3!{v4s70LMR zSMa;{*G}M=ywc}uPoUC#zj^f)M_p9#%nC?kx#!?-JPdM84sbI09@TU0(;wp1Me_7`YS!B zD40#f04y^DhFF5_!tNDDuIXZ+zeemJ`Dh`T7@ovHsz(T^j%-c0dgGSx`lvC&hlM7P zg--pX=ut2Po7L}IwQ+HC+x&)k@A8h{qGmru)vA+Y3pnLM05kc3$C6?8=$oQSK-FiE`!f<}Bk&xHgQ7KX1oB>vr0(xe zwlH3zj=!-YMu5|^4nvHW*uwBRizj@Xl$Mt8#fYzh#|*=8`(8B?A^6{qmB5cZnIhLR zK@BA3*=zSeyemKe(oT!3WaCEwNt>vvsdY2~hW|DTQB$}q-}T~fMF1yu`x}U1A`vYP zoGUh_20CQ^czF?iG< zTO8B!Y8R)x8$v*&O?^hZ6jAQ>kQ8!!Kvmd2vNV`$$G3Ic*er8&b|hLn_ztMjO?qRQ z9&56_uCRRkf<%De_zLTPCFY3TI7-)eQBRA7enrIhVB;qW6o^iwMIOcow?~}-*=&RN z+TRCOZ0ni3wYSIO{$~QoJ%`tN21I-WK(I+k0!%4^H@Ui8AeLC%@gFI?rp$=c=hLhq z;drvcfcJ4daH04dqfl#BSc%KTy9q7L56EnLQgi-M7kGvn^|t2HbEqVCOAw{=Lp2t+X)Z1K{t5pe1_^;P=KQzktpmrboLf8A0Xrkd#;h z+EZ2E-DMg+5=7YiT%viiS}+MYu$A;L0HBly?mV~tDeq*xIyXqZ*da@}astGG;aZuI zwdbg~3Bi!T@B&!y1(?6@nw7#2vY)Xg3hSZYbb!=h29(eOo4Svsox}cTO3dgeHa5CG z-|v3~`8<5kf6Lk$c^cuVDB@d7j&CF=6L@@Se`7iZ!1f-PX(HTwd{|0mHo@H~M1mHm zUYm@8g5ZQY`y|xw%)6KbRfMIMc=;4;5K{FPcqcI_>7J{#we=j70uK~xx57A!Z$DCi=eIO~ zK5GP`Ql`Fq`65RwDze(<&&w8*)fX>^Xx^h!Ips&=$Ki%JJD9|6`cABRW9ti@3-- z0b5mK+}A2r2X+O1mAouG#f&L@e8P9+HI5_)CkPx6mLKE9k@`gNUr1C5emXxQx(x3K zrSAC^d(c5BGpRngH+ycqoZX*2q?8@!EMBt zaG&q8Sk3FpQ{$D0KFL8z5C1v$Tz?UrSpCJ(#}f(J$5i*q>a*otK473 z`e4|do}lU^0&P}^MiMGtkByBAK&9{U;qteio!|Ghv~AUIBf??}-DU1PjkmL+zTJi_RHTm%k#| z`H8AE;PyAklaf#;({m-*!mP-6`IIUon$$*fg$p|eXoE526B&Ysg%jg>(8gp@ybT<$ zR9$Z}D;(3KfM0z8j>ODwz2U_ro@AtR#6;h2F#ZV-U|m*=GhObzcuXUhh-7`KSn@s} z?tYXD3X33MVz^|8DNK4-Eabet;oLM`e8cUH_ldAEydz{%F2v-C*&0lFm^50|VL;~b zd{uFh>^Xd|+pG0LPo~b?iTgkZb7pNaaWcV8f6db+)a?i7T=7$+y`fa{~5_ z!Lg;_L=8Zrrs^Nu*!{QvF(Do!n>*nQf`*HUFI$pxot}wgRp?4hm$4t+< zkGF=om$i1L_+)vG8NYqP@WUNPO!f+Pw5fR_w|S7z7~b{z<|d7T2+O;n) zoB}q#Kb@v(gAqu3FmYO7W1lgLVYZnz!I1WNR*+jR+%N~Lm|**nilHZh6M<3-MrOy- zFL8c$4e3bAiI#Y#f+5yeFRQXsYqhNfOtH024flA9 zsz$u2RUgY;cEC2ma>O@AlgW_5qs-ZpR&98Ax7&dA?#ESHd7gZW}cZCtAgwq zU*Nw3pUM3I3HTV;Lh2z=)^4n|cJKXDLM&u%U%ze<(D3c7>eS_M63S^N%Rie@vzYjk zP=!~p8HPW-M1yZZHZIJ({qdt`s<>pg(Z!hc))Ra?=U>eY(-EAC$NC6XW`ypfk_sL zqEu_zE=vdntZFerod(ioZc)`F*><}aI}x}1K0BUl0f%_<+r~700L3oq>7M!qPl3Qb z>t!2(LK~P@i_6v9jT1}z>r-I)3A_U+b~5S#F?NRtoPo=*8jT>zIGgFNpXa40KLTMA zhob|T2{W%xs}!)2>%xjwA<1!xQnRe&&P@K5drxfSsmDMLXPb(iE`P+6wiM(#txdPJ z)5)lQ1%^|nN}+yX8&!H{PS(tVUe(OFIlcebd_SU=1`aPpsWL8|7hT8%0f#m;wdto7 zmr%4HcfblQLUEGk&BJbg2-q4(@rEXE>3%;8gvH_ec}5^`P@dk}b*?g}E)~pxP_%=h* zH3u5xBA~K%UNKX*PYX{jAf5Z`4qk2EYs-ETg-2iri@QY{L0Z)*l(d#Svp>62y{BEI z{+kC|Gp==?f8ljC4-5^(lz(aqHZRNrZH~`&_@VW=>QRjx*V=;_6kAKU{qFTwO1i-N z#L$!~buJ(S63~^FT)_&yFrBe`#TN-bo!a6=O`Uyt@xAkVwNIBwF)ruy)Xou^Qel4c zI)tNjlpd&-Ahw>uAyjfgxekF+=!`)+kH)3$Qm1-tAW^)c30bsP@fpJEW$o=>sJ5QV zNZLIU(ubQ&b~^o}X#UTJ3EB;23)Q@+wx=4#`Lu55QMo*CU+tD&!yjfMBtSy#(1{#Y zAuK~|1tbg%49v*+?XP_bqpDrVWFbW&7;wSb?JEK58X6k1sRmRDyV;tzbtwo)xzE7? ziFi1I*vb!1Rh%@J>_Co2r9yDoZw#1RCR)H?Cik^agVaXb60BgYATPC;X>`uCI0znO zp_1T2AYtwW6UP*DUQ_IRkCauzT-3NRObSziV+kW6A;JGf!Ml$g8XVNy=sGOC@&A}p&IawWtNN+&E`M* zF-pl2qK?u#N>M;L16Rq_5nI^S<78g<7$w5$PE1S`nl#*LD1p!W0jbmV5SUN^LQYY?p(aw&wNEYjfb$N)g^>U%xB&XR z55jzWEy{Wjt&v-W3{x{ z#nz-T$}q*yRIdj-DTS z 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 w-M`BWf0Gb)shLsjxBo5yu3aEB`1~9HY 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 diff --git a/docs/_static/usb_host/poweron-timings.png b/docs/_static/usb_host/poweron-timings.png deleted file mode 100644 index 59973ec9cef28b29a8e387e4dccb3622ff80b4b1..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 39353 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 Z%_=?Au4!Pv+`$0E5ih@k<(}B9e*^N@YyAKK diff --git a/docs/_static/usb_host/stack-overview.png b/docs/_static/usb_host/stack-overview.png deleted file mode 100644 index 40996041de17cf705c4bad02cf2c4e837235a290..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 19318 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 diff --git a/docs/_static/usb_host_lib_entities.png b/docs/_static/usb_host_lib_entities.png deleted file mode 100644 index c22186dae42dc7023aa043c80d9847d980405934..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 65445 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. - -Features --------- - -- Multiple supported device classes (CDC, HID, MIDI, MSC) -- Composite devices -- Vendor specific classes -- Maximum of {IDF_TARGET_USB_EP_NUM} endpoints - - - {IDF_TARGET_USB_EP_NUM_INOUT} IN/OUT endpoints - - {IDF_TARGET_USB_EP_NUM_IN} IN endpoints - -- VBUS monitoring for self-powered devices - -.. Todo: Refactor USB hardware connect into a separate guide - -Hardware Connection -------------------- - -.. only:: esp32s2 or esp32s3 or esp32h4 - - The {IDF_TARGET_NAME} routes the USB D+ and D- signals to GPIOs {IDF_TARGET_USB_DP_GPIO_NUM} and {IDF_TARGET_USB_DM_GPIO_NUM} respectively. For USB device functionality, these GPIOs should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug). - -.. only:: esp32p4 - - The {IDF_TARGET_NAME} routes the USB D+ and D- signals to their dedicated pins. For USB device functionality, these pins should be connected to the bus in some way (e.g., via a Micro-B port, USB-C port, or directly to standard-A plug). - -.. figure:: ../../../_static/usb-board-connection.png - :align: center - :alt: Connection of an USB GPIOs directly to a USB standard-A plug - :figclass: align-center - -.. only:: esp32s2 or esp32s3 or esp32h4 - - .. note:: - - If you are using an {IDF_TARGET_NAME} development board with two USB ports, the port labeled "USB" will already be connected to the D+ and D- GPIOs. - -.. note:: - - Self-powered devices must also connect VBUS through a voltage divider or comparator. For more details, please refer to :ref:`self-powered-device`. - -.. only:: esp32s3 - - External PHY Configuration - -------------------------- - - The {IDF_TARGET_NAME} contains two USB controllers: USB-OTG and USB-Serial-JTAG. However, both controllers share a **single PHY**, which means only one can operate at a time. To use USB Device functionality while the USB-Serial-JTAG is active (e.g., for debugging or flashing), an **external PHY** is required, since the PHY is used by USB-Serial-JTAG. - - .. note:: - An external PHY is not the only way to enable debugging alongside USB Host or Device functionality. It is also possible to switch the debugging interface from USB-Serial-JTAG to plain JTAG by burning the appropriate eFuses. For details, refer to document :doc:`JTAG Debugging <../../api-guides/jtag-debugging/index>` in ESP-IDF Programming Guide for your target. - - {IDF_TARGET_NAME} supports connecting external PHY ICs. This becomes especially relevant when full-speed USB device functionality is needed while the USB-Serial-JTAG controller is also in use. Various external PHY ICs may require different hardware modifications. Please refer to each IC's datasheet for specifics. A general connection diagram below is provided for reference. For more information, please refer to `Use an external PHY `__. - - .. figure:: ../../../_static/usb_device/usb_fs_phy_sp5301.png - :align: center - :alt: usb_fs_phy_sp5301 - - A typical circuit diagram for an external PHY - - **List of Tested External PHY ICs:** - - - **SP5301** — Directly supported by {IDF_TARGET_NAME}. See the guide above for schematic and routing information. - - **TUSB1106** — Directly supported by {IDF_TARGET_NAME}. Works with the external-PHY driver via GPIO mapping. Follow the reference wiring in the TUSB1106 datasheet (power-supply options and recommended series resistors on D+/D–). - - **STUSB03E** — Requires signal routing using an analog switch. See example below. - - .. figure:: ../../../_static/usb_device/ext_phy_schematic_stusb03e.png - :align: center - :alt: External PHY with Analog Switch Schematic (Device mode) - - Example connection using STUSB03E and analog switch (Device mode) - - .. note:: - This schematic is a minimal example intended only to demonstrate the external PHY connection. It omits other essential components and signals (e.g., VCC, GND, RESET) required for a complete, functional {IDF_TARGET_NAME} design. - The schematic includes both a +5 V rail (usually from USB VBUS) and a VCC rail. VCC should match the chip supply voltage (usually 3.3 V). Ensure that the external PHY and the chip are powered from the same voltage domain. If designing a self-powered USB device, connect VBUSDET signal from the external PHY to {IDF_TARGET_NAME} for mandatory VBUS monitoring. - - Hardware configuration is handled via GPIO mapping to the PHY's pins. Any unused pins (e.g., :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num`, :cpp:member:`usb_phy_ext_io_conf_t::fs_edge_sel_io_num`) **must be set to -1**. - - .. note:: - The :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num` pin is **currently not supported** and does not need to be connected. - The :cpp:member:`usb_phy_ext_io_conf_t::fs_edge_sel_io_num` pin is optional and only required if switching between low-speed and full-speed modes is needed. - - Starting from version 2.0, the ESP TinyUSB Device Stack supports external PHY usage. To use an external PHY in device mode: - - 1. Configure the GPIO mapping and PHY using :cpp:type:`usb_phy_config_t`. - 2. Create the PHY using :cpp:func:`usb_new_phy()`. - 3. Use :cpp:func:`TINYUSB_DEFAULT_CONFIG()` to initialize :cpp:type:`tinyusb_config_t`. - 4. Set the `phy.skip_setup` field of :cpp:type:`tinyusb_config_t` to ``true`` to bypass PHY reinitialization and use the externally configured PHY. - - **Example Code:** - - .. code-block:: c - - // GPIO configuration for external PHY - const usb_phy_ext_io_conf_t ext_io_conf = { - .vp_io_num = 8, - .vm_io_num = 5, - .rcv_io_num = 11, - .oen_io_num = 17, - .vpo_io_num = 4, - .vmo_io_num = 46, - .suspend_n_io_num = -1, - .fs_edge_sel_io_num = -1, - }; - - // Configuration and initialization of external PHY for OTG controller (Device mode) - const usb_phy_config_t phy_config = { - .controller = USB_PHY_CTRL_OTG, - .target = USB_PHY_TARGET_EXT, - .otg_mode = USB_OTG_MODE_DEVICE, - .otg_speed = USB_PHY_SPEED_FULL, - .ext_io_conf = &ext_io_conf - }; - - usb_phy_handle_t phy_hdl; - ESP_ERROR_CHECK(usb_new_phy(&phy_config, &phy_hdl)); - - // Initialize TinyUSB with default configuration (event handler can be set if needed) - tinyusb_config_t config = TINYUSB_DEFAULT_CONFIG(); - config.phy.skip_setup = true; - - tinyusb_driver_install(&config); - - This setup ensures that the USB Device stack uses the **external PHY** instead of attempting to configure the internal one. - -Device Stack Structure ----------------------- - -The basis of the Device Stack is TinyUSB, where the Device Stack implements the following features on top of TinyUSB: - -- Customization of USB descriptors -- Serial device support -- Redirecting of standard streams through the Serial device -- Storage Media (SPI-Flash and SD-Card) for USB Device MSC Class. -- A task within the encapsulated device stack that handles TinyUSB servicing - -Component Dependency -^^^^^^^^^^^^^^^^^^^^ - -The Device Stack is distributed via the `ESP Component Registry `__. Thus, to use it, please add the Device Stack component as dependency using the following command: - -.. code:: bash - - idf.py add-dependency esp_tinyusb - -Configuration Options -^^^^^^^^^^^^^^^^^^^^^ - -Multiple aspects of the Device Stack can be configured using menuconfig. These include: - -- The verbosity of the TinyUSB's log -- Device Stack task related options -- Default device/string descriptor options -- Class specific options - -.. _descriptors-configuration: - -Descriptor Configuration -^^^^^^^^^^^^^^^^^^^^^^^^ - -The :cpp:type:`tinyusb_config_t` structure provides USB descriptor related fields that should be initialized. - -The following descriptors should be initialized for both full-speed and high-speed devices: - -- :cpp:member:`device_descriptor` -- :cpp:member:`string_descriptor` - -Full-speed devices should initialize the following field to provide their configuration descriptor: - -- :cpp:member:`configuration_descriptor` - -.. only:: esp32p4 - - High-speed devices should initialize the following fields to provide configuration descriptors at each speed: - - - :cpp:member:`fs_configuration_descriptor` - - :cpp:member:`hs_configuration_descriptor` - - :cpp:member:`qualifier_descriptor` - - .. note:: - - Both :cpp:member:`fs_configuration_descriptor` and :cpp:member:`hs_configuration_descriptor` must be present to comply with USB 2.0 specification. - -The Device Stack will instantiate a USB device based on the descriptors provided in the fields described above when :cpp:func:`tinyusb_driver_install` is called. - -The Device Stack also provides default descriptors that can be installed by setting the corresponding field in :cpp:func:`tinyusb_driver_install` to ``NULL``. Default descriptors include: - -- Default device descriptor: Enabled by setting :cpp:member:`device_descriptor` to ``NULL``. Default device descriptor will use the values set by the corresponding menuconfig options (e.g., PID, VID, bcdDevice etc). -- Default string descriptor: Enabled by setting :cpp:member:`string_descriptor` to ``NULL``. Default string descriptors will use the value set by corresponding menuconfig options (e.g., manufacturer, product, and serial string descriptor options). -- Default configuration descriptor. Some classes that rarely require custom configuration (such as CDC and MSC) will provide default configuration descriptors. These can be enabled by setting associated configuration descriptor field to ``NULL``: - - - :cpp:member:`configuration_descriptor`: full-speed descriptor for full-speed devices only - - :cpp:member:`fs_configuration_descriptor`: full-speed descriptor for high-speed devices - - :cpp:member:`hs_configuration_descriptor`: high-speed descriptor for high-speed devices - -.. note:: - - For backward compatibility, when Device Stack supports high-speed, the field :cpp:member:`configuration_descriptor` could be used instead of :cpp:member:`fs_configuration_descriptor` for full-speed configuration descriptor. - -Installation ------------- - -To install the Device Stack, please call :cpp:func:`tinyusb_driver_install`. The Device Stack's configuration is specified in a :cpp:type:`tinyusb_config_t` structure that is passed as an argument to :cpp:func:`tinyusb_driver_install`. - -.. note:: - - The :cpp:type:`tinyusb_config_t` structure can be zero-initialized (e.g., ``const tinyusb_config_t tusb_cfg = { 0 };``) or partially (as shown below). For any member that is initialized to ``0`` or ``NULL``, the stack uses its default configuration values for that member, see example below. - -.. code-block:: c - - const tinyusb_config_t partial_init = { - .device_descriptor = NULL, // Use the default device descriptor specified in Menuconfig - .string_descriptor = NULL, // Use the default string descriptors specified in Menuconfig - .external_phy = false, // Use internal PHY - #if (TUD_OPT_HIGH_SPEED) - .fs_configuration_descriptor = NULL, // Use the default full-speed configuration descriptor according to settings in Menuconfig - .hs_configuration_descriptor = NULL, // Use the default high-speed configuration descriptor according to settings in Menuconfig - .qualifier_descriptor = NULL, // Use the default qualifier descriptor, with values from default device descriptor - #else - .configuration_descriptor = NULL, // Use the default configuration descriptor according to settings in Menuconfig - #endif // TUD_OPT_HIGH_SPEED - - }; - -.. _self-powered-device: - -Self-Powered Device -------------------- - -USB specification mandates self-powered devices to monitor voltage levels on USB's VBUS signal. As opposed to bus-powered devices, a self-powered device can be fully functional even without a USB connection. The self-powered device detects connection and disconnection events by monitoring the VBUS voltage level. VBUS is considered valid if it rises above 4.75 V and invalid if it falls below 4.35 V. - -On the {IDF_TARGET_NAME}, this will require using a GPIO to act as a voltage sensing pin to detect when VBUS goes above/below the prescribed thresholds. However, {IDF_TARGET_NAME} pins are 3.3 V tolerant. Thus, even if VBUS rises/falls above/below the thresholds mentioned above, it would still appear as a logic HIGH to the {IDF_TARGET_NAME}. Thus, in order to detect the VBUS valid condition, users can do one of the following: - -- Connect VBUS to a voltage comparator chip/circuit that detects the thresholds described above (i.e., 4.35 V and 4.75 V), and outputs a 3.3 V logic level to the {IDF_TARGET_NAME} indicating whether VBUS is valid or not. -- Use a resistor voltage divider that outputs (0.75 x Vdd) if VBUS is 4.4 V (see figure below). - -.. note:: - - In either case, the voltage on the sensing pin must be logic low within 3 ms after the device is unplugged from the USB host. - -.. figure:: ../../../_static/diagrams/usb/usb_vbus_voltage_monitor.png - :align: center - :alt: Simple voltage divider for VBUS monitoring - :figclass: align-center - - Simple voltage divider for VBUS monitoring - -To use this feature, in :cpp:type:`tinyusb_config_t`, you must set :cpp:member:`self_powered` to ``true`` and :cpp:member:`vbus_monitor_io` to GPIO number that is used for VBUS monitoring. - -USB Serial Device (CDC-ACM) ---------------------------- - -If the CDC option is enabled in Menuconfig, the USB Serial Device can be initialized with :cpp:func:`tusb_cdc_acm_init` according to the settings from :cpp:type:`tinyusb_config_cdcacm_t`, see example below. - -.. code-block:: c - - const tinyusb_config_cdcacm_t acm_cfg = { - .usb_dev = TINYUSB_USBDEV_0, - .cdc_port = TINYUSB_CDC_ACM_0, - .rx_unread_buf_sz = 64, - .callback_rx = NULL, - .callback_rx_wanted_char = NULL, - .callback_line_state_changed = NULL, - .callback_line_coding_changed = NULL - }; - tusb_cdc_acm_init(&acm_cfg); - -To specify callbacks, you can either set the pointer to your :cpp:type:`tusb_cdcacm_callback_t` function in the configuration structure or call :cpp:func:`tinyusb_cdcacm_register_callback` after initialization. - -USB Serial Console -^^^^^^^^^^^^^^^^^^ - -The USB Serial Device allows the redirection of all standard input/output streams (stdin, stdout, stderr) to USB. Thus, calling standard library input/output functions such as ``printf()`` will result into the data being sent/received over USB instead of UART. - -Users should call :cpp:func:`esp_tusb_init_console` to switch the standard input/output streams to USB, and :cpp:func:`esp_tusb_deinit_console` to switch them back to UART. - -USB Mass Storage Device (MSC) ------------------------------ - -If the MSC ``CONFIG_TINYUSB_MSC_ENABLED`` option is enabled in Menuconfig, the ESP Chip can be used as USB MSC Device. The storage media (SPI-Flash or SD-Card) can be initialized as shown below. - -- SPI-Flash - -.. code-block:: c - - static esp_err_t storage_init_spiflash(wl_handle_t *wl_handle) - { - *** - esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, NULL); - *** - wl_mount(data_partition, wl_handle); - *** - } - storage_init_spiflash(&wl_handle); - - const tinyusb_msc_spiflash_config_t config_spi = { - .wl_handle = wl_handle - }; - tinyusb_msc_storage_init_spiflash(&config_spi); - - -- SD-Card - -.. code-block:: c - - static esp_err_t storage_init_sdmmc(sdmmc_card_t **card) - { - *** - sdmmc_host_t host = SDMMC_HOST_DEFAULT(); - sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT(); - // For SD Card, set bus width to use - - slot_config.width = 4; - slot_config.clk = CONFIG_EXAMPLE_PIN_CLK; - slot_config.cmd = CONFIG_EXAMPLE_PIN_CMD; - slot_config.d0 = CONFIG_EXAMPLE_PIN_D0; - slot_config.d1 = CONFIG_EXAMPLE_PIN_D1; - slot_config.d2 = CONFIG_EXAMPLE_PIN_D2; - slot_config.d3 = CONFIG_EXAMPLE_PIN_D3; - slot_config.flags |= SDMMC_SLOT_FLAG_INTERNAL_PULLUP; - - sd_card = (sdmmc_card_t *)malloc(sizeof(sdmmc_card_t)); - (*host.init)(); - sdmmc_host_init_slot(host.slot, (const sdmmc_slot_config_t *) &slot_config); - sdmmc_card_init(&host, sd_card); - *** - } - storage_init_sdmmc(&card); - - const tinyusb_msc_sdmmc_config_t config_sdmmc = { - .card = card - }; - tinyusb_msc_storage_init_sdmmc(&config_sdmmc); - -MSC Performance Optimization -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -**Single-Buffer Approach** - -The single-buffer approach improves performance by using a dedicated buffer to temporarily store incoming write data instead of processing it immediately in the callback. - -- **Configurable buffer size**: The buffer size is set via ``CONFIG_TINYUSB_MSC_BUFSIZE``, allowing users to balance performance and memory usage. - -This approach ensures that USB transactions remain fast while avoiding potential delays caused by storage operations. - -**USB MSC Drive Performance** - -.. only:: esp32s3 - - .. list-table:: - :header-rows: 1 - :widths: 20 20 20 - - * - FIFO Size - - Read Speed - - Write Speed - - * - 512 B - - 0.566 MB/s - - 0.236 MB/s - - * - 8192 B - - 0.925 MB/s - - 0.928 MB/s - -.. only:: esp32p4 - - .. list-table:: - :header-rows: 1 - :widths: 20 20 20 - - * - FIFO Size - - Read Speed - - Write Speed - - * - 512 B - - 1.174 MB/s - - 0.238 MB/s - - * - 8192 B - - 4.744 MB/s - - 2.157 MB/s - - * - 32768 B - - 5.998 MB/s - - 4.485 MB/s - -.. only:: esp32s2 - - .. note:: - - SD card support is not available for {IDF_TARGET_NAME} in MSC device mode. - - **SPI Flash Performance:** - - .. list-table:: - :header-rows: 1 - :widths: 20 20 - - * - FIFO Size - - Write Speed - - * - 512 B - - 5.59 KB/s - - * - 8192 B - - 21.54 KB/s - -.. only:: esp32h4 - - .. note:: - - SD card support is not available for {IDF_TARGET_NAME} in MSC device mode. - - **SPI Flash Performance:** - - .. list-table:: - :header-rows: 1 - :widths: 20 20 - - * - FIFO Size - - Write Speed - - * - 512 B - - 4.48 KB/s - - * - 8192 B - - 22.33 KB/s - -Performance Limitations: - -- **Internal SPI Flash performance** is constrained by architectural limitations where program execution and storage access share the same flash chip. This results in program execution being **suspended during flash writes**, significantly impacting performance. -- **Internal SPI Flash usage is intended primarily for demonstration purposes.** For practical use cases requiring higher performance, it is recommended to use **external storage such as an SD card or an external SPI flash chip, where supported.** - -.. only:: esp32s3 or esp32p4 - - SD cards are not affected by this constraint, explaining their higher performance gains. - -Application Examples --------------------- - -The examples can be found in the directory :example:`peripherals/usb/device`. - -- :example:`peripherals/usb/device/tusb_console` demonstrates how to set up {IDF_TARGET_NAME} to get log output via a Serial Device connection using the TinyUSB component, applicable for any Espressif boards that support USB-OTG. -- :example:`peripherals/usb/device/tusb_serial_device` demonstrates how to set up {IDF_TARGET_NAME} to function as a USB Serial Device using the TinyUSB component, with the ability to be configured as a double serial device. -- :example:`peripherals/usb/device/tusb_midi` demonstrates how to set up {IDF_TARGET_NAME} to function as a USB MIDI Device, outputting a MIDI note sequence via the native USB port using the TinyUSB component. -- :example:`peripherals/usb/device/tusb_hid` demonstrates how to implement a USB keyboard and mouse using the TinyUSB component, which sends 'key a/A pressed & released' events and moves the mouse in a square trajectory upon connection to a USB host. -- :example:`peripherals/usb/device/tusb_msc` demonstrates how to use the USB capabilities to create a Mass Storage Device that can be recognized by USB-hosts, allowing access to its internal data storage, with support for SPI Flash and SD MMC Card storage media. -- :example:`peripherals/usb/device/tusb_composite_msc_serialdevice` demonstrates how to set up {IDF_TARGET_NAME} to function simultaneously as both a USB Serial Device and an MSC device (SPI-Flash as the storage media) using the TinyUSB component. - -.. only:: not esp32p4 and not esp32h4 - - - :example:`peripherals/usb/device/tusb_ncm` demonstrates how to transmit Wi-Fi data to a Linux or Windows host via USB using the Network Control Model (NCM), a sub-class of Communication Device Class (CDC) USB Device for Ethernet-over-USB applications, with the help of a TinyUSB component. +USB Device documentation has moved to `ESP-USB `_. diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst index 480bd95463..bcd6e6d4e5 100644 --- a/docs/en/api-reference/peripherals/usb_host.rst +++ b/docs/en/api-reference/peripherals/usb_host.rst @@ -3,734 +3,4 @@ USB Host :link_to_translation:`zh_CN:[中文]` -{IDF_TARGET_OTG_NUM_HOST_CHAN: default="8", esp32p4="16"} - -The document provides information regarding the USB Host Library. This document is split into the following sections: - -.. contents:: Sections - :depth: 2 - -.. ---------------------------------------------------- Overview ------------------------------------------------------- - -Overview --------- - -The USB Host Library (hereinafter referred to as the Host Library) is the lowest layer of the USB Host stack that exposes a public facing API. In most cases, applications that require USB Host functionality do not need to interface with the Host Library directly. Instead, most applications use the API provided by a host class driver that is implemented on top of the Host Library. - -However, you may want to use the Host Library directly for some of (but not limited to) the following reasons: - -- Implementation of a custom host class driver -- Usage of lower level USB Host API - -Features & Limitations -^^^^^^^^^^^^^^^^^^^^^^ - -The Host Library has the following features: - -.. list:: - - :esp32s2 or esp32s3 or esp32h4: - Supports Full Speed (FS) and Low Speed (LS) Devices. - :esp32p4: - Supports High Speed (HS), Full Speed (FS) and Low Speed (LS) Devices. - - Supports all four transfer types: Control, Bulk, Interrupt, and Isochronous. - :esp32p4: - Supports High-Bandwidth Isochronous endpoints. - :esp32p4: - {IDF_TARGET_NAME} includes two USB 2.0 OTG peripherals: one High-Speed and one Full-Speed. Both support USB Host functionality. However, due to a current software limitation, only one can operate as a USB Host at a time. Support for dual USB Host operation is planned for a future update. - - Allows multiple class drivers to run simultaneously, i.e., multiple clients of the Host Library. - - A single device can be used by multiple clients simultaneously, e.g., composite devices. - - The Host Library itself and the underlying Host Stack does not internally instantiate any OS tasks. The number of tasks is entirely controlled by how the Host Library interface is used. However, a general rule of thumb regarding the number of tasks is ``(the number of host class drivers running + 1)``. - - Allows single Hub support (If option `CONFIG_USB_HOST_HUBS_SUPPORTED` is enabled). - - Allows multiple Hubs support (If option `CONFIG_USB_HOST_HUB_MULTI_LEVEL` is enabled). - - Supports global suspend and resume, implemented by suspending or resuming the entire bus. - - Supports automatic global resume by submitting a transfer. - -Currently, the Host Library and the underlying Host Stack has the following limitations: - -.. list:: - - - Only supports Asynchronous transfers. - - Only supports using one configuration. Changing to other configurations after enumeration is not supported yet. - - Transfer timeouts are not supported yet. - - Selective (per-device/per-port) suspend/resume is not supported yet. - - Remote Wakeup initiated by a USB device is not supported yet. - - The External Hub Driver: Remote Wakeup feature is not supported (External Hubs are active, even if there are no devices inserted). - - The External Hub Driver: Doesn't handle error cases (overcurrent handling, errors during initialization etc. are not implemented yet). - - The External Hub Driver: No Interface selection. The Driver uses the first available Interface with Hub Class code (09h). - - The External Port Driver: No downstream port debounce mechanism (not implemented yet). - :esp32p4: - The External Hub Driver: No Transaction Translator layer (No FS/LS Devices support when a Hub is attached to HS Host). - - -.. -------------------------------------------------- Architecture ----------------------------------------------------- - -Architecture ------------- - -.. figure:: ../../../_static/usb_host_lib_entities.png - :align: center - :alt: Diagram of the Key Entities of USB Host Functionality - :figclass: align-center - - Diagram of the key entities involved in USB Host functionality - -The diagram above shows the key entities that are involved when implementing USB Host functionality. These entities are: - -- The **Host Library** -- **Clients** of the Host Library -- **Devices** -- Host Library **Daemon Task** - -Host Library -^^^^^^^^^^^^ - -The Host Library is the lowest public-facing API layer of the ESP-IDF USB Host Stack. Any other ESP-IDF component (such as a class driver or a user component) that needs to communicate with a connected USB device can only do so using the Host Library API either directly or indirectly. - -The Host Library's API is split into two sub-sets, namely the **Library API** and **Client API**. - -- The Client API handles the communication between a client of the Host Library and one or more USB devices. The Client API should only be called by registered clients of the Host Library. -- The Library API handles all of the Host Library processing that is not specific to a single client, such as device enumeration. Usually, the library API is called by a Host Library Daemon Task. - -Clients -^^^^^^^ - -A client of the Host Library is a software component, such as a host class driver or user component, which utilizes the Host Library to establish communication with a USB device. Generally, each client has a one-to-one relation with a task. This implies that all Client API calls pertaining to a specific client must originate from the context of the same task. - -By organizing the software components that use the Host Library's into clients, the Host Library can delegate the handling of all events specific to that client to the client's task. In other words, each client task is responsible for all the required processing and event handling associated with the USB communication that the client initiates. - -Daemon Task -^^^^^^^^^^^ - -Although the Host Library delegates the handling of client events to the clients themselves, there are still Library events – events that are not specific to any particular client – that need to be handled. Library event handling can include things such as: - -- Handling USB device connection, enumeration, and disconnection -- Rerouting control transfers to/from clients -- Forwarding events to clients - -Therefore, in addition to the client tasks, the Host Library also requires a task, which is usually the Host Library Daemon Task, to handle all of the library events. - -Devices -^^^^^^^ - -The Host Library shields clients from the details of device handling, encompassing details such as connection, memory allocation, and enumeration. The clients are provided only with a list of already connected and enumerated devices to choose from. By default during enumeration, each device is automatically configured to use the first configuration found, namely, the first configuration descriptor returned on a Get Configuration Descriptor request. For most standard devices, the first configuration will have a ``bConfigurationValue`` of ``1``. If option `CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` is enabled, a different ``bConfigurationValue`` can be selected, see `Multiple Configuration Support`_ for more details. - -It is possible for two or more clients to simultaneously communicate with the same device as long as they are not communicating to the same interface. However, multiple clients can simultaneously communicate with the same device's default endpoint (i.e., EP0), which will result in their control transfers being serialized. - -For a client to communicate with a device, the client must: - -#. Open the device using the device's address. This lets the Host Library know that the client is using that device. -#. Claim the interface(s) that will be used for communication. This prevents other clients from claiming the same interface(s). -#. Send transfers to the endpoints of claimed interfaces. The client's task is responsible for handling its own processing and events related to USB device communication. - - -.. ------------------------------------------------------ Usage -------------------------------------------------------- - -Usage ------ - -The Host Library and the underlying Host Stack will not create any tasks. All tasks, namely the client tasks and the Daemon Task, need to be created by the class drivers or the user. Instead, the Host Library provides two event handler functions that handle all of the required Host Library processing, thus these functions should be called repeatedly from the client tasks and the Daemon Task. Therefore, the implementation of client tasks and the Daemon Task will be largely centered around the invocation of these event handler functions. - -Host Library & Daemon Task -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Basic Usage -""""""""""" - -The Host Library API provides :cpp:func:`usb_host_lib_handle_events` to handle library events. This function should be called repeatedly, typically from the Daemon Task. Some notable features regarding :cpp:func:`usb_host_lib_handle_events` are: - -- The function can block until a library event needs handling. -- Event flags are returned on each invocation. These event flags are useful for knowing when the Host Library can be uninstalled. - -A bare-bones Daemon Task would resemble something like the following code snippet: - -.. code-block:: c - - #include "usb/usb_host.h" - - void daemon_task(void *arg) - { - ... - bool exit = false; - while (!exit) { - uint32_t event_flags; - usb_host_lib_handle_events(portMAX_DELAY, &event_flags); - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) { - ... - } - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) { - ... - } - ... - } - ... - } - -.. note:: - - See the :example:`peripherals/usb/host/usb_host_lib` example for full implementation of the Daemon Task. - -Lifecycle -""""""""" - -.. figure:: ../../../_static/usb_host_lib_lifecycle.png - :align: center - :alt: Graph of Typical USB Host Library Lifecycle - :figclass: align-center - - Graph of Typical USB Host Library Lifecycle - -The graph above illustrates the typical lifecycle of the Host Library with multiple clients and devices. Specifically, the example involves: - -- Two registered clients (Client 1 and Client 2). -- Two connected devices (Device 1 and Device 2), where Client 1 communicates with Device 1 and Client 2 communicates with Device 2. - -With reference to the graph above, the typical lifecycle involves the following key stages. - -1. The Host Library is installed by calling :cpp:func:`usb_host_install`. - - Installation must be done before any other Host Library API is called. - - Where :cpp:func:`usb_host_install` is called (e.g., from the Daemon Task or another task) depends on the synchronization logic between the Daemon Task, client tasks, and the rest of the system. -2. Once the Host Library is installed, the clients can be registered by calling :cpp:func:`usb_host_client_register`. - - This is typically called from the client task, where the client task waits for a signal from the Daemon Task. - - This can be called elsewhere if necessary as long it is called after :cpp:func:`usb_host_install`. -3. Device 1 connects and is then enumerated. - - Each registered client (in this case Client 1 and Client 2) is notified of the new device by way of the :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` event. - - Client 1 opens Device 1 and begins communication with it. -4. Similarly Device 2 connects and is enumerated. - - Client 1 and 2 are notified of a new device via a :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` event. - - Client 2 opens Device 2 and begins communication with it. -5. Device 1 suddenly disconnects. - - Client 1 is notified by way of :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_GONE` and begins its cleanup. - - Client 2 is not notified as it has not opened Device 1. -6. Client 1 completes its cleanup and deregisters by calling :cpp:func:`usb_host_client_deregister`. - - This is typically called from the client task before the task exits. - - This can be called elsewhere if necessary as long as Client 1 has already completed its cleanup. -7. Client 2 completes its communication with Device 2. Client 2 then closes Device 2 and deregisters itself. - - The Daemon Task is notified of the deregistration of all clients by way the :c:macro:`USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS` event flag as Client 2 is the last client to deregister. - - Device 2 is still allocated (i.e., not freed), as it is still connected albeit not currently opened by any client. -8. The Daemon Task decides to clean up as there are no more clients. - - The Daemon Task must free Device 2 first by calling :cpp:func:`usb_host_device_free_all`. - - If :cpp:func:`usb_host_device_free_all` was able to free all devices, the function will return `ESP_OK` indicating that all devices have been freed. - - If :cpp:func:`usb_host_device_free_all` was unable to free all devices for reasons like the device is still opened by a client, the function will return `ESP_ERR_NOT_FINISHED`. - - The Daemon Task must wait for :cpp:func:`usb_host_lib_handle_events` to return the :c:macro:`USB_HOST_LIB_EVENT_FLAGS_ALL_FREE` event flag in order to know when all devices have been freed. -9. Once the Daemon Task has verified that all clients have deregistered and all devices have been freed, it can now uninstall the Host Library by calling :cpp:func:`usb_host_uninstall`. - -Clients & Class Driver -^^^^^^^^^^^^^^^^^^^^^^ - -Basic Usage -""""""""""" - -The Host Library API provides :cpp:func:`usb_host_client_handle_events` to handle a particular client's events. This function should be called repeatedly, typically from the client's task. Some notable features regarding :cpp:func:`usb_host_client_handle_events` are: - -- The function can block until a client event needs handling. -- The function's primary purpose is to call the various event handling callbacks when a client event occurs. - -The following callbacks are called from within :cpp:func:`usb_host_client_handle_events` thus allowing the client task to be notified of events. - -- The client event callback of type :cpp:type:`usb_host_client_event_cb_t` delivers client event messages to the client. Client event messages indicate events such as the addition or removal of a device. -- The USB transfer completion callback of type :cpp:type:`usb_transfer_cb_t` indicates that a particular USB transfer previously submitted by the client has been completed. - -.. note:: - - Given that the callbacks are called from within :cpp:func:`usb_host_client_handle_events`, users should avoid blocking from within the callbacks as this will result in :cpp:func:`usb_host_client_handle_events` being blocked as well, thus preventing other pending client events from being handled. - -The following code snippet demonstrates a bare-bones host class driver and its client task. The code snippet contains: - -- A simple client task function ``client_task`` that calls :cpp:func:`usb_host_client_handle_events` in a loop. -- Implementations of a client event callback and transfer completion callbacks. -- Implementation of a simple state machine for the class driver. The class driver simply opens a device, sends an OUT transfer to EP1, then closes the device. - -.. code-block:: c - - #include - #include "usb/usb_host.h" - - #define CLASS_DRIVER_ACTION_OPEN_DEV 0x01 - #define CLASS_DRIVER_ACTION_TRANSFER 0x02 - #define CLASS_DRIVER_ACTION_CLOSE_DEV 0x03 - - struct class_driver_control { - uint32_t actions; - uint8_t dev_addr; - usb_host_client_handle_t client_hdl; - usb_device_handle_t dev_hdl; - }; - - static void client_event_cb(const usb_host_client_event_msg_t *event_msg, void *arg) - { - // This function is called from within usb_host_client_handle_events(). Do not block and try to keep it short - struct class_driver_control *class_driver_obj = (struct class_driver_control *)arg; - switch (event_msg->event) { - case USB_HOST_CLIENT_EVENT_NEW_DEV: - class_driver_obj->actions |= CLASS_DRIVER_ACTION_OPEN_DEV; - class_driver_obj->dev_addr = event_msg->new_dev.address; //Store the address of the new device - break; - case USB_HOST_CLIENT_EVENT_DEV_GONE: - class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; - break; - default: - break; - } - } - - static void transfer_cb(usb_transfer_t *transfer) - { - // This function is called from within usb_host_client_handle_events(). Do not block and try to keep it short - struct class_driver_control *class_driver_obj = (struct class_driver_control *)transfer->context; - printf("Transfer status %d, actual number of bytes transferred %d\n", transfer->status, transfer->actual_num_bytes); - class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; - } - - void client_task(void *arg) - { - ... // Wait until Host Library is installed - // Initialize class driver objects - struct class_driver_control class_driver_obj = {0}; - // Register the client - usb_host_client_config_t client_config = { - .is_synchronous = false, - .max_num_event_msg = 5, - .async = { - .client_event_callback = client_event_cb, - .callback_arg = &class_driver_obj, - } - }; - usb_host_client_register(&client_config, &class_driver_obj.client_hdl); - //Allocate a USB transfer - usb_transfer_t *transfer; - usb_host_transfer_alloc(1024, 0, &transfer); - - //Event handling loop - bool exit = false; - while (!exit) { - // Call the client event handler function - usb_host_client_handle_events(class_driver_obj.client_hdl, portMAX_DELAY); - // Execute pending class driver actions - if (class_driver_obj.actions & CLASS_DRIVER_ACTION_OPEN_DEV) { - // Open the device and claim interface 1 - usb_host_device_open(class_driver_obj.client_hdl, class_driver_obj.dev_addr, &class_driver_obj.dev_hdl); - usb_host_interface_claim(class_driver_obj.client_hdl, class_driver_obj.dev_hdl, 1, 0); - } - if (class_driver_obj.actions & CLASS_DRIVER_ACTION_TRANSFER) { - // Send an OUT transfer to EP1 - memset(transfer->data_buffer, 0xAA, 1024); - transfer->num_bytes = 1024; - transfer->device_handle = class_driver_obj.dev_hdl; - transfer->bEndpointAddress = 0x01; - transfer->callback = transfer_cb; - transfer->context = (void *)&class_driver_obj; - usb_host_transfer_submit(transfer); - } - if (class_driver_obj.actions & CLASS_DRIVER_ACTION_CLOSE_DEV) { - // Release the interface and close the device - usb_host_interface_release(class_driver_obj.client_hdl, class_driver_obj.dev_hdl, 1); - usb_host_device_close(class_driver_obj.client_hdl, class_driver_obj.dev_hdl); - exit = true; - } - ... // Handle any other actions required by the class driver - } - - // Cleanup class driver - usb_host_transfer_free(transfer); - usb_host_client_deregister(class_driver_obj.client_hdl); - ... // Delete the client task. Signal the Daemon Task if necessary. - } - -.. note:: - - An actual host class driver is likely to support many more features, thus will have a much more complex state machine. A host class driver is also likely to need to: - - - Be able to open multiple devices - - Parse an opened device's descriptors to identify if the device is of the target class - - Communicate with multiple endpoints of an interface in a particular order - - Claim multiple interfaces of a device - - Handle various errors - -Lifecycle -""""""""" - -The typical life cycle of a client task and class driver will go through the following stages: - -#. Wait for some signal regarding the Host Library being installed. -#. Register the client via :cpp:func:`usb_host_client_register` and allocate any other class driver resources, such as allocating transfers using :cpp:func:`usb_host_transfer_alloc`. -#. For each new device that the class driver needs to communicate with: - - a. Check if the device is already connected via :cpp:func:`usb_host_device_addr_list_fill`. - b. If the device is not already connected, wait for a :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` event from the client event callback. - c. Open the device via :cpp:func:`usb_host_device_open`. - d. Parse the device and configuration descriptors via :cpp:func:`usb_host_get_device_descriptor` and :cpp:func:`usb_host_get_active_config_descriptor` respectively. - e. Claim the necessary interfaces of the device via :cpp:func:`usb_host_interface_claim`. - -#. Submit transfers to the device via :cpp:func:`usb_host_transfer_submit` or :cpp:func:`usb_host_transfer_submit_control`. -#. Once an opened device is no longer needed by the class driver, or has disconnected, as indicated by a :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_GONE` event: - - a. Stop any previously submitted transfers to the device's endpoints by calling :cpp:func:`usb_host_endpoint_halt` and :cpp:func:`usb_host_endpoint_flush` on those endpoints. - b. Release all previously claimed interfaces via :cpp:func:`usb_host_interface_release`. - c. Close the device via :cpp:func:`usb_host_device_close`. - -#. Deregister the client via :cpp:func:`usb_host_client_deregister` and free any other class driver resources. -#. Delete the client task. Signal the Daemon Task if necessary. - - -.. ---------------------------------------------------- Power Management ----------------------------------------------- - -Power Management ----------------- - -Global Suspend/Resume -^^^^^^^^^^^^^^^^^^^^^ - -USB Host library supports global Suspend/Resume, which suspends and resumes the entire USB bus. The global Suspend/Resume is implemented through the root port(s). When suspended, the USB Host stops sending SOFs, which effectively puts all the devices connected to the USB bus to a suspended state. - -Note that the global Suspend/Resume does **not** suspend/resume the USB-OTG peripheral on the USB Host side, and therefore does **not** reduce power consumption on the host controller itself. - -Events -^^^^^^ - -Client events -""""""""""""" - -When a device is suspended or resumed, all clients that have opened the affected device are notified via the following events. Each event includes the handle of the suspended or resumed device: - -- :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_SUSPENDED` — The device has entered a suspended state. -- :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_RESUMED` — The device has resumed operation. - - -USB Host library event -"""""""""""""""""""""" - -The following event is associated with the automatic suspend timer. When a timer expires, its callback unblocks the USB Host library handler and delivers the event: - -- :cpp:enumerator:`USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND` — Indicates that the automatic suspend timer has expired. - -Auto Suspend Timer -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Users can configure an automatic suspend timer using :cpp:func:`usb_host_lib_set_auto_suspend`. The auto suspend timer is reset every time the USB Host library client processing function handles an event from any client, or when USB Host library itself is processing any event. - -The auto suspend timer actively monitors USB bus activity and USB Host library activity. Specifically: - -- If USB traffic is detected (i.e., any transfer or client-handled event occurs), the timer is automatically reset. -- If USB Host library activity is detected (i.e., new device connection occurs), the timer is automatically reset. -- If the USB bus and USB Host library remain idle (no traffic, client or library events), the timer continues counting down. -- Once the timer reaches the specified timeout (in milliseconds), the suspend event is triggered. - -This mechanism ensures that the USB Host enters suspend mode only when the bus is truly idle, preventing unintended suspension during active communication. - -Important considerations for the auto suspend timer: - -- The timer can be configured and will start counting down even if no device is connected. -- The timer stops when all devices are disconnected. -- The timer automatically resets upon any device connection or disconnection. -- When the timer expires, the USB Host library event is delivered only if: - - - A device is currently connected to the root port, and - - The root port is not already in a suspended state - -The auto suspend timer can be configured in the following modes: - -- **One-shot** (:cpp:enumerator:`USB_HOST_LIB_AUTO_SUSPEND_ONE_SHOT`) — The timer expires once and then stops. -- **Periodic** (:cpp:enumerator:`USB_HOST_LIB_AUTO_SUSPEND_PERIODIC`) — The timer automatically restarts after each expiration, repeating indefinitely. - -Auto Resume by Transfer Submit -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to the automatic suspend timer, the USB Host library also supports automatic resume of a suspended root port when a transfer (control or non-control) is submitted. This feature allows developers to initiate a resume simply by calling a transfer API (e.g., :cpp:func:`usb_host_transfer_submit` or :cpp:func:`usb_host_transfer_submit_control`), without needing to explicitly call :cpp:func:`usb_host_lib_root_port_resume`. - -When the root port is in suspended state and a client submits a transfer to a suspended device, the library will: - -1. Automatically initiate a resume on the root port. -2. Delay the transfer until the resume signaling is complete. -3. Submit the transfer once the bus is in the active (resumed) state. - -This mechanism simplifies client implementation and ensures that resume behavior is consistent and safe, avoiding race conditions that may occur if resume is triggered manually in parallel with transfer submission. - -.. note:: - - Auto-resume via transfer submission is only applicable when the root port is in a suspended state. If the port is already active, transfer submission proceeds as usual. - -The following code snippet demonstrates how to cycle between suspended and resumed states using the auto suspend timer and the auto resume by transfer submit functionality. - -.. code-block:: c - - #include "usb/usb_host.h" - - static void client_task(void *arg) - { - while(true) { - // Submit transfer to the suspended device, which automatically resumes the device - // Device will then automatically enter suspended mode after 1 second of inactivity thanks to the auto suspend timer - usb_host_transfer_submit(xfer_out); - - // Switch context for 10s. The device will be automatically suspended after ~1s of inactivity - vTaskDelay(pdMS_TO_TICKS(10000)); - } - } - - void usb_host_lib_task(void *arg) - { - ... - - // Set the auto suspend timer to periodic mode and period of 1s, - // to automatically suspend the device after 1 second of inactivity and to restart automatically after expiration - usb_host_lib_set_auto_suspend(USB_HOST_LIB_AUTO_SUSPEND_PERIODIC, 1000); - - while (1) { - uint32_t event_flags; - usb_host_lib_handle_events(portMAX_DELAY, &event_flags); - - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND) { - // Auto suspend timer expired, suspend the root port - usb_host_lib_root_port_suspend(); - } - ... - } - ... - } - -.. note:: - - For more details regarding suspend and resume, please refer to `USB 2.0 Specification `_ > Chapter 11.9 *Suspend and Resume*. - -.. ---------------------------------------------------- Examples ------------------------------------------------------- - -Examples --------- - -Host Library Examples -^^^^^^^^^^^^^^^^^^^^^ - -:example:`peripherals/usb/host/usb_host_lib` demonstrates how to use the USB Host Library API to install and register a client, wait for a device connection, print the device's information, handle disconnection, and repeat these steps until a user quits the application. - -Class Driver Examples -^^^^^^^^^^^^^^^^^^^^^ - -The USB Host Stack provides a number of examples that implement host class drivers using the Host Library's API. - -CDC-ACM -""""""" - -* A host class driver for the Communication Device Class (Abstract Control Model) is distributed as a managed component via the `ESP Component Registry `__. -* :example:`peripherals/usb/host/cdc` demonstrates how to use the CDC-ACM Host Driver to enable communication between {IDF_TARGET_NAME} and a USB CDC-ACM device, including vendor-specific devices such as CP210x, FTDI FT23x or CH34x. -* The CDC-ACM driver is also used in `esp_modem examples `__, where it is used for communication with cellular modems. - -MSC -""" - -* A host class driver for the Mass Storage Class (Bulk-Only Transport) is deployed to `ESP Component Registry `__. -* :example:`peripherals/usb/host/msc` demonstrates how to use USB Mass Storage Class to access, read, write, and perform operations on a USB flash drive, including handling USB reconnections and deinitializing the USB Host Stack. - -HID -""" - -* A host class driver for the HID (Human interface device) is distributed as a managed component via the `ESP Component Registry `__. -* :example:`peripherals/usb/host/hid` demonstrates how to implement a basic USB Host HID Class Driver on {IDF_TARGET_NAME}, enabling communication with USB HID devices like keyboards and mice, and continuously scans for their connection, fetching HID reports once connected. - -UVC -""" - -* A host class driver for the USB Video Device Class is distributed as a managed component via the `ESP Component Registry `__. -* :example:`peripherals/usb/host/uvc` demonstrates how to capture video frames from a USB camera using the UVC driver. - -.. ---------------------------------------------- USB Host Menuconfig -------------------------------------------------- - -.. only:: esp32s3 - - External PHY Configuration - -------------------------- - - The {IDF_TARGET_NAME} contains two USB controllers—the USB-OTG and USB-Serial-JTAG. However, both controllers share a **single PHY**, which means only one can operate at a time. To use USB Host functionality while the USB-Serial-JTAG is active (e.g., for debugging or flashing), an **external PHY** is required, since the PHY is used by USB-Serial-JTAG. - - .. note:: - An external PHY is not the only way to enable debugging alongside USB Host or Device functionality. It is also possible to switch the debugging interface from USB-Serial-JTAG to plain JTAG by burning the appropriate eFuses. For details, refer to the `JTAG Debugging `_ in the ESP-IDF Programming Guide for your target. - - {IDF_TARGET_NAME} supports connecting external PHY ICs. This allows independent operation of both USB-OTG and USB-Serial-JTAG controllers. Various external PHY ICs may require different hardware configurations. Please refer to the respective IC datasheets for details. A general connection diagram is available in the official ESP documentation: `Use an external PHY `__. - - **List of Tested External PHY ICs:** - - - **SP5301** — Directly supported by {IDF_TARGET_NAME}. See the guide above for schematic and routing details. - - **TUSB1106** — Directly supported by {IDF_TARGET_NAME}. Works with the external-PHY driver via GPIO mapping. Follow the reference wiring in the TUSB1106 datasheet (power-supply options and recommended series resistors on D+/D–). - - **STUSB03E** — Requires signal routing using an analog switch. See example below. - - .. figure:: ../../../_static/usb_host/ext_phy_schematic_stusb03e.png - :align: center - :alt: External PHY with Analog Switch Schematic (Host mode) - - Example connection using STUSB03E and analog switch (Host mode) - - .. note:: - - This schematic is a minimal example intended only to demonstrate the external PHY connection. It omits other essential components and signals (e.g., VCC, GND, RESET) required for a complete, functional {IDF_TARGET_NAME} design. - - The schematic includes both a +5 V rail (used to power USB devices) and a VCC rail (typically 3.3 V). VCC should match the chip supply voltage. Ensure that +5 V for the USB bus is appropriately sourced and protected (e.g., with a power switch and current limiting). Always comply with USB host power requirements, particularly when supporting USB bus-powered devices. - - Hardware configuration is handled via GPIO mapping to the PHY's pins. Any unused pins (e.g., :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num`) **must be set to -1**. - - .. note:: - - The :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num` pin is **currently not supported** and does not need to be connected. - - **Example Code:** - - .. code-block:: c - - // GPIO configuration for external PHY - const usb_phy_ext_io_conf_t ext_io_conf = { - .vp_io_num = 8, - .vm_io_num = 5, - .rcv_io_num = 11, - .oen_io_num = 17, - .vpo_io_num = 4, - .vmo_io_num = 46, - .fs_edge_sel_io_num = 38, - .suspend_n_io_num = -1, - }; - - // Configuration and initialization of external PHY for OTG controller (Host mode) - const usb_phy_config_t phy_config = { - .controller = USB_PHY_CTRL_OTG, - .target = USB_PHY_TARGET_EXT, - .otg_mode = USB_OTG_MODE_HOST, - .otg_speed = USB_PHY_SPEED_FULL, - .ext_io_conf = &ext_io_conf - }; - - usb_phy_handle_t phy_hdl; - ESP_ERROR_CHECK(usb_new_phy(&phy_config, &phy_hdl)); - - // Configure USB Host to use the externally initialized PHY - usb_host_config_t host_config = { - .skip_phy_setup = true, - // Add other host configuration fields as needed - }; - ESP_ERROR_CHECK(usb_host_install(&host_config)); - - This setup ensures that the USB Host stack uses the **external PHY** and bypasses PHY setup. - -Host Stack Configuration ------------------------- - -Non-Compliant Device Support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To support USB devices that are non-compliant in various scenarios or exhibit specific behaviors, it is possible to configure the USB Host stack. - -As a USB device may be hot-plugged, it is essential to have configurable delays between power switching and device attachment, and when the device's internal power has stabilized. - -Enumeration Configuration -""""""""""""""""""""""""" - -During the process of enumerating connected USB devices, several delay values ensure the proper functioning of the device. - -.. figure:: ../../../_static/usb_host/poweron-timings.png - :align: center - :alt: USB Root Hub Power-on and Connection Events Timing - - USB Root Hub Power-on and Connection Events Timing - -The figure above shows all the delay values associated with both turning on port power with a device connected and hot-plugging a device. - -* After a port is reset or resumed, the USB system software is expected to provide a "recovery" interval of 10 ms before the device attached to the port is expected to respond to data transfers. -* After the reset/resume recovery interval, if a device receives a ``SetAddress()`` request, the device must be able to complete processing of the request and be able to successfully complete the Status stage of the request within 50 ms. -* After successful completion of the Status stage, the device is allowed a ``SetAddress()`` recovery interval of 2 ms. - -.. note:: - - For more details regarding connection event timings, please refer to `USB 2.0 Specification `_ > Chapter 7.1.7.3 *Connect and Disconnect Signaling*. - -Configurable parameters of the USB host stack can be configured with multiple options via Menuconfig. - -* For debounce delay, refer to `CONFIG_USB_HOST_DEBOUNCE_DELAY_MS`. -* For reset hold interval, refer to `CONFIG_USB_HOST_RESET_HOLD_MS`. -* For reset recovery interval, refer to `CONFIG_USB_HOST_RESET_RECOVERY_MS`. -* For ``SetAddress()`` recovery interval, refer to `CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS`. - -Downstream Port Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -When external Hubs feature is supported, there are several parameters which could be configured for the external Hubs port. - -Each external Hub has a Hub Descriptor which describes the device characteristics. - -.. note:: - - For detailed information about Hub Descriptor, please refer to `USB 2.0 Specification `_ > Chapter 11.23.2.1 *Hub Descriptor*. - -Configurable parameters of the downstream port can be configured with multiple options via Menuconfig. - -* For custom value to stabilize the power after powering on the port (PwrOn2PwrGood value), refer to `CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_MS`. -* For reset recovery interval, refer to `CONFIG_USB_HOST_EXT_PORT_RESET_RECOVERY_DELAY_MS`. - -.. note:: - - The specification claims, that for a hub with no power switches, PwrOn2PwrGood must be set to zero. Meanwhile, for some devices, this value could be increased to give extra time for device to power-up. To enable this feature, refer to `CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_ENABLE`. - -Host Channels -""""""""""""" - -When external Hubs support feature is enabled (`CONFIG_USB_HOST_HUBS_SUPPORTED`), the amount of Host channels plays important role, as each downstream device requires vacant channel. - -To handle each attached device, different amount of channels are required. This amount does depend on the device class (EPs number). - -Supported amount of channels for {IDF_TARGET_NAME} is {IDF_TARGET_OTG_NUM_HOST_CHAN}. - -.. note:: - - - One free channel is required to enumerate the device. - - From 1 to N (when N - number of EPs) free channels are required to claim the interface. - - When there are no more free Host channels available, the device could not be enumerated and its interface cannot be claimed. - - -Multiple Configuration Support -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -To support USB devices that have more than one configuration, it is possible to specify the desired configuration number during a device's enumeration process. - -Enumeration Filter -"""""""""""""""""" - -The enumeration filter is a callback function of type :cpp:type:`usb_host_enum_filter_cb_t` called at the beginning of the enumeration process once a device descriptor is read from a newly attached USB device. Consequently, the user is provided with the obtained device descriptor. Through this callback, the user can: - -* Select the configuration of the USB device. -* Filter which USB devices should be enumerated. - -To use the enumeration filter, users should enable the `CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` option using menuconfig. Users can specify the callback by setting :cpp:member:`usb_host_config_t::enum_filter_cb` which is then passed to the Host Library when calling :cpp:func:`usb_host_install`. - -.. -------------------------------------------------- API Reference ---------------------------------------------------- - -API Reference -------------- - -The API of the USB Host Library is separated into the following header files. However, it is sufficient for applications to only ``#include "usb/usb_host.h"`` and all USB Host Library headers will also be included. - -- `usb/include/usb/usb_host.h` contains the functions and types of the USB Host Library. -- `usb/include/usb/usb_helpers.h` contains various helper functions that are related to the USB protocol such as descriptor parsing. -- `usb/include/usb/usb_types_stack.h` contains types that are used across multiple layers of the USB Host stack. -- `usb/include/usb/usb_types_ch9.h` contains types and macros related to Chapter 9 of the USB2.0 specification, i.e., descriptors and standard requests. -- `usb/include/usb/usb_types_ch11.h` contains types and macros related to Chapter 11 of the USB2.0 specification, i.e., hub specifications. - -Header File -^^^^^^^^^^^ - -- ``usb_host.h`` can be included with: - -.. code:: c - - #include "usb/usb_host.h" - -- This header file is a part of the API provided by the ``usb`` component. The ``usb`` component is distributed via the `ESP Component Registry `__. Thus, to use it, please add the Host Stack component as dependency using the following command: - -.. code:: bash - - idf.py add-dependency usb - -.. ------------------------------------------------ Maintainers Notes -------------------------------------------------- - -Maintainers Notes ------------------ - -.. note:: - - For more details regarding the internal implementation details of the USB Host stack, please refer to :doc:`/api-reference/peripherals/usb_host/usb_host_notes_index`. - -.. toctree:: - :hidden: - :maxdepth: 0 - - usb_host/usb_host_notes_index +USB Host documentation has moved to `ESP-USB `_. diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst deleted file mode 100644 index 8747d1f15e..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_arch.rst +++ /dev/null @@ -1,60 +0,0 @@ -USB Host Maintainers Notes (Architecture) -========================================= - -:link_to_translation:`zh_CN:[中文]` - -The Host Stack is roughly split into multiple layers of abstraction, with each layer representing different USB concepts and a different level of USB Host operation. For example, a higher layer may present an abstraction of devices and application data transfers, whereas a lower layer may present an abstraction of endpoints and USB transfers. - -Layer Descriptions ------------------- - -The layers of the Host Stack are described in the following table. The layers are ordered from lowest layer (i.e, furthest away from the user) to highest layer (i.e., closest to the user). - -.. list-table:: Host Stack Layers - :widths: 20 10 70 - :header-rows: 1 - - * - Layer - - Files - - Description - * - Host Controller (DWC_OTG) - - N/A - - This layer represents the USB Controller Hardware of the {IDF_TARGET_NAME}. The API presented by this layer is the register interface of the controller. - * - LL - - ``usbh_ll.h`` - - The LL (Low Level) layer abstracts the basic register access of the USB controller according to ESP-IDF's :doc:`Hardware Abstraction API Guidelines <../../../api-guides/hardware-abstraction>`. In other words, this layer provides APIs to access the controller's registers and format/parse the controller's DMA descriptors. - * - HAL - - ``usbh_hal.h``, ``usbh_hal.c`` - - The HAL (Hardware Abstraction Layer) abstracts the operating steps of the USB controller into functions according to ESP-IDF's :doc:`Hardware Abstraction API Guidelines <../../../api-guides/hardware-abstraction>`. This layer also abstracts the controller's host port and host channels, and provides APIs to operate the them. - * - HCD - - ``hcd.h``, ``hcd.c`` - - The HCD (Host Controller Driver) acts as hardware agnostic API for all USB controllers (i.e., an API that can theoretically be used with any USB controller implementation). This layer also abstracts the root port (i.e., root hub) and USB pipes. - * - USBH and Hub Driver - - ``usbh.h``, ``usbh.c`` - - The USBH (USB Host Driver) layer is equivalent to the USBD layer described in chapter 10 of the USB2.0 specification. The USBH presents an abstraction of USB devices, internally manages a list of connected devices (i.e., device pool), and also arbitrates device sharing between clients (i.e., tracks which endpoints are in use and also presents a shared endpoint 0). - * - Hub Driver - - ``hub.h``, ``hub.c`` - - The Hub Driver layer acts as a special client of the USBH that is responsible for handling device attachment/detachment, and notifying the USBH of such events. For device attachment, the Hub Driver also handles the enumeration process as well. - * - USB Host Library - - ``usb_host.h``, ``usb_host.c`` - - The USB Host Library layer is the lowest public API layer of the Host Stack and presents the concept of USB Host Clients. The abstraction of clients allows for multiple class drivers to coexist simultaneously (where each class roughly maps to a single client) and also acts as a mechanism for division of labor (where each client is responsible for its own processing and event handling). - * - Host Class Drivers - - See the `ESP-USB repository `_ or the USB Host examples in ESP-IDF (via :example:`peripherals/usb/host`). - - The Host Class Drivers implement the host side of a particular device class (e.g., CDC, MSC, HID). The exposed API is specific to each class driver. - -Layer Dependencies ------------------- - -The Host Stack roughly follows a top to bottom hierarchy with inter-layer dependencies. Given layers A (highest), B, and C (lowest), the Host Stack has the following inter-layer dependency rules: - -- a particular layer can use the API of any layer directly below (Layer A using layer B is allowed). -- a particular layer can use the API of any layer indirectly below (Layer A using layer C is allowed) i.e., skipping layers. -- a particular layer must not use the API of any layer above (Layer C using layer A/B is forbidden). - -.. note:: - - Layer skipping is permitted in order to circumvent the need to repeat the same abstraction across multiple layers. For example, the abstraction of pipes are presented at the HCD layer but are used by multiple layers above. - -.. todo:: - - Add diagram of API dependencies between layers diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_design.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_design.rst deleted file mode 100644 index ae54b757b8..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_design.rst +++ /dev/null @@ -1,144 +0,0 @@ -USB Host Maintainers Notes (Design Guidelines) -============================================== - -:link_to_translation:`zh_CN:[中文]` - -Design Considerations ---------------------- - -The design of the Host Stack takes into account the following design considerations: - -**Limited Hardware Resources:** - -The embedded nature of Host Stack means limited hardware resources (such as memory and processing power) when compared to larger host systems. - -**USB 2.0 Chapter 10:** - -Chapter 10 of the USB 2.0 specification specifies certain requirements of USB Host systems, in particular the required layers of the USB Host's system software. - -**Varying Complexity of Different Use Cases:** - -The embedded nature of the Host Stack also means a wide range of use cases with differing complexities. Some USB Host applications aim to only support a single vendor specific device, whereas other applications require support for a wide range of devices of different classes. - -Requirements ------------- - -Given the design considerations above, the Host Stack was designed with the following set of requirements: - -DMA Support -^^^^^^^^^^^ - -**Requirement: The Host Stack must support DMA.** - -The Host Stack must support DMA in order to reduce CPU's workload. DMA support allows the automatic copying of USB transfer data to and from the Host Controller without CPU intervention. This is especially critical given the embedded nature of the CPU (i.e., lower CPU frequencies) and large maximum data payloads of USB transfers (e.g., 1023 bytes for isochronous transfers). - -Minimize Memory Copies -^^^^^^^^^^^^^^^^^^^^^^ - -**Requirement: The Host Stack should minimize the amount of memory copies when passing data between layers.** - -Various data and objects (e.g., USB transfers) need to be passed between multiple layers of the Host Stack. The Host Stack should minimize the amount of memory copies that occur between layers by allocating the data's or object's memory once, and simply passing a pointer to that data or object between the layers. Therefore, the Host Stack requires some standardized data types shared across multiple layers (see USB 2.0 Section 10.3.4). - -Event Driven -^^^^^^^^^^^^ - -**Requirement: The Host Stack must allow for event driven operation (i.e., the Host Stack's API must not be polling).** - -The Host Stack needs to support some CPU intensive application scenarios such as video streaming (i.e., UVC class). Therefore, the Host Stack should minimize CPU usage by supporting completely event driven operation, thus reserving the majority of CPU time for the application itself (i.e., video encoding or decoding in this case). - -The Host Stack needs to communicate events across the layers using interrupts, callbacks, and FreeRTOS synchronization primitives (e.g., queues and semaphores). - -No Task Creation -^^^^^^^^^^^^^^^^ - -**Requirement: All layers of the Host Stack below (and including) the Host Library layer must not create any tasks.** - -Task stacks are generally one of the most memory intensive parts of an ESP-IDF applications. Given the wide range of applications scenarios, the number of tasks created (and their stack sizes) can vary greatly. For example: - -- applications that require low latency or high throughput (such as isochronous transfers) may choose to create a dedicated task to handle those transfers in order to minimize latency. -- applications that do not have strict latency requirements (such as bulk transfers) may choose to handle those transfers from a shared task in order to save some memory. - -Therefore, all layers of the Host Stack below (and including) the Host Library layer **must not** create any tasks. Instead, these layers should expose handlers functions to be called from tasks created by the upper layers. Task creation will be delegated to the class driver or application layer. - -Operable at Different Layers -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Given the wide range of use case complexities, the Host Stack must be operable at different layers, allowing users to use the Host Stack at a lower layer (e.g., the HCD or HAL) or at a higher layer (e.g., a class driver). - -Being operable at different layers allows the users to decide on the appropriate trade-off between convenience, control, and optimization for their application when using the Host Stack. For example: - -- Host Stack applications that support a dedicated custom device may want to use a lower level of abstraction for better optimization, control, and simpler API. -- Host Stack applications that need to support a wide range of device classes requires the full Host Stack so that device enumeration is automatically handled. - -Coding Conventions ------------------- - -The Host Stack follows the following set of coding conventions for better code readability and maintainability: - -Symbols Use Layer Name As Prefix -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -For each layer of the Host Stack, the symbols exposed by that layer (i.e., functions, types, macros) must be prefixed with that layer's name. For example, the symbols exposed by the HCD layer will be prefixed ``hcd_...`` or ``HCD_...``. - -However, internal symbols (e.g., static functions) **should not** be prefixed with their layer's name. This makes it easier to differentiate between internal and external symbols when modifying that layer's source code. - -Critical Section Functions Prefixed With ``_`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In each layer of the Host Stack, there are various static functions that must be called inside a critical section. The names of these functions are prefixed with ``_`` (e.g., ``_func_called_from_crit()``) to make it easier for maintainers to differentiate which functions should be called from critical sections. For example: - -.. code-block:: c - - some_func(); // Called outside critical section - taskENTER_CRITICAL(&some_lock); - _some_func_crit(); // Called inside critical section. _ prefix makes it easier to differentiate - taskEXIT_CRITICAL(&some_lock); - -Grouping Structure Members by Locking Mechanism -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Some layers of the Host Stack utilize multiple locking schemes (e.g., critical sections and task mutexes) to ensure thread safety, where each locking scheme offers a different level of protection. However, member variables of the same object can be protected by different locking scheme. Therefore, to clearly demarcate the different locking schemes and their associated variables, structure members are grouped by locking scheme as nested structures. - -.. list-table:: Locking Scheme - :widths: 10 10 80 - :header-rows: 1 - - * - Locking Scheme - - Nested Structure - - Description - * - Critical Sections - - ``dynamic`` - - Shared data accessed from both a task context and ISR context are protected by a critical section. - * - Task Mutexes - - ``mux_protected`` - - Shared data accessed from only a task context are protected by a FreeRTOS Mutex - * - Single Thread - - ``single_thread`` - - Data that is only ever accessed by the same task do not require the use of any locks. - * - Constant - - ``constant`` - - Constant data is set once during the object's instantiation and never changed again. Thus, any task or ISR can freely access the constant data without the use of locks, so long as the variable is never written to. - -Grouping structure members by locking scheme makes the code more maintainable as it makes clear which locking scheme is required when accessing a particular member variable, as demonstrated in the code snippet below: - -.. code-block:: c - - typedef struct some_obj some_obj_t; - - some_obj_t obj; - - // Accessing dynamic members requires critical section - taskENTER_CRITICAL(&some_lock); - obj.dynamic.varA = 1; - taskEXIT_CRITICAL(&some_lock); - - // Accessing mutex protected members requires taking the mutex - xSemaphoreTake(&some_mux, portMAX_DELAY); - obj.mux_protected.varB = 1; - xSemaphoreGive(&some_mux); - - // Accessing single thread members does not require locking so long as this is the only task to access it - obj.single_thread.varC = 1; - - // Accessing constant members requires no locking. But only read access is allowed - int local_var = obj.constant.varD; diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst deleted file mode 100644 index 1885b7d088..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst +++ /dev/null @@ -1,224 +0,0 @@ -USB Host Maintainers Notes (DWC_OTG Controller) -=============================================== - -:link_to_translation:`zh_CN:[中文]` - -The {IDF_TARGET_NAME} uses a DesignWare USB 2.0 On-the-Go Controller (henceforth referred to as DWC_OTG in this document) as its underlying hardware controller, where the DWC_OTG operates in Host Mode with Scatter/Gather DMA enabled. - -.. note:: - - This section only summarizes the operation of the DWC_OTG in Host Mode at a high level. For full details of the DWC_OTG, please refer to the DWC_OTG Databook and Programming Guide. - -Host Mode Operating Model -------------------------- - -A simplified version of the operating model of the DWC_OTG in Host Mode is illustrated in the diagram below. The diagram contains some of the key concepts and terms regarding DWC_OTG Host Mode. - -.. figure:: ../../../../_static/usb_host/dwc-otg-operation.png - :align: center - :alt: DWC_OTG Host Mode Operating Model - :figclass: align-center - -.. note:: - - Refer to the Databook section 2.1.4 (Host Architecture) for more details. - -Host Port -^^^^^^^^^ - -The Host Port represents the single USB port provided by the DWC_OTG (in USB terms, this can be thought of as a single USB port of the root hub of the bus). The Host Port can only connect to a single device, though more devices can be connected via hub devices. - -The Host Port is responsible for: - -- detecting direct device connections/disconnections. -- detecting the speed of the directly connected device. -- issuing various bus signals (such as suspend, resume, reset). - -Host Channels -^^^^^^^^^^^^^ - -In Host Mode, the DWC_OTG uses channels to communicate with device endpoints, where one channel maps to a particular endpoint (in USB terms, channels are the hardware representation of pipes). For example, a channel will map to EP 1 OUT. Each channel has its own set of CSRs (Control and Status Registers) so that they can be configured and controlled independently. A channel's CSRs are used to: - -- specify the details of the channel's target endpoint (e.g., device address, EP number, transfer type, direction). -- start a transfer on the channel (e.g., by setting up DMA descriptors). - -When using Scatter/Gather DMA, transfers on Host Channels are completely event driven. Users simply fill out the appropriate DMA descriptors, fill in the channel's CSRs, then enable the channel. The channel will then generate an interrupt when the transfer completes. - -Data FIFOs -^^^^^^^^^^ - -In Host Mode, the DWC_OTG uses multiple FIFOs as a staging area for the data payloads of USB transfers. When using DMA, the DMA engine will copy data between the TX/RX FIFOs and {IDF_TARGET_NAME}'s internal memory: - -- For an OUT transfer, the transfer's data payload is copied from main memory to one of the TX FIFOs by DMA. The MAC Layer will then transmit that data payload in accordance to USB packet formatting. -- For an IN transfer, the MAC Layer will parse the received USB packet and store the received data payload in the RX FIFO. The data is then copied to main memory by DMA. - -The destination FIFO depends on the direction and transfer type of the channel: - -- All IN channel data goes to the RX FIFO. -- All non-periodic (i.e., Control and Bulk) OUT channel data goes to the Non-periodic TX (NPTX) FIFO. -- All periodic (i.e., Interrupt and Isochronous) OUT channel data goes to the Periodic TX (PTX) FIFO. - -.. note:: - - The separation of non-periodic and periodic OUT channels to the NPTX and PTX FIFOs is due to the periodic nature of Interrupt and Isochronous endpoints (specified by the ``bInterval`` value of the endpoint). The DWC_OTG automatically schedules these periodic transfers, thus a separate PTX FIFO allows these periodic transfers to be staged separately. - -DMA Engine -^^^^^^^^^^ - -The DMA engine is responsible for copying data between the FIFOs and main memory. In Host Mode Scatter/Gather DMA, a particular channel can carry out multiple transfers automatically without software intervention. The following diagram illustrates the DWC_OTG Host Mode Scatter/Gather DMA Memory Structures. - -.. figure:: ../../../../_static/usb_host/dwc-otg-scatter-gather.png - :align: center - :alt: DWC_OTG Host Mode Scatter/Gather DMA Memory Structures - :figclass: align-center - -- Each USB transfer is described by a Queue Transfer Descriptor (QTD). Each QTD consists of: - - - A 32-bit Buffer Status Quadlet specifying details of the transfer, and also reports the status of the transfer on completion. The Buffer Status Quadlet has bits to specify whether the QTD should generate an interrupt and/or halt the channel on completion. - - A 32-bit pointer to the data buffer containing the data payload for OUT transfers, or an empty buffer used to store the data payload for IN transfers. - -- The data payload of each QTD can be larger than the MPS (Maximum Packet Size) of its target endpoint. The DWC_OTG hardware automatically handles the split of transfer into multiple transactions. -- Multiple QTDs can be placed into a single QTD List. A channel will then execute each QTD in the list automatically, and optionally loop back around via configuration. -- Before a channel starts data transfer, it is configured with a QTD list (and QTD list length). Once the channel is enabled, USB transfers are executed automatically by the hardware. -- A channel can generate interrupts (configurable) on completion of a particular QTD, or an entire QTD list. - -.. note:: - - Refer to Programming Guide section 6.2.1 (Descriptor Memory Structures) for more details. - -Hardware Configuration ----------------------- - -The DWC_OTG IP is configurable. The notable host related configurations of the {IDF_TARGET_NAME}'s DWC_OTG are listed below: - -.. only:: esp32p4 - - .. list-table:: {IDF_TARGET_NAME}'s DWC_OTG Configuration - :widths: 70 30 - :header-rows: 1 - - * - Description - - Configuration - * - Host and Device Mode support with OTG - - ``OTG_MODE = 0`` - * - High Speed (HS), Full Speed (FS) and Low Speed (LS) support - - ``OTG_FSPHY_INTERFACE = 2``, ``OTG_HSPHY_INTERFACE = 3`` - * - Internal DMA controller with Scatter/Gather DMA - - ``OTG_ARCHITECTURE = 2``, ``OTG_EN_DESC_DMA = 1`` - * - Split transfers not supported - - ``OTG_SINGLE_POINT = 1`` - * - 16 Host Mode channels - - ``OTG_NUM_HOST_CHAN = 16`` - * - All transfer types supported, including ISOC and INTR OUT transfers - - ``OTG_EN_PERIO_HOST = 1`` - * - Dynamically sized Data FIFO of 4096 bytes (1024 lines) - - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 1024`` - * - Only 4 periodic and 4 non-periodic transactions per microframe - - ``OTG_NPERIO_TX_QUEUE_DEPTH = 4``, ``OTG_PERIO_TX_QUEUE_DEPTH = 4`` - -.. only:: esp32s2 or esp32s3 or esp32h4 - - .. list-table:: {IDF_TARGET_NAME}'s DWC_OTG Configuration - :widths: 70 30 - :header-rows: 1 - - * - Description - - Configuration - * - Host and Device Mode support with OTG - - ``OTG_MODE = 0`` - * - Full Speed (FS) and Low Speed (LS) support - - ``OTG_FSPHY_INTERFACE = 1``, ``OTG_HSPHY_INTERFACE = 0`` - * - Internal DMA controller with Scatter/Gather DMA - - ``OTG_ARCHITECTURE = 2``, ``OTG_EN_DESC_DMA = 1`` - * - 8 Host Mode channels - - ``OTG_NUM_HOST_CHAN = 8`` - * - All transfer types supported, including ISOC and INTR OUT transfers - - ``OTG_EN_PERIO_HOST = 1`` - * - Dynamically sized Data FIFO of 1024 bytes (256 lines) - - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 256`` - -Scatter/Gather DMA Transfer ---------------------------- - -The basic operating procedure for Host Channels' transfers consists of the following steps: - -#. Prepare data buffers, QTDs, and a QTD list. In particular, ensure which QTDs should halt the channel and generate an interrupt on completion. -#. Set channel and endpoint characteristics via CSRs (such as EP address, transfer type, EP MPS etc). -#. Set channel's QTD list related CSRs (such as QTD list pointer and QTD list length) and channel interrupt CSRs -#. Enable the channel. Transfers are now handled automatically by hardware using DMA. -#. The Channel generates an interrupt on a channel event (e.g., QTD completion or channel error). -#. Parse the channel interrupt to determine what event occurred. -#. Parse the QTDs to determine the result of each individual transfer. - -However, there are some minor differences in channel operation and QTD list usage depending on the transfer type. - -Bulk -^^^^ - -Bulk transfers are the simplest transfers. Each QTD represents a bulk transfer of a particular direction, where the DWC_OTG automatically splits a particular QTD into multiple MPS sized transactions. Thus it is possible to fill a QTD list with multiple bulk transfers, and have the entire list executed automatically (i.e., only interrupt on completion of the last QTD). - -Control -^^^^^^^ - -Control transfers are more complicated as they are bi-directional (i.e., each control transfer stage can have a different direction). Thus, a separate QTD is required for each stage, and each QTD must halt the channel on completion. Halting the channel after each QTD allows the channel's direction to be changed by reconfiguring the channel's CSRs. Thus a typical control transfer consists of 3 QTDs (one for each stage). - -Interrupt -^^^^^^^^^ - -In accordance with the USB 2.0 specification, interrupt transfers executes transactions at the endpoints specified service period (i.e., ``bInterval``). A particular interrupt endpoint may not execute more than one interrupt transaction within a service period. The service period is specified in number of microframes or frames, thus a particular interrupt endpoint will generally execute one transaction every Nth microframe or frame until the transfer is complete. For interrupt channels, the service period of a particular channel (i.e., ``bInterval``) is specified via the Host Frame List (see section 6.5 of Programming Guide for more details). - -.. note:: - - HS USB allows an interrupt endpoint to have three interrupt transactions in a single microframe. See USB 2.0 specification section 5.7.3 (Interrupt Transfer Packet Size Constraints) for more details. - -Thus, interrupt transfers in Host Mode Scatter/Gather DMA have the following peculiarities: - -- If a QTD payload is larger than the endpoint's MPS, the channel will automatically split the transfer into multiple MPS sized transactions (similar to bulk transfers). However, each transaction **is executed at endpoint's specified service period** (i.e., one transaction per ``bInterval``) until the transfer completes. -- For Interrupt IN transfers, if a short packet is received (i.e., transaction's data payload is < MPS), this indicates that the endpoint has no more data to send. In this case: - - - the channel generates an extra channel interrupt even if the transfer's QTD did not set the IOC (interrupt on complete) bit. - - however, the channel is not halted even if this extra channel interrupt is generated. - - software must then use this extra interrupt to manually halt the interrupt channel, thus canceling any remaining QTDs in the QTD list. - - -.. note:: - - Due to the interrupt transfer peculiarities, it may be easier for software to allocate a QTD for each transaction instead of an entire transfer. - -Isochronous -^^^^^^^^^^^ - -In accordance with the USB 2.0 specification, isochronous transfers executes transactions at the endpoints specified service period (i.e., ``bInterval``) in order to achieve a constant rate of data transfer. A particular isochronous endpoint may not execute more than one isochronous transaction within a service period. The service period is specified in number of microframes or frames, thus a particular isochronous endpoint will generally execute one transaction every Nth microframe or frame until the transfer is complete. For isochronous channels, the service period of a particular channel (i.e., ``bInterval``) is specified via the Host Frame List (see section 6.5 of programming guide for more details). - -However, unlike interrupt transactions, isochronous transactions are not retried on failure (or NAK), due to the need to maintain the constant data rate. - -.. note:: - - HS USB allows an isochronous endpoint to have three isochronous transactions in a single microframe. See USB 2.0 specification section 5.6.3 (Isochronous Transfer Packet Size Constraints) for more details. - -Thus, isochronous transfers in Host Mode Scatter/Gather DMA have the following peculiarities: - -- A QTD must be allocated for each microframe or frame. However, non-service period QTDs should be left blank (i.e., only every Nth QTD should be filled if the channel's service period is every Nth microframe or frame). -- **Each filled QTD must represent a single transaction instead of the entire transfer**. -- Because isochronous transactions are not retried on failure, the status of each completed QTD must be checked. - -Supplemental Notes ------------------- - -Some of the DWC_OTG's behaviors are not mentioned in the Databook or Programming Guide. This section describes some of those behaviors that are relevant to the Host Stack's implementation. - -Port Errors Do Not Trigger a Channel Interrupt -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If a port error occurs (such as a sudden disconnection or port over-current) while there are one or more active channels, - -- the active channels remains active (i.e., ``HCCHAR.ChEna`` remains set) and no channel interrupts are generated. -- channels could in theory be disabled by setting ``HCCHAR.ChDis``, but this does not work for Isochronous channels as the channel disabled interrupt is never generated. - -Therefore, on port errors, a controller soft reset should be used to ensure all channels are disabled. - -Port Reset Interrupts -^^^^^^^^^^^^^^^^^^^^^ - -- When the DWC_OTG issues a reset signal on its port, and during the reset signal the device disconnects, the disconnection interrupt (i.e., ``HPRT.PrtConnDet``) is not generated until the reset is deasserted. -- When resetting an already enabled port (i.e., ``HPRT.PrtEna``) such as a second reset during enumeration or a run-time reset, a Port Enable/Disable Change interrupt (i.e., ``HPRT.PrtEnChng``) is generated both on the assertion and deassertion of the reset signal. diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst deleted file mode 100644 index d51cfd3ddf..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. Translation not required: According to the USB developers, all of the ``usb_host_notes_*`` files are just internal notes for ESP-IDF developers, not for our end users. So we don't need to translate them at all. - -USB Host Enumeration Driver (Enum) -================================== - -Introduction ------------- - -The USB Host Enumeration Driver (henceforth referred to as Enum Driver) provides a software interface which abstracts away the USB device enumeration process. The Enum Driver provides a simple API to start, proceed, complete and cancel the enumeration of a particular device. Internally, the Enum Driver will handle all stages of the enumeration process such as requesting various descriptors and setting the device's configuration. - -Requirements ------------- - -USB Specification Requirements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Chapter 9.1.2 of the USB 2.0 specification outlines some actions, when a USB device is attached to a powered port. - -The design of the Enum Driver takes into consideration following actions: - -- **The hub performs the required reset processing for the port.** ``enum_config_t.enum_event_cb`` call with ``ENUM_EVENT_RESET_REQUIRED`` event used for Hub Driver notification. -- **The host assigns a unique address to the USB device.** The Enum Driver keeps the device address value and assigns a unique address to the USB device, moving the device to the Address state. -- **The host reads the device descriptor to determine what actual maximum data payload size this USB device's default pipe can use**. The Enum Driver reads the device descriptor to determine what actual maximum data payload size this USB device's default pipe can use. -- **The host reads the configuration information from the device by reading each configuration zero to n-1, where n is the number of configurations.** This requirement simplified to reading only one configuration information from the device by reading configuration with default number, which could be selected by ``enum_config_t.enum_filter_cb`` call. -- **The host assigns a configuration value to the device.** The Enum Driver assigns a configuration value to the device. - -.. note:: - - Typically, most USB devices only contain a single configuration. Thus, the Enum Driver defaults to selecting the configuration with `bConfigurationValue = 1`. - - If users would like to select a different configuration, the Enum Driver provides an enumeration filter callback feature (enabled via `CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK`). This callback is called during the enumeration process and allows users to decide what devices to enumerate, and which ``bConfigurationValue`` to use. - -.. note:: - - For more detailed information about Bus enumeration, please refer to `USB 2.0 Specification `_ > Chapter 9.1.2 **Bus Enumeration**. - -Host Stack Requirements -^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to the USB 2.0 specification requirements, the Enum Driver also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): - -- Enum Driver must not instantiate any tasks/threads -- Enum Driver must be event driven, providing event callbacks and an event processing function -- Enum Driver must use only API from underlying layer (USBH) - -Implementation & Usage ----------------------- - -Host Stack Interaction -^^^^^^^^^^^^^^^^^^^^^^ - -The Enum Driver takes place between USB Host layer and USBH layer with a possibility to select configuration with ``enum_config_t.enum_event_cb`` callback provided on Enum Driver installation. - -Events & Processing -^^^^^^^^^^^^^^^^^^^ - -The Enum Driver is completely event driven and all event handling is done via the ``enum_process()`` function. The ``enum_config_t.proc_req_cb`` callback provided on Enum Driver installation will be called when processing is required. Typically, ``enum_process()`` will be called from a shared USB Host stack thread/task. - -The Enum Driver exposes the following event callbacks: - -- ``enum_event_cb_t`` used to indicate various events regarding an enumeration process. This callback is called from the context of ``enum_process()`` - -The Enum Driver exposes the following events: - -- ``ENUM_EVENT_STARTED`` Enumeration process has been started -- ``ENUM_EVENT_RESET_REQUIRED`` Enumeration process requires device reset -- ``ENUM_EVENT_COMPLETED`` Enumeration process has been completed -- ``ENUM_EVENT_CANCELED`` Enumeration process has been canceled (due to internal error or via ``enum_cancel()`` function call) - -Device Enumeration -^^^^^^^^^^^^^^^^^^ - -The USB device enumeration process implemented in the Enum Driver is mostly based same process in the `Windows USB stack `__. The Enum Driver's enumeration process involves the following steps: - -#. First device descriptor request (to obtain the MPS of EP0) -#. Second device reset (to workaround some non-compliant devices) -#. Set device address -#. Second device descriptor request (to obtain and store the full device descriptor) -#. Configuration descriptor request (to obtain the full configuration descriptor of selected configuration) -#. Language ID Table request (checks to see if en-US is supported) -#. Manufacturer string descriptor request -#. Product string descriptor request -#. Serial number string descriptor request -#. Set configuration request (sets the device to target configuration number) - -.. note:: - - String descriptors are optional. If a device does not support string descriptors, these stages could be omitted. - -Enumeration Stages -^^^^^^^^^^^^^^^^^^ - -The Enum Driver splits the enumeration process into multiple stages which are executed linearly. Depending on the connected device, some stages (such as fetching the string descriptors) can be skipped. When a stage completes, a call to the ``enum_config_t.proc_req_cb`` callback must be made to trigger a subsequent call of ``enum_process()``.The subsequent call of ``enum_process()`` will then select and execute the next stage of enumeration. Stage completion can trigger the ``enum_config_t.proc_req_cb`` callback in one of the following ways: - -- Inside the control transfer completion callback (for stages that send a control transfer) -- Direct call to ``enum_config_t.proc_req_cb`` (for stages that don't need to wait for any event) -- Inside ``enum_proceed()`` (for stages that require some action to be carried out outside the Enum Driver) - -Any control transfer made during enumeration is split into two stages, where the first stage executes the transfer and the second stage (suffixed with ``_CHECK``) will check the results of the transfers. - -When requesting a variable length descriptors (e.g., configuration or string descriptors), the request is split into two control transfers. The first control transfer is fixed in length which only reads the header of the descriptor. The ``bLength`` field of the descriptor's header indicates the full length of the entire descriptor and is used to set the size of the second transfer which fetches the entire descriptor. As a result, any request for a variable length descriptor is split into four stages: - -- Get short **ANY** descriptor (prefixed with ``GET_SHORT_...``) -- Check short **ANY** descriptor (prefixed with ``CHECK_SHORT_...``) -- Get full **ANY** descriptor (prefixed with ``GET_FULL_...``) -- Check full **ANY** descriptor (prefixed with ``CHECK_FULL_...``) - -.. note:: - - Retrieving the Device Descriptor is an exception here because the second reset is taken place after retrieving short Device Descriptor. - -Cancel Enumeration -^^^^^^^^^^^^^^^^^^ - -In some cases (such as a device disconnection), an ongoing enumeration process may need to be cancelled. An ongoing enumeration can be cancelled (regardless of its current stage) by calling ``enum_cancel()`` which will change the enumeration process's current stage to ``ENUM_STAGE_CANCEL``. - -On the next call to ``enum_process``, the Enum Driver will execute the ``ENUM_STAGE_CANCEL`` which does the following: - -- releases the device's enumeration lock. -- frees all resources related to the current device. -- propagates the ``ENUM_EVENT_CANCELED`` event. diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst deleted file mode 100644 index 3b2876a7a4..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst +++ /dev/null @@ -1,65 +0,0 @@ -USB Host External Hub Driver (Ext Hub) -====================================== - -Introduction ------------- - -The External Hub Driver (henceforth referred to as Ext Hub Driver) - -Requirements ------------- - -USB Specification Requirements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Chapter 11 of the USB 2.0 specification outlines some aspects, when a USB Hub device is attached to a powered port. - -The design of the Ext Driver takes into consideration the following: - -- **Connectivity behavior** -- **Power management** -- **Device connect/disconnect detection** -- **Bus fault detection and recovery** -- **High-, full-, and low-speed device support** - -.. note:: - - For more detailed information, please refer to `USB 2.0 Specification `_ > Chapter 11.1 **Overview**. - -Host Stack Requirements -^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to the USB 2.0 specification requirements, the Ext Hub Driver also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): - -- Ext Hub Driver must not instantiate any tasks/threads -- Ext Hub Driver must be event driven, providing event callbacks and an event processing function -- Ext Hub Driver must use only API from underlying layer (USBH) - -Implementation & Usage ----------------------- - -Host Stack Interaction -^^^^^^^^^^^^^^^^^^^^^^ - -The Ext Hub Driver takes place between USB Host layer and USBH layer, next to the Hub Driver. The Hub Driver and the Ext Hub Driver were split into two Drivers to achieve the goal of logic distinguishing between root Hub and external Hub. - -Device handling -^^^^^^^^^^^^^^^ - -The Ext Hub Driver can be installed via ``ext_hub_install()`` call and uninstalled via ``ext_hub_uninstall()`` call. After installation the Ext Hub provides the following APIs for external Hub addition and removal: - -- ``ext_hub_new_dev()`` which will verify the device class (`HUB_CLASSCODE (09H)`) and, if the device has the Hub class, the Ext Hub Driver: - - - allocates a new device object - - adds it to the external device pool - - starts the process of Hub configuration (retrieving Hub Descriptor, Device status and Hub status) - -- ``ext_hub_dev_gone()`` which will verify the device in the Ext Hub Driver list and start the process of external Hub device removing. - -Events & Processing -^^^^^^^^^^^^^^^^^^^ - -The Ext Hub Driver is completely event driven and all event handling is done via the ``ext_hub_process()`` function. The ``ext_hub_config_t.proc_req_cb`` callback provided on the Ext Hub Driver installation will be called when processing is required. Typically, ``ext_hub_process()`` will be called from the Hub Driver ``hub_process()`` processing function. - -The Ext Hub Driver does not expose any event callback. - diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst deleted file mode 100644 index 1dc74d90e2..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst +++ /dev/null @@ -1,85 +0,0 @@ -USB Host External Port Driver (Ext Port) -======================================== - -Introduction ------------- - -The External Port Driver (henceforth referred to as Ext Port Driver) isolates the handling process for downstream facing ports, which are provided by the Ext Hub Driver. - -.. note:: - - For more detailed information, please refer to `USB 2.0 Specification `_ > Chapter 11.5 **Downstream Facing Ports**. - -Requirements ------------- - -Host Stack Requirements -^^^^^^^^^^^^^^^^^^^^^^^ - -The Ext Port Driver takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): - -- The Ext Port Driver must not instantiate any tasks/threads -- The Ext Port Driver must be event driven, providing event callbacks and an event processing function -- The Ext Port Driver must use only API from underlying layer (The Ext Hub Driver) - -Implementation & Usage ----------------------- - -Host Stack Interaction -^^^^^^^^^^^^^^^^^^^^^^ - -The Ext Port Driver is a part of The Ext Hub Driver, so the interaction and hierarchical place in USB Host Stack is the same as for the Ext Hub Driver. The Ext Hub and the Ext Port Drivers were split into two Drivers to achieve the goal of logic distinguishing between external Hubs and Downstream Facing Ports handling. - -Ports handling -^^^^^^^^^^^^^^^ - -The Ext Port Driver can be installed via ``ext_port_install()`` call and uninstalled via ``ext_port_uninstall()`` call. - -After installation, the Ext Port Driver API could be requested via ``ext_port_get_driver()`` call. - -The Ext Port Driver API ------------------------ - -The Ext Port Driver provides an API, which could be split into three groups: object control, device control and general. - -The Ext Port Driver: Object Control -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - - Create object - - Delete object - -The Ext Port Driver: Port Control -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - - Reset - - Disable - - Recycle - - Activate - - Get Speed - - Get status - - Set status - - Gone - -The Ext Port Driver: General Purpose -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - - Request processing - -Events & Processing -------------------- - -The Ext Port Driver is completely event driven and all event handling is done via the ``ext_port_process()`` function. The ``ext_port_driver_config_t.proc_req_cb`` callback provided on the Ext Port Driver installation will be called when processing is required. Typically, ``ext_port_process()`` will be called from the Hub Driver ``hub_process()`` processing function. - -The Ext Port Driver exposes the following events via ``ext_port_driver_config_t.event_cb``: - -- ``EXT_PORT_CONNECTED`` Downstream facing port has a device connection event -- ``EXT_PORT_RESET_COMPLETED`` Downstream facing port has a device and completed the port reset -- ``EXT_PORT_DISCONNECTED`` Downstream facing port has a device disconnection event - -The Ext Port Driver ports processing is based on the Hub class-specific request ``Get Port Status``. - -After successful completion of the class-specific request ``Get Port Status`` and setting the new port status, the Ext Port Driver continues the port handling while it is required by ports' state and status. - -.. note:: - - For more detailed information, please refer to `USB 2.0 Specification `_ > Chapter 11.24.2.7 **Get Port Status** diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst deleted file mode 100644 index cac7338ece..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_index.rst +++ /dev/null @@ -1,43 +0,0 @@ -USB Host Maintainers Notes (Introduction) -========================================= - -:link_to_translation:`zh_CN:[中文]` - -This document contains information regarding the implementation details of the USB Host stack. This document is intended for the maintainers and third-party contributors of the USB Host stack. Users of the USB Host stack should refer to :doc:`../usb_host` instead. - -.. warning:: - - The implementations details of the USB Host stack is categorized as private API. Thus, all layers (other than the USB Host Library) do not adhere to :ref:`ESP-IDF's versioning scheme ` (i.e., breaking changes are permitted). - -.. figure:: ../../../../_static/usb_host/stack-overview.png - :align: center - :alt: Diagram of Host Stack Layers - -This document is split into the following sections: - -.. toctree:: - :maxdepth: 1 - - usb_host_notes_design - usb_host_notes_arch - usb_host_notes_dwc_otg - usb_host_notes_usbh - usb_host_notes_enum - usb_host_notes_ext_hub - usb_host_notes_ext_port - -Todo: - -- USB Host Maintainers Notes (HAL & LL) -- USB Host Maintainers Notes (HCD) -- USB Host Maintainers Notes (Hub) -- USB Host Maintainers Notes (USB Host Library) - -.. -------------------------------------------------- Introduction ----------------------------------------------------- - -Introduction ------------- - -The ESP-IDF USB Host Stack allows the {IDF_TARGET_NAME} to operate as a USB Host. Operating as a USB Host allows the {IDF_TARGET_NAME} to communicate with a wide range of USB devices. However, most USB Host Stack implementations do not run on embedded hardware (i.e., runs on PCs and smartphones), thus have comparatively more resources (i.e., memory and CPU speed). - -The implementation of the ESP-IDF USB Host Stack (henceforth referred to as the Host Stack) takes into account the embedded nature of the {IDF_TARGET_NAME} which is reflected in various aspects of the Host Stack's design. diff --git a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst b/docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst deleted file mode 100644 index f7d673563a..0000000000 --- a/docs/en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst +++ /dev/null @@ -1,117 +0,0 @@ -.. Translation not required: According to the USB developers, all of the ``usb_host_notes_*`` files are just internal notes for ESP-IDF developers, not for our end users. So we don't need to translate them at all. - -USB Host Driver (USBH) -====================== - -Introduction ------------- - -The USB Host Driver (henceforth referred to as USBH) provides a USB Host software interface which abstracts USB devices. The USBH interface provides APIs to... - -- manage the device pool (i.e., adding and removing devices) -- address and configure a device (i.e., setting device and configuration descriptors) -- submit transfers to a particular endpoint of a device - -Requirements ------------- - -USB Specification Requirements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Chapter 10 of the USB 2.0 specification outlines some requirements of the USBH (referred to as USBD in the specification). The design of the USBH takes into consideration these requirements from the specification. - -- Default pipe of a device is owned by the USBH -- All other pipes are owned and managed by clients of the USBH -- USBH interface must provide the following services - - - Configuration and command mechanism - - Transfer services via both command and pipe mechanisms - - Event notification - - Status reporting and error recovery - -Host Stack Requirements -^^^^^^^^^^^^^^^^^^^^^^^ - -In addition to the USB 2.0 specification requirements, the USBH also takes into consideration the requirements set for the overall Host Stack (see :doc:`./usb_host_notes_design`): - -- USBH must not instantiate any tasks/threads -- USBH must be event driven, providing event callbacks and an event processing function - -Implementation & Usage ----------------------- - -Events & Processing -^^^^^^^^^^^^^^^^^^^ - -The USBH is completely event driven and all event handling is done via then ``usbh_process()`` function. The ``usbh_config_t.proc_req_cb`` callback provided on USBH installation will be called when processing is required. Typically, ``usbh_process()`` will be called from a dedicated thread/task. - -The USBH exposes the following event callbacks: - -- ``usbh_event_cb_t`` used to indicate various events regarding a particular device and control transfers to EP0. This callback is called from the context of ``usbh_process()`` -- ``usbh_ep_cb_t`` used to indicate events for all other endpoints. This callback is not called from the ``usbh_process()`` context (currently called from an HCD interrupt context). - -Device Pool -^^^^^^^^^^^ - -The USBH keeps track of all currently connected devices by internally maintaining a device pool (simply a linked list) where each device is represented by a device object. - -The USB 2.0 specification "assumes a specialized client of the USBD, called a hub driver, that acts as a clearinghouse for the addition and removal of devices from a particular hub". As a result, the USBH is completely reliant on an external client(s) (typically a Hub Driver) to inform the USBH of device addition and removal. The USBH provides the following APIs for device addition and removal: - -- ``usbh_devs_add()`` which will allocate a new device object and add it to the device pool. The newly added device will be unenumerated, meaning the device object will... - - - be assigned to address 0 - - have no device and configuration descriptor - -- ``usbh_devs_remove()`` which will indicate to the USBH that a device has been removed (such as due to a disconnection or a port error). - - - If the device is not currently opened (i.e., used by one or more clients), the USBH will free the underlying device object immediately. - - If the device is currently opened, a ``USBH_EVENT_DEV_GONE`` event will be propagated and the device will be flagged for removal. The last client to close the device will free the device object. - - When a device object is freed, a ``USBH_EVENT_DEV_FREE`` event will be propagated. This event is used to indicate that the device's upstream port can be recycled. - -Device Enumeration -^^^^^^^^^^^^^^^^^^ - -Newly added devices will need to be enumerated. The USBH provides various ``usbh_dev_set_...()`` functions to enumerate the device, such as assigning the device's address and setting device/configuration/string descriptors. Given that USBH devices can be shared by multiple clients, attempting to enumerate a device while another client has opened the device can cause issues. - -Thus, before calling any ``usbh_dev_set_...()`` enumeration function, a device must be locked for enumeration by calling ``usbh_dev_enum_lock()``. This prevents the device from being opened by any other client but the enumerating client. - -After enumeration is complete, the enumerating client can call ``usbh_devs_trigger_new_dev_event()`` to propagate a ``USBH_EVENT_NEW_DEV`` event. - -Device Usage -^^^^^^^^^^^^ - -Clients that want to use a device must open the device by calling ``usbh_devs_open()`` and providing the device's address. The device's address can either be obtained from a ``USBH_EVENT_NEW_DEV`` event or by calling ``usbh_devs_addr_list_fill()``. - -Opening a device will do the following: - -- Return a ``usb_device_handle_t`` device handle which can be used to refer to the device in various USBH functions -- Increment the device's internal ``open_count`` which indicates how many clients have opened the device. As long as ``open_count > 0``, the underlying device object will not be freed, thus guaranteeing that the device handle refers to a valid device object. - -Once a client no longer needs to use a device, the client should call ``usbh_devs_close()`` thus invalidating the device handle. - -.. note:: - - Most device related APIs accept ``usb_device_handle_t`` as an argument, which means that the calling client must have previously opened the device to obtain the device handle beforehand. This design choice is intentional in order to enforce an "open before use" pattern. - - However, a limited set of APIs (e.g., ``usbh_devs_remove()``) refer to devices using a Unique Identifier (``uid``) which is assigned on device addition (see ``usbh_devs_add()``). The use of ``uid`` in these functions allows their callers to refer to a device **without needing to open it** due to the lack of a ``usb_device_handle_t``. - - As a result, it is possible that a caller of a ``uid`` function may refer to a device that has already been freed. Thus, callers should account for a fact that these functions may return :c:macro:`ESP_ERR_NOT_FOUND`. - -Endpoints & Transfers -^^^^^^^^^^^^^^^^^^^^^ - -USBH supports transfer to default (i.e., EP0) and non-default endpoints. - -For non-default endpoints: - -- A client must first allocate the endpoint by calling ``usbh_ep_alloc()`` which assigns a ``usbh_ep_cb_t`` callback and returns a ``usbh_ep_handle_t`` endpoint handle so that the endpoint can be referred to. -- A client can then enqueue a ``urb_t`` transfer to the endpoint by calling ``usbh_ep_enqueue_urb()``. -- The ``usbh_ep_cb_t`` callback is called to indicate transfer completion -- The client must then dequeue the transfer using ``usbh_ep_dequeue_urb()`` - -Default endpoints are owned and managed by the USBH, thus API for control transfers are different: - -- EP0 is always allocated for each device, thus clients do no need to allocate EP0 or provide an endpoint callback. -- Clients call should call ``usbh_dev_submit_ctrl_urb()`` to submit a control transfer to a device's EP0. -- A ``USBH_EVENT_CTRL_XFER`` event will be propagated when the transfer is complete -- Control transfers do not need to be dequeued diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index df0cc4e964..8c043176fa 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -17,6 +17,8 @@ api-reference/mesh/index api-reference/network/index api-reference/mesh/esp_mesh api-reference/network/esp_mesh api-reference/peripherals/can api-reference/peripherals/twai api-reference/peripherals/usb api-reference/peripherals/usb_device +api-reference/peripherals/usb_device "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" +api-reference/peripherals/usb_host "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host.html" api-reference/wifi/index api-reference/network/index api-reference/wifi/esp_now api-reference/network/esp_now api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig diff --git a/docs/zh_CN/api-reference/peripherals/usb_device.rst b/docs/zh_CN/api-reference/peripherals/usb_device.rst index 7486c26c0d..36c4d19f34 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_device.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_device.rst @@ -1,470 +1,6 @@ USB 设备栈 -================= +========== :link_to_translation:`en:[English]` -{IDF_TARGET_USB_DP_GPIO_NUM:default="20", esp32h4="22"} -{IDF_TARGET_USB_DM_GPIO_NUM:default="19", esp32h4="21"} -{IDF_TARGET_USB_EP_NUM: default="6", esp32p4="15"} -{IDF_TARGET_USB_EP_NUM_INOUT:default="5", esp32p4="8"} -{IDF_TARGET_USB_EP_NUM_IN:default="1", esp32p4="7"} - -概述 --------- - -USB 设备栈（以下简称设备栈）支持在 {IDF_TARGET_NAME} 上启用 USB 设备支持。通过使用设备栈，可以为 {IDF_TARGET_NAME} 烧录任意具有明确定义的 USB 设备功能（如键盘、鼠标、摄像头）、自定义功能（也称特定供应商类别）或上述功能的组合（也称复合设备）。 - -设备栈基于 TinyUSB 栈构建，但对 TinyUSB 进行了一些小的功能扩展和修改，使其更好地集成到 ESP-IDF。设备栈通过 `乐鑫组件注册表 `__ 作为托管组件分发。 - -功能列表 --------- - -- 支持多种设备类别 (CDC, HID, MIDI, MSC) -- 支持复合设备 -- 支持特定供应商类别 -- 最多支持 {IDF_TARGET_USB_EP_NUM} 个端点 - - - {IDF_TARGET_USB_EP_NUM_INOUT} 个输入/输出端点 - - {IDF_TARGET_USB_EP_NUM_IN} 个输入端点 - -- 自供电设备的 VBUS 监测 - -.. Todo: Refactor USB hardware connect into a separate guide - -硬件连接 --------- - -.. only:: esp32s2 or esp32s3 or esp32h4 - - {IDF_TARGET_NAME} 将 USB D+ 和 D- 信号分别路由到 GPIO {IDF_TARGET_USB_DP_GPIO_NUM} 和 {IDF_TARGET_USB_DM_GPIO_NUM}。为了实现 USB 设备功能，这些 GPIO 应通过某种方式连接到总线（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。 - -.. only:: esp32p4 - - {IDF_TARGET_NAME} 将 USB D+ 和 D- 信号路由到其专用管脚。为了实现 USB 设备功能，这些管脚应通过某种方式连接到总线（例如，通过 Micro-B 端口、USB-C 端口或直接连接到标准-A 插头）。 - -.. figure:: ../../../_static/usb-board-connection.png - :align: center - :alt: 将 USB GPIO 直接接连至 USB 标准-A 插头 - :figclass: align-center - -.. only:: esp32s2 or esp32s3 or esp32h4 - - .. note:: - - 如果你使用带有两个 USB 端口的 {IDF_TARGET_NAME} 开发板，标有 "USB" 的端口已经连接到 D+ 和 D- GPIO。 - -.. note:: - - 自供电设备还必须通过电压分压器或比较器连接 VBUS，详情请参阅 :ref:`self-powered-device`。 - -.. only:: esp32s3 - - 外部 PHY 配置 - ------------- - - {IDF_TARGET_NAME} 内部集成了两个 USB 控制器：USB-OTG 与 USB-Serial-JTAG。这两个控制器 **共用同一个 PHY**，因此同一时间只能有一个控制器工作。如果在 USB-Serial-JTAG 工作时（例如调试或烧录）时仍需要使用 USB 设备功能，必须使用 **外部 PHY**，因为此时内部 PHY 已被 USB-Serial-JTAG 占用。 - - .. note:: - 使用外部 PHY 并不是在 USB 主机或设备功能开启时同时实现调试的唯一办法。也可以通过烧录对应的 eFuse，将调试接口从 USB-Serial-JTAG 切换为传统的 JTAG 接口。具体步骤请参考 ESP-IDF 编程指南中针对你的芯片的 :doc:`JTAG 调试 <../../api-guides/jtag-debugging/index>` 章节。 - - {IDF_TARGET_NAME} 支持连接外部 PHY 芯片。当需要在使用 USB-Serial-JTAG 控制器的同时提供全速 USB 设备功能时，这一点尤其重要。不同的外部 PHY 芯片可能需要不同的硬件配置，请参考各自芯片的规格书。乐鑫官方文档提供了如下的通用连接示意图供参考。如需了解更多内容，请参阅 `使用外部 PHY `__。 - - .. figure:: ../../../_static/usb_device/usb_fs_phy_sp5301.png - :align: center - :alt: usb_fs_phy_sp5301 - - 连接外部 PHY 芯片的典型电路图 - - **已测试的外部 PHY 芯片如下：** - - - **SP5301** — {IDF_TARGET_NAME} 原生支持此芯片。原理图与布线方法请参考上文链接。 - - **TUSB1106** — {IDF_TARGET_NAME} 原生支持。可通过 GPIO 映射与外部 PHY 驱动配合使用。请遵循 TUSB1106 数据手册中的参考连接（供电方案以及在 D+/D– 上建议的串联电阻）。 - - **STUSB03E** — 需要通过模拟开关进行信号切换，详情参考下方示例。 - - .. figure:: ../../../_static/usb_device/ext_phy_schematic_stusb03e.png - :align: center - :alt: 使用模拟开关的外部 PHY 原理图（设备模式） - - 使用 STUSB03E 与模拟开关的连接示例（设备模式） - - .. note:: - 此原理图仅为简化示例，用于展示外部 PHY 的连接方式，未包含完整 {IDF_TARGET_NAME} 设计所需的所有元件和信号（如 VCC、GND、RESET 等）。 - 图中包含 +5 V 电源轨（通常来自 USB VBUS）和 VCC 电源轨。VCC 电压应与芯片供电电压一致（通常为 3.3 V），并确保外部 PHY 与芯片使用同一电压域供电。如果设计自供电 USB 设备，请将外部 PHY 的 VBUSDET 信号接入 {IDF_TARGET_NAME}，以便实现对 VBUS 电压状态的监控。 - - 硬件配置通过将 GPIO 映射到 PHY 管脚实现。任何未使用的管脚（如 :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num`、:cpp:member:`usb_phy_ext_io_conf_t::fs_edge_sel_io_num`） **必须设置为 -1**。 - - .. note:: - :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num` 管脚 **当前不受支持**，无需连接。 - :cpp:member:`usb_phy_ext_io_conf_t::fs_edge_sel_io_num` 管脚为可选管脚，仅需在低速和全速模式间切换时使用。 - - ESP TinyUSB 设备栈从 2.0 版本开始支持外部 PHY。要在设备模式下使用外部 PHY，需执行以下步骤： - - 1. 使用 :cpp:type:`usb_phy_config_t` 配置 GPIO 映射与 PHY。 - 2. 调用 :cpp:func:`usb_new_phy()` 创建 PHY。 - 3. 使用 :cpp:func:`TINYUSB_DEFAULT_CONFIG()` 初始化 :cpp:type:`tinyusb_config_t`。 - 4. 将 :cpp:type:`tinyusb_config_t` 的 `phy.skip_setup` 字段设为 ``true``，从而跳过 PHY 的重新初始化，直接使用已配置的外部 PHY。 - - **示例代码：** - - .. code-block:: c - - // 外部 PHY 的 GPIO 配置 - const usb_phy_ext_io_conf_t ext_io_conf = { - .vp_io_num = 8, - .vm_io_num = 5, - .rcv_io_num = 11, - .oen_io_num = 17, - .vpo_io_num = 4, - .vmo_io_num = 46, - .suspend_n_io_num = -1, - .fs_edge_sel_io_num = -1, - }; - - // 针对 OTG 控制器（设备模式）的外部 PHY 配置与初始化 - const usb_phy_config_t phy_config = { - .controller = USB_PHY_CTRL_OTG, - .target = USB_PHY_TARGET_EXT, - .otg_mode = USB_OTG_MODE_DEVICE, - .otg_speed = USB_PHY_SPEED_FULL, - .ext_io_conf = &ext_io_conf - }; - - usb_phy_handle_t phy_hdl; - ESP_ERROR_CHECK(usb_new_phy(&phy_config, &phy_hdl)); - - // 使用默认配置初始化 TinyUSB（可根据需要设置事件处理函数） - tinyusb_config_t config = TINYUSB_DEFAULT_CONFIG(); - config.phy.skip_setup = true; - - tinyusb_driver_install(&config); - - 通过上述配置，USB 设备栈会直接使用 **外部 PHY**，而不会尝试配置内部 PHY。 - -设备栈结构 ----------- - -设备栈以 TinyUSB 栈为基础，在此基础上，该设备栈实现了以下功能： - -- 自定义 USB 描述符 -- 支持串行设备 -- 通过串行设备重定向标准流 -- 提供用于 USB 设备 MSC 类的存储介质（SPI-Flash 和 SD 卡） -- 封装设备栈中处理 TinyUSB 服务的任务 - -组件依赖项 -------------- - -设备栈通过 `乐鑫组件注册表 `__ 分发，使用前，请使用以下命令将设备栈组件添加为依赖项： - -.. code:: bash - - idf.py add-dependency esp_tinyusb - -配置选项 -^^^^^^^^^ - -通过 menuconfig 选项，可以对设备栈进行以下多方面配置： - -- TinyUSB 日志的详细程度 -- 设备栈任务相关选项 -- 默认设备/字符串描述符选项 -- 特定类别的选项 - -.. _descriptors-configuration: - -配置描述符 -^^^^^^^^^^^^^^^^^^^^^^^^^ - -结构体 :cpp:type:`tinyusb_config_t` 提供了与 USB 描述符相关的字段，应进行初始化。 - -无论是全速 USB 设备还是高速 USB 设备，都应初始化以下描述符： - -- :cpp:member:`device_descriptor` -- :cpp:member:`string_descriptor` - -全速 USB 设备应初始化以下字段，以提供相应的配置描述符： - -- :cpp:member:`configuration_descriptor` - -.. only:: esp32p4 - - 高速 USB 设备应初始化以下字段，以提供不同速度下的配置描述符： - - - :cpp:member:`fs_configuration_descriptor` - - :cpp:member:`hs_configuration_descriptor` - - :cpp:member:`qualifier_descriptor` - - .. note:: - - 为符合 USB 2.0 协议规范，需同时初始化 :cpp:member:`fs_configuration_descriptor` 和 :cpp:member:`hs_configuration_descriptor`。 - -调用 :cpp:func:`tinyusb_driver_install` 时，设备栈将基于上述字段中提供的描述符实现 USB 设备。 - -设备栈还提供了默认描述符，将 :cpp:func:`tinyusb_driver_install` 中的相应字段设置为 ``NULL`` 即可安装。默认描述符包括： - -- 默认设备描述符：如需启用，将 :cpp:member:`device_descriptor` 设置为 ``NULL``。默认设备描述符将使用相应的 menuconfig 选项设置的值（如 PID、VID、bcdDevice 等）。 -- 默认字符串描述符：如需启用，将 :cpp:member:`string_descriptor` 设置为 ``NULL``。默认字符串描述符将使用相应的 menuconfig 选项设置的值（如制造商、产品和序列字符串描述符选项）。 -- 默认配置描述符。某些很少需要自定义配置的类别（如 CDC 和 MSC）将提供默认配置描述符。如需启用，将相应的配置描述符字段设置为 ``NULL``。 - - - :cpp:member:`configuration_descriptor`：全速描述符，仅适用于全速设备 - - :cpp:member:`fs_configuration_descriptor`：全速描述符，适用于高速设备 - - :cpp:member:`hs_configuration_descriptor`：高速描述符，适用于高速设备 - -.. note:: - - 为实现向后兼容性，若设备栈支持高速，可使用 :cpp:member:`configuration_descriptor` 代替 :cpp:member:`fs_configuration_descriptor` 来设置全速配置描述符。 - -安装设备栈 ----------- - -请调用 :cpp:func:`tinyusb_driver_install` 安装设备栈。结构体 :cpp:type:`tinyusb_config_t` 指定了设备栈的配置，而 :cpp:type:`tinyusb_config_t` 作为参数传递给 :cpp:func:`tinyusb_driver_install`。 - -.. note:: - - 结构体 :cpp:type:`tinyusb_config_t` 可以实现零初始化（如 ``const tinyusb_config_t tusb_cfg = { 0 };``）或部分初始化（如下所示）。对于结构体中任何初始化为 ``0`` 或 ``NULL`` 的成员，设备栈将使用其默认配置，请参阅如下示例。 - -.. code-block:: c - - const tinyusb_config_t partial_init = { - .device_descriptor = NULL, // 使用在 menuconfig 中指定的默认设备描述符 - .string_descriptor = NULL, // 使用在 menuconfig 中指定的默认字符串描述符 - .external_phy = false, // 使用内部 USB PHY - #if (TUD_OPT_HIGH_SPEED) - .fs_configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认全速配置描述符 - .hs_configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认高速配置描述符 - .qualifier_descriptor = NULL, // 使用默认限定描述符，值取自默认设备描述符 - #else - .configuration_descriptor = NULL, // 使用在 menuconfig 中根据设置指定的默认配置描述符 - #endif // TUD_OPT_HIGH_SPEED - - }; - -.. _self-powered-device: - -自供电设备 -------------------- - -USB 规范要求自供电设备监测 USB 的 VBUS 信号的电压水平。与总线供电设备相反，即使没有 USB 连接，自供电设备也可以正常工作。通过监测 VBUS 电压水平，自供电设备可以检测连接和断开事件。当 VBUS 电压升高到 4.75 V 以上时视为有效；当 VBUS 电压下降到 4.35 V 以下时视为无效。 - -在 {IDF_TARGET_NAME} 上，需要使用一个 GPIO 作为电压感测管脚，检测 VBUS 处于在规定阈值之上/之下。然而，由于 {IDF_TARGET_NAME} 管脚具有 3.3 V 容差，即使 VBUS 上升/下降到高于/低于上述规定阈值，{IDF_TARGET_NAME} 仍会显示为逻辑高电平。因此，为了检测 VBUS 是否有效，可以采用以下方法： - -- 将 VBUS 连接至电压比较器芯片/电路，该芯片/电路可检测上述阈值（即 4.35 V 和 4.75 V），并向 {IDF_TARGET_NAME} 输出 3.3 V 逻辑电平，指示 VBUS 是否有效。 -- 如果 VBUS 为 4.4 V，则使用电阻分压器输出 (0.75 x Vdd)（见下图）。 - -.. note:: - - 在这两种情况下，设备从 USB 主机拔出后 3 毫秒内，传感管脚上的电压必须为逻辑低电平。 - -.. figure:: ../../../_static/diagrams/usb/usb_vbus_voltage_monitor.png - :align: center - :alt: 用于 VBUS 监测的简易分压器 - :figclass: align-center - - 用于 VBUS 监测的简易分压器 - -请在结构体 :cpp:type:`tinyusb_config_t` 中将 :cpp:member:`self_powered` 设置为 ``true``，并将 :cpp:member:`vbus_monitor_io` 设置为用于 VBUS 监测的 GPIO 管脚编号以使用此功能。 - -USB 串行设备 (CDC-ACM) ---------------------------- - -如果在 menuconfig 中启用了 CDC 选项，则可以根据 :cpp:type:`tinyusb_config_cdcacm_t` 的设置，使用 :cpp:func:`tusb_cdc_acm_init` 初始化 USB 串行设备，请参阅如下示例： - -.. code-block:: c - - const tinyusb_config_cdcacm_t acm_cfg = { - .usb_dev = TINYUSB_USBDEV_0, - .cdc_port = TINYUSB_CDC_ACM_0, - .rx_unread_buf_sz = 64, - .callback_rx = NULL, - .callback_rx_wanted_char = NULL, - .callback_line_state_changed = NULL, - .callback_line_coding_changed = NULL - }; - tusb_cdc_acm_init(&acm_cfg); - -可以在配置结构体中设置指向 :cpp:type:`tusb_cdcacm_callback_t` 函数的指针指定回调函数，或在初始化 USB 串行设备后，调用 :cpp:func:`tinyusb_cdcacm_register_callback` 指定回调函数。 - -USB 串行控制台 -^^^^^^^^^^^^^^^^^^ - -USB 串行设备支持将所有标准输入/输出流 (stdin、stdout、stderr) 重定向到 USB。因此，调用如 ``printf()`` 等标准库输入/输出函数将导致通过 USB 而不是 UART 发送/接收数据。 - -建议调用 :cpp:func:`esp_tusb_init_console` 将标准输入/输出流切换到 USB，并调用 :cpp:func:`esp_tusb_deinit_console` 将其切换回 UART。 - -USB 大容量存储设备 (MSC) ------------------------------ - -在 menuconfig 中启用 MSC ``CONFIG_TINYUSB_MSC_ENABLED`` 选项时，可以将 ESP 芯片作为 USB 大容量存储设备使用。按如下示例，可以初始化存储媒介（SPI-Flash 或 SD 卡）。 - -- SPI-Flash - -.. code-block:: c - - static esp_err_t storage_init_spiflash(wl_handle_t *wl_handle) - { - *** - esp_partition_t *data_partition = esp_partition_find_first(ESP_PARTITION_TYPE_DATA, ESP_PARTITION_SUBTYPE_DATA_FAT, NULL); - *** - wl_mount(data_partition, wl_handle); - *** - } - storage_init_spiflash(&wl_handle); - - const tinyusb_msc_spiflash_config_t config_spi = { - .wl_handle = wl_handle - }; - tinyusb_msc_storage_init_spiflash(&config_spi); - - -- SD 卡 - -.. code-block:: c - - static esp_err_t storage_init_sdmmc(sdmmc_card_t **card) - { - *** - sdmmc_host_t host = SDMMC_HOST_DEFAULT(); - sdmmc_slot_config_t slot_config = SDMMC_SLOT_CONFIG_DEFAULT(); - // 对于 SD 卡，设置要使用的总线宽度 - - slot_config.width = 4; - slot_config.clk = CONFIG_EXAMPLE_PIN_CLK; - slot_config.cmd = CONFIG_EXAMPLE_PIN_CMD; - slot_config.d0 = CONFIG_EXAMPLE_PIN_D0; - slot_config.d1 = CONFIG_EXAMPLE_PIN_D1; - slot_config.d2 = CONFIG_EXAMPLE_PIN_D2; - slot_config.d3 = CONFIG_EXAMPLE_PIN_D3; - slot_config.flags |= SDMMC_SLOT_FLAG_INTERNAL_PULLUP; - - sd_card = (sdmmc_card_t *)malloc(sizeof(sdmmc_card_t)); - (*host.init)(); - sdmmc_host_init_slot(host.slot, (const sdmmc_slot_config_t *) &slot_config); - sdmmc_card_init(&host, sd_card); - *** - } - storage_init_sdmmc(&card); - - const tinyusb_msc_sdmmc_config_t config_sdmmc = { - .card = card - }; - tinyusb_msc_storage_init_sdmmc(&config_sdmmc); - -MSC 性能优化 -^^^^^^^^^^^^^^ - -**single-buffer 方案** - -single-buffer 方案通过使用专用 buffer 临时存储接收到的写入数据，而不是在回调中立即处理，从而提升性能。 - -- **可配置的 buffer 大小**： 通过 ``CONFIG_TINYUSB_MSC_BUFSIZE`` 参数设置 buffer 大小，用户可以根据实际需要，灵活调整性能与存储占用的平衡点。 - -该方案确保了 USB 传输的效率，同时避免因存储操作可能带来的延迟。 - -**USB MSC 驱动器性能** - -.. only:: esp32s3 - - .. list-table:: - :header-rows: 1 - :widths: 20 20 20 - - * - FIFO 大小 - - 读取速度 - - 写入速度 - - * - 512 B - - 0.566 MB/s - - 0.236 MB/s - - * - 8192 B - - 0.925 MB/s - - 0.928 MB/s - -.. only:: esp32p4 - - .. list-table:: - :header-rows: 1 - :widths: 20 20 20 - - * - FIFO 大小 - - 读取速度 - - 写入速度 - - * - 512 B - - 1.174 MB/s - - 0.238 MB/s - - * - 8192 B - - 4.744 MB/s - - 2.157 MB/s - - * - 32768 B - - 5.998 MB/s - - 4.485 MB/s - -.. only:: esp32s2 - - .. note:: - - {IDF_TARGET_NAME} 在 MSC 设备模式下不支持 SD 卡功能。 - - **SPI flash 性能：** - - .. list-table:: - :header-rows: 1 - :widths: 20 20 - - * - FIFO 大小 - - 写入速度 - - * - 512 B - - 5.59 KB/s - - * - 8192 B - - 21.54 KB/s - -.. only:: esp32h4 - - .. note:: - - {IDF_TARGET_NAME} 不支持在 MSC 设备模式下使用 SD 卡。 - - **SPI Flash 性能：** - - .. list-table:: - :header-rows: 1 - :widths: 20 20 - - * - FIFO 大小 - - 写入速度 - - * - 512 B - - 4.48 KB/s - - * - 8192 B - - 22.33 KB/s - -性能限制： - -- **内部 SPI flash 性能** 受架构限制影响。程序执行和存储访问共享同一 flash 芯片，导致写入 flash 时必须暂停程序执行，会显著影响性能。 -- **内部 SPI flash 主要适用于演示场景**。在需要更高性能的实际应用中，在支持的情况下使用 **外部存储设备**，如 SD 卡或外部 SPI flash 芯片。 - -.. only:: esp32s3 or esp32p4 - - SD 卡不受此限制影响，因此能获得更高的性能提升。 - -应用示例 --------------------- - -如需查看相关示例，请前往目录 :example:`peripherals/usb/device`。 - -- :example:`peripherals/usb/device/tusb_console` 演示了如何使用 TinyUSB 组件配置 {IDF_TARGET_NAME}，以通过串行设备连接获取和输出日志，适用于任何支持 USB-OTG 的乐鑫开发板。 -- :example:`peripherals/usb/device/tusb_serial_device` 演示了如何使用 TinyUSB 组件将 {IDF_TARGET_NAME} 配置为 USB 串行设备，还支持配置为双串行设备。 -- :example:`peripherals/usb/device/tusb_midi` 演示了如何使用 TinyUSB 组件将 {IDF_TARGET_NAME} 配置为 USB MIDI 设备，从而通过本地 USB 端口输出 MIDI 音符序列。 -- :example:`peripherals/usb/device/tusb_hid` 演示了如何使用 TinyUSB 组件实现 USB 键盘和鼠标，在连接到 USB 主机时发送 “按下和释放 key a/A” 事件，并使鼠标沿方形轨迹移动。 -- :example:`peripherals/usb/device/tusb_msc` 演示了如何使用 USB 功能创建一个可以被 USB 主机识别的大容量存储设备，允许访问其内部数据存储，支持 SPI Flash 和 SD MMC 卡存储介质。 -- :example:`peripherals/usb/device/tusb_composite_msc_serialdevice` 演示了如何使用 TinyUSB 组件将 {IDF_TARGET_NAME} 同时配置为 USB 串行设备和 MSC 设备（存储介质为 SPI-Flash）运行。 - -.. only:: not esp32p4 and not esp32h4 - - - :example:`peripherals/usb/device/tusb_ncm` 演示了使用 TinyUSB 组件，借助网络控制模型 (NCM) 将 Wi-Fi 数据通过 USB 传输到 Linux 或 Windows 主机。NCM 是通信设备类 (CDC) USB 设备的一个子类，专用于 Ethernet-over-USB 应用。 +USB 设备文档已迁移到 `ESP-USB `_。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst index 8755995d33..6c61392806 100644 --- a/docs/zh_CN/api-reference/peripherals/usb_host.rst +++ b/docs/zh_CN/api-reference/peripherals/usb_host.rst @@ -3,734 +3,4 @@ USB 主机 :link_to_translation:`en:[English]` -{IDF_TARGET_OTG_NUM_HOST_CHAN: default="8", esp32p4="16"} - -本文档提供了 USB 主机库的相关信息，按以下章节展开： - -.. contents:: 章节 - :depth: 2 - -.. ---------------------------------------------------- Overview ------------------------------------------------------- - -概述 --------- - -USB 主机库（以下简称主机库）是 USB 主机栈的最底层，提供面向公众开放的 API。应用程序使用 USB 主机功能时，通常无需与主机库直接交互，而是使用某个主机 Class 驱动提供的 API，这些主机 Class 驱动构建在主机库之上。 - -然而，由于以下的某些原因（但不仅限于此），有时你可能需要直接使用主机库： - -- 需要实现自定义主机 Class 驱动程序 -- 需要更低级别的 USB 主机 API - -特性和限制 -^^^^^^^^^^^^^^^^^^^^^^ - -主机库具有以下特性： - -.. list:: - - :esp32s2 or esp32s3 or esp32h4: - 支持全速 (FS) 和低速 (LS) 设备。 - :esp32p4: - 支持高速 (HS)、全速 (FS) 和低速 (LS) 设备。 - - 支持四种传输类型，即控制传输、块传输、中断传输和同步传输。 - :esp32p4: - 支持高带宽等时性端点。 - :esp32p4: - {IDF_TARGET_NAME} 包含两个 USB 2.0 OTG 外设：USB 2.0 OTG 高速和 USB 2.0 OTG 全速，二者均支持 USB 主机功能。但由于当前软件的限制，同一时间仅能有一个作为 USB 主机工作。未来版本计划支持两个 USB 主机同时运行。 - - 支持多个 Class 驱动程序同时运行，即主机的多个客户端同时运行。 - - 单个设备可以由多个客户端同时使用，如复合设备。 - - 主机库及其底层主机栈不会在内部自动创建操作系统任务，任务数量完全由主机库接口的使用方式决定。一般来说，任务数量为 ``（运行中的主机 Class 驱动程序数量 + 1）``。 - - 支持单个 Hub（启用选项 `CONFIG_USB_HOST_HUBS_SUPPORTED`）。 - - 支持多个 Hub（启用选项 `CONFIG_USB_HOST_HUB_MULTI_LEVEL`）。 - - 支持全局挂起与恢复，通过挂起或恢复整个总线来实现。 - - 支持通过提交传输自动触发全局恢复。 - -目前，主机库及其底层主机栈存在以下限制： - -.. list:: - - - 仅支持异步传输。 - - 仅支持使用发现的首个配置，尚不支持变更为其他配置。 - - 尚不支持传输超时。 - - 尚未支持选择性（按设备/按端口）挂起/恢复。 - - 尚不支持由 USB 设备发起的远程唤醒。 - - 外部 Hub 驱动：不支持远程唤醒功能（即使没有设备插入，外部 Hub 也处于工作状态）。 - - 外部 Hub 驱动：不处理错误用例（尚未实现过流处理、初始化错误等功能）。 - - 外部 Hub 驱动：不支持接口选择。驱动程序使用具有 Hub 类代码 (09h) 的第一个可用接口。 - - 外部端口驱动：无下游端口去抖动机制（尚未实现）。 - :esp32p4: - 外部 Hub 驱动：无事务转换层（当 Hub 连接到高速主机时，不支持全速/低速设备）。 - - -.. -------------------------------------------------- Architecture ----------------------------------------------------- - -架构 ------------- - -.. figure:: ../../../_static/usb_host_lib_entities.png - :align: center - :alt: USB 主机功能的关键实体 - :figclass: align-center - - USB 主机功能涉及的关键实体 - -上图展示了使用 USB 主机功能时涉及的关键实体，包括： - -- **主机库** -- 主机库的 **客户端** -- **设备** -- 主机库的 **守护进程任务** - -主机库 -^^^^^^^^^^^^ - -主机库是 ESP-IDF USB 主机栈中面向公众开放的最底层的 API 层。任何其他 ESP-IDF 组件（如 Class 驱动程序或用户组件），如果需要与连接的 USB 设备通信，只能直接或间接使用主机库 API。 - -主机库 API 分为两类，即 **库 API** 和 **客户端 API**。 - -- 客户端 API 负责主机库的客户端与一或多个 USB 设备间的通信，该 API 只能由主机库的注册客户端调用。 -- 库 API 负责主机库处理的通信中不特定于单个客户端的通信，如设备枚举。该 API 通常由主机库的守护进程任务调用。 - -客户端 -^^^^^^^ - -主机库的客户端指使用主机库与 USB 设备通信的软件组件，如主机 Class 驱动程序或用户组件。每个客户端通常与任务间存在一对一关系，这表明，对特定客户端而言，其所有客户端 API 都应该在同一任务的上下文中调用。 - -通过将使用主机库的软件组件进行分类，划分为独立的客户端，主机库可以将所有客户端特定事件的处理委托给客户端对应的任务。换句话说，每个客户端任务负责管理与其对应的客户端之间的所有 USB 通信操作和事件处理，无需关心其他客户端的事件。 - -守护进程任务 -^^^^^^^^^^^^ - -尽管主机库将客户端事件的处理委托给客户端本身，但仍然需要处理主机库事件，即不特定于客户端的事件。主机库事件处理可能涉及以下内容： - -- 处理 USB 设备的连接、枚举和断连 -- 将控制传输从/向客户端进行重定向 -- 将事件转发给客户端 - -因此，除客户端任务外，主机库也需要一个任务来处理所有的库事件，这个任务通常是主机库守护进程任务。 - -设备 -^^^^^^^ - -主机库隔离了客户端与设备处理的细节，包括连接、内存分配和枚举等，客户端只需提供已连接且已枚举的设备列表供选择。默认情况下，在枚举过程中，每个设备都会自动配置为使用找到的第一个配置，即通过获取配置描述符请求返回的第一个配置描述符。对于大多数标准设备，通常将第一个配置的 ``bConfigurationValue`` 设置为 ``1``。启用选项 `CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 后，可以选择不同的 ``bConfigurationValue``。获取更多详细信息，请参阅 `多项配置支持`_。 - -只要不与相同接口通信，两个及以上的客户端可以同时与同一设备通信。然而，多个客户端同时与相同设备的默认端点（即 EP0）通信，将导致它们的控制传输序列化。 - -要与设备通信，客户端必须满足以下条件： - -#. 使用设备地址打开设备，告知主机库，客户端正在使用该设备。 -#. 获取将用于通信的接口，防止其他客户端获取相同的接口。 -#. 通过已经获取了使用权的设备接口的端点通信通道发送数据传输。客户端的任务负责处理其与 USB 设备通信相关的操作和事件。 - - -.. ------------------------------------------------------ Usage -------------------------------------------------------- - -用法 ------ - -主机库及底层主机栈不会创建任何任务，客户端任务和守护进程任务等均需由 Class 驱动程序或用户自行创建。然而，主机库提供了两个事件处理函数，可以处理所有必要的主机库操作，这些函数应从客户端任务和守护进程任务中重复调用。因此，客户端任务和守护进程任务的使用将主要集中于调用这些事件处理函数。 - -主机库与守护进程任务 -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -基本用法 -""""""""""" - -主机库 API 提供了 :cpp:func:`usb_host_lib_handle_events`，可以处理库事件。该函数需要反复调用，通常是从守护进程任务中调用。函数 :cpp:func:`usb_host_lib_handle_events` 有以下特点： - -- 该函数会持续阻塞，直至需要处理库事件。 -- 每次调用该函数都会返回事件标志，有助于了解卸载主机库的时机。 - -最基础的守护进程任务通常类似以下代码片段： - -.. code-block:: c - - #include "usb/usb_host.h" - - void daemon_task(void *arg) - { - ... - bool exit = false; - while (!exit) { - uint32_t event_flags; - usb_host_lib_handle_events(portMAX_DELAY, &event_flags); - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS) { - ... - } - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_ALL_FREE) { - ... - } - ... - } - ... - } - -.. note:: - - 了解守护进程任务的完整示例，请前往 :example:`peripherals/usb/host/usb_host_lib`。 - -生命周期 -""""""""" - -.. figure:: ../../../_static/usb_host_lib_lifecycle.png - :align: center - :alt: USB 主机库典型生命周期 - :figclass: align-center - - USB 主机库典型生命周期 - -上图展示了 USB 主机库的典型生命周期，其中涉及多个客户端和设备。具体而言，示例涉及以下内容： - -- 两个已注册的客户端（客户端 1 和客户端 2）。 -- 两个已连接的设备（设备 1 和设备 2），其中客户端 1 与设备 1 通信，客户端 2 与设备 2 通信。 - -参考上图可知，典型 USB 主机库生命周期包括以下关键阶段： - -1. 调用 :cpp:func:`usb_host_install`，安装主机库。 - - 调用任意主机库 API 前，请确保已完成主机库安装。 - - 调用 :cpp:func:`usb_host_install` 的位置（如从守护进程任务或其他任务中调用）取决于守护系统任务、客户端任务和系统其余部分间的同步逻辑。 -2. 安装完主机库后，调用 :cpp:func:`usb_host_client_register` 注册客户端。 - - 该注册函数通常从客户端任务调用，而客户端任务需等待来自守护进程任务的信号。 - - 调用过 :cpp:func:`usb_host_install` 后，如有需要，也可以在其他地方调用该注册函数。 -3. 设备 1 连接，并进行枚举。 - - 每个已注册的客户端（本案例中为客户端 1 和客户端 2）都会通过 :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` 事件得到新设备的通知。 - - 客户端 1 开启设备 1，并与之通信。 -4. 设备 2 连接，并进行枚举。 - - 客户端 1 和 2 通过 :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` 事件得到新设备的通知。 - - 客户端 2 开启设备 2，并与之通信。 -5. 设备 1 突然断开连接。 - - 客户端 1 通过 :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_GONE` 得到通知，并开始清理，关闭和释放客户端 1 与设备 1 之间的关联资源。 - - 客户端 2 不会收到通知，因为它并未开启设备 1。 -6. 客户端 1 完成清理，调用 :cpp:func:`usb_host_client_deregister` 注销客户端。 - - 该注销函数通常在任务退出前，从客户端任务中调用。 - - 如有需要，只要客户端 1 已完成清理，也可以在其他地方调用该注销函数。 -7. 客户端 2 完成与设备 2 的通信，随后关闭设备 2，并自行注销。 - - 由于客户端 2 是最后一个注销的客户端，通过 :c:macro:`USB_HOST_LIB_EVENT_FLAGS_NO_CLIENTS` 事件标志，守护进程任务可以得知，所有客户端已注销。 - - 设备 2 未释放，仍会进行分配，因为虽然没有任何客户端打开设备 2，但它仍处于连接状态。 -8. 所有客户端注销后，守护进程任务开始清理。 - - 守护进程任务需要先调用 :cpp:func:`usb_host_device_free_all`，释放设备 2。 - - 如果 :cpp:func:`usb_host_device_free_all` 能够成功释放所有设备，函数将返回 `ESP_OK`，表明已释放所有设备。 - - 如果 :cpp:func:`usb_host_device_free_all` 无法成功释放所有设备，例如因为设备仍由某个客户端开启，函数将返回 `ESP_ERR_NOT_FINISHED`。 - - 守护进程任务必须等待 :cpp:func:`usb_host_lib_handle_events` 返回事件标志 :c:macro:`USB_HOST_LIB_EVENT_FLAGS_ALL_FREE`，方知何时所有设备均已释放。 -9. 一旦守护进程任务确认所有客户端均已注销，且所有设备均已释放，便可调用 :cpp:func:`usb_host_uninstall`，卸载主机库。 - -客户端与 Class 驱动程序 -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -基本用法 -""""""""""" - -主机库 API 提供函数 :cpp:func:`usb_host_client_handle_events`，可以处理特定客户端事件。该函数需要反复调用，通常是从客户端任务中调用。函数 :cpp:func:`usb_host_client_handle_events` 有以下特点： - -- 该函数可以持续阻塞，直至需要处理客户端事件。 -- 该函数的主要目的是发生客户端事件时，调用多个事件处理回调函数。 - -以下回调函数均从 :cpp:func:`usb_host_client_handle_events` 中调用，因此客户端任务能够获取事件通知。 - -- 类型为 :cpp:type:`usb_host_client_event_cb_t` 的客户端事件回调函数会将客户端事件消息传递给客户端，提示添加、移除设备等事件。 -- 类型为 :cpp:type:`usb_transfer_cb_t` 的 USB 传输完成回调函数表明，先前由客户端提交的特定 USB 传输已完成。 - -.. note:: - - 考虑到上述回调函数从 :cpp:func:`usb_host_client_handle_events` 中调用，应避免在回调函数内部阻塞，否则将导致 :cpp:func:`usb_host_client_handle_events` 阻塞，阻止其他待处理的客户端事件得到处理。 - -以下代码片段展示了一个基础的主机 Class 驱动程序及其客户端任务，代码片段中包括： - -- 一个简单的客户端任务函数 ``client_task``，它会在循环中调用 :cpp:func:`usb_host_client_handle_events`。 -- 使用客户端事件回调函数和传输完成回调函数。 -- 一个用于 Class 驱动程序的简单状态机。该 Class 驱动程序仅支持打开设备，发送 OUT 传输到 EP1，然后关闭设备。 - -.. code-block:: c - - #include - #include "usb/usb_host.h" - - #define CLASS_DRIVER_ACTION_OPEN_DEV 0x01 - #define CLASS_DRIVER_ACTION_TRANSFER 0x02 - #define CLASS_DRIVER_ACTION_CLOSE_DEV 0x03 - - struct class_driver_control { - uint32_t actions; - uint8_t dev_addr; - usb_host_client_handle_t client_hdl; - usb_device_handle_t dev_hdl; - }; - - static void client_event_cb(const usb_host_client_event_msg_t *event_msg, void *arg) - { - //该函数从 usb_host_client_handle_events() 中调用，请勿在此阻塞，并尽量保持简洁 - struct class_driver_control *class_driver_obj = (struct class_driver_control *)arg; - switch (event_msg->event) { - case USB_HOST_CLIENT_EVENT_NEW_DEV: - class_driver_obj->actions |= CLASS_DRIVER_ACTION_OPEN_DEV; - class_driver_obj->dev_addr = event_msg->new_dev.address; //存储新设备的地址 - break; - case USB_HOST_CLIENT_EVENT_DEV_GONE: - class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; - break; - default: - break; - } - } - - static void transfer_cb(usb_transfer_t *transfer) - { - //该函数从 usb_host_client_handle_events() 中调用，请勿在此阻塞，并尽量保持简洁 - struct class_driver_control *class_driver_obj = (struct class_driver_control *)transfer->context; - printf("Transfer status %d, actual number of bytes transferred %d\n", transfer->status, transfer->actual_num_bytes); - class_driver_obj->actions |= CLASS_DRIVER_ACTION_CLOSE_DEV; - } - - void client_task(void *arg) - { - ... //等待主机库安装 - //初始化 Class 驱动程序对象 - struct class_driver_control class_driver_obj = {0}; - //注册客户端 - usb_host_client_config_t client_config = { - .is_synchronous = false, - .max_num_event_msg = 5, - .async = { - .client_event_callback = client_event_cb, - .callback_arg = &class_driver_obj, - } - }; - usb_host_client_register(&client_config, &class_driver_obj.client_hdl); - //分配一个 USB 传输 - usb_transfer_t *transfer; - usb_host_transfer_alloc(1024, 0, &transfer); - - //事件处理循环 - bool exit = false; - while (!exit) { - //调用客户端事件处理函数 - usb_host_client_handle_events(class_driver_obj.client_hdl, portMAX_DELAY); - //执行待处理的 Class 驱动程序操作 - if (class_driver_obj.actions & CLASS_DRIVER_ACTION_OPEN_DEV) { - //开启设备，声明接口 1 - usb_host_device_open(class_driver_obj.client_hdl, class_driver_obj.dev_addr, &class_driver_obj.dev_hdl); - usb_host_interface_claim(class_driver_obj.client_hdl, class_driver_obj.dev_hdl, 1, 0); - } - if (class_driver_obj.actions & CLASS_DRIVER_ACTION_TRANSFER) { - //发送一个 OUT 传输到 EP1 - memset(transfer->data_buffer, 0xAA, 1024); - transfer->num_bytes = 1024; - transfer->device_handle = class_driver_obj.dev_hdl; - transfer->bEndpointAddress = 0x01; - transfer->callback = transfer_cb; - transfer->context = (void *)&class_driver_obj; - usb_host_transfer_submit(transfer); - } - if (class_driver_obj.actions & CLASS_DRIVER_ACTION_CLOSE_DEV) { - //释放接口，关闭设备 - usb_host_interface_release(class_driver_obj.client_hdl, class_driver_obj.dev_hdl, 1); - usb_host_device_close(class_driver_obj.client_hdl, class_driver_obj.dev_hdl); - exit = true; - } - ... //处理其他 Class 驱动程序要求的行为 - } - - //清理 Class 驱动程序 - usb_host_transfer_free(transfer); - usb_host_client_deregister(class_driver_obj.client_hdl); - ... //删除客户端任务。如有需要，向守护进程任务发送信号。 - } - -.. note:: - - 在实际应用中，主机 Class 驱动程序还能支持更多功能，因此也存在更复杂的状态机。主机 Class 驱动程序可能需要： - - - 能够开启多个设备 - - 解析已开启设备的描述符，确定设备是否是目标 Class - - 按特定顺序，与接口的多个端点通信 - - 声明设备的多个接口 - - 处理各种错误情况 - -生命周期 -""""""""" - -客户端任务与 Class 驱动程序的典型生命周期包括以下关键阶段： - -#. 等待与主机库有关的信号完成安装。 -#. 通过 :cpp:func:`usb_host_client_register` 注册客户端，并分配其他的 Class 驱动程序资源，如使用 :cpp:func:`usb_host_transfer_alloc` 分配传输。 -#. 对于 Class 驱动程序需要与之通信的各个新设备： - - a. 调用 :cpp:func:`usb_host_device_addr_list_fill`，检查设备是否已连接。 - b. 如果设备尚未连接，则等待客户端事件回调函数的 :cpp:enumerator:`USB_HOST_CLIENT_EVENT_NEW_DEV` 事件。 - c. 调用 :cpp:func:`usb_host_device_open` 开启设备。 - d. 分别调用 :cpp:func:`usb_host_get_device_descriptor` 和 :cpp:func:`usb_host_get_active_config_descriptor`，解析设备和配置描述符。 - e. 调用 :cpp:func:`usb_host_interface_claim`，声明设备的必要接口。 - -#. 调用 :cpp:func:`usb_host_transfer_submit` 或 :cpp:func:`usb_host_transfer_submit_control`，向设备提交传输。 -#. 一旦 :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_GONE` 事件表示，Class 驱动程序不再需要已打开的设备，或者设备断开连接： - - a. 在这些端点上调用 :cpp:func:`usb_host_endpoint_halt` 和 :cpp:func:`usb_host_endpoint_flush`，停止先前提交的传输。 - b. 调用 :cpp:func:`usb_host_interface_release`，释放先前声明的所有接口。 - c. 调用 :cpp:func:`usb_host_device_close`，关闭设备。 - -#. 调用 :cpp:func:`usb_host_client_deregister` 注销客户端，并释放其他 Class 驱动程序资源。 -#. 删除客户端任务。如有需要，向守护进程任务发送信号。 - - -.. ---------------------------------------------------- 电源管理 ----------------------------------------------- - -电源管理 ----------------- - -全局挂起/恢复 -^^^^^^^^^^^^^^^^^^^^^ - -USB 主机库支持全局挂起/恢复，也就是挂起或恢复整个 USB 总线。全局挂起恢复通过根端口实现。挂起时，USB 主机会停止发送 SOF 包，从而使连接到 USB 总线的所有设备进入挂起状态。 - -请注意，全局挂起/恢复并 **不会** 在 USB 主机端挂起/恢复 USB-OTG 外设，因此并 **不会** 降低主机控制器本身的功耗。 - -事件 -^^^^^^ - -客户端事件 -""""""""""""" - -当设备被挂起或恢复时，所有已打开该受影响设备的客户端都会通过以下事件收到通知。每个事件都包含该被挂起或已恢复设备的句柄： - -- :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_SUSPENDED` — 设备已进入挂起状态。 - -- :cpp:enumerator:`USB_HOST_CLIENT_EVENT_DEV_RESUMED` — 设备已恢复运行。 - -USB 主机库事件 -"""""""""""""""""""" - -下列事件与自动挂起定时器相关联。定时器超时后，其回调函数会解除 USB 主机库处理程序的阻塞并传递该事件： - -- :cpp:enumerator:`USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND` — 表示自动挂起定时器已超时。 - -自动挂起定时器 -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -可使用 :cpp:func:`usb_host_lib_set_auto_suspend` 配置自动挂起定时器。每当 USB 主机库的客户端处理函数处理来自任意客户端的事件时，或当 USB 主机库本身在处理任何事件时，自动挂起定时器都会被重置。 - -自动挂起定时器会主动监测 USB 总线活动以及 USB 主机库的活动情况。具体如下： - -- 如果检测到 USB 流量（即发生任何传输或由客户端处理的事件），定时器会自动重置。 -- 如果检测到 USB 主机库的活动（即有新设备连接），定时器会自动重置。 -- 如果 USB 总线和 USB 主机库保持空闲（无流量、客户端事件或库事件），定时器继续倒计时。 -- 一旦定时器达到指定的超时时间（以毫秒为单位），将触发挂起。 - -这种机制确保 USB 主机仅在总线真正空闲时才进入挂起模式，避免在活跃通信期间出现意外挂起。 - -自动挂起定时器的重要注意事项： - -- 定时器可配置，即使未连接任何设备也会开始倒计时。 -- 所有设备断开连接后，定时器停止。 -- 设备连接或断开时，定时器自动重置。 -- 定时器超时后，只有在以下情况下才会派发 USB 主机库事件： - - - 当前有设备连接到根端口，并且 - - 根端口尚未处于挂起状态 - -自动挂起定时器可以配置为以下几种模式： - -- **单次** (:cpp:enumerator:`USB_HOST_LIB_AUTO_SUSPEND_ONE_SHOT`)：定时器超时一次后停止。 -- **周期性** (:cpp:enumerator:`USB_HOST_LIB_AUTO_SUSPEND_PERIODIC`)：定时器在每次超时后自动重启，无限重复。 - -由传输提交触发自动恢复 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -除了自动挂起定时器之外，USB 主机库还支持在传输提交（控制或非控制）时对已挂起的根端口进行自动恢复。通过此功能，开发人员只需调用传输 API（例如 :cpp:func:`usb_host_transfer_submit` 或 :cpp:func:`usb_host_transfer_submit_control`）即可发起恢复，无需显式调用 :cpp:func:`usb_host_lib_root_port_resume`。 - -当根端口处于挂起状态，且有客户端向已挂起的设备提交传输请求时，USB 主机库将执行以下流程： - -1. 自动向根端口发起恢复信号。 -2. 暂停处理该传输请求，直到恢复信号完成。 -3. 待总线进入活动（已恢复）状态后提交传输。 - -这一机制简化了客户端实现，避免了因手动触发恢复与提交传输并行进行而可能产生的竞态条件，确保恢复行为一致且安全。 - -.. note:: - - 仅在根端口处于挂起状态时，才能通过传输提交进行自动恢复。若根端口已处于活动状态，传输提交将照常进行。 - -下面的代码片段演示了如何使用自动挂起定时器和传输提交自动恢复功能，在挂起与恢复状态之间循环切换。 - -.. code-block:: c - - #include "usb/usb_host.h" - - static void client_task(void *arg) - { - while(true) { - // 向挂起的设备提交传输，以自动恢复设备 - // 借助自动挂起定时器，设备在无操作 1 秒后自动进入挂起模式 - usb_host_transfer_submit(xfer_out); - - // 切换上下文 10 秒。设备将在空闲约 1 秒后自动挂起 - vTaskDelay(pdMS_TO_TICKS(10000)); - } - } - - void usb_host_lib_task(void *arg) - { - ... - - // 将自动挂起定时器设置为周期模式，周期为 1 秒， - // 用于在无操作 1 秒后自动挂起设备，并在超时后自动重启 - usb_host_lib_set_auto_suspend(USB_HOST_LIB_AUTO_SUSPEND_PERIODIC, 1000); - - while (1) { - uint32_t event_flags; - usb_host_lib_handle_events(portMAX_DELAY, &event_flags); - - if (event_flags & USB_HOST_LIB_EVENT_FLAGS_AUTO_SUSPEND) { - // 自动挂起定时器超时，挂起根端口 - usb_host_lib_root_port_suspend(); - } - ... - } - ... - } - -.. note:: - - 关于挂起与恢复的更多细节，请参阅 `USB 2.0 规范 `_ > 第 11.9 章 *Suspend and Resume*。 - -.. ---------------------------------------------------- Examples ------------------------------------------------------- - -示例 --------- - -主机库示例 -^^^^^^^^^^^^^^^^^^^^^ - -:example:`peripherals/usb/host/usb_host_lib` 演示了如何使用 USB 主机库 API 来安装和注册客户端、等待设备连接、打印设备信息和处理断开连接，并重复这些步骤，直到退出应用程序。 - -Class 驱动程序示例 -^^^^^^^^^^^^^^^^^^^^^^^^ - -USB 主机栈提供了大量示例，展示了如何通过使用主机库 API 创建主机 Class 驱动程序。 - -CDC-ACM -""""""" - -* 通信设备 Class（抽象控制模型）的主机 Class 驱动程序通过 `乐鑫组件注册表 `__ 作为受管理的组件分发。 -* 示例 :example:`peripherals/usb/host/cdc` 演示了如何使用 CDC-ACM 主机驱动程序，让 {IDF_TARGET_NAME} 与 USB CDC-ACM 设备通信，包括 CP210x、FTDI FT23x 或 CH34x 等厂商设备。 -* 示例 `esp_modem `__ 中也使用了 CDC-ACM 驱动程序，该程序在这些示例中与蜂窝模块通信。 - -MSC -""" - -* 大容量存储 Class（仅支持批量传输）的主机 Class 驱动程序已部署到 `乐鑫组件注册表 `__。 -* 示例 :example:`peripherals/usb/host/msc` 演示了如何使用 USB 大容量存储类来访问、读取、写入和操作 USB 闪存驱动器，包括处理 USB 重新连接和反初始化 USB 主机堆栈。 - -HID -""" - -* HID（人机接口设备）的主机 class 驱动作为托管组件通过 `乐鑫组件注册表 `__ 分发。 -* 示例 :example:`peripherals/usb/host/hid` 演示了如何在 {IDF_TARGET_NAME} 上实现基本的 USB 主机 HID 类驱动，以便与 USB HID 设备（如键盘和鼠标）进行通信，并持续扫描设备的连接状态。一旦连接成功，即获取 HID 报告。 - -UVC -""" - -* USB 视频设备 Class 的主机 Class 驱动程序作为托管组件通过 `乐鑫组件注册表 `__ 分发。 -* 示例 :example:`peripherals/usb/host/uvc` 演示了如何使用 UVC 驱动程序从 USB 摄像头捕获视频帧。 - -.. ---------------------------------------------- USB Host Menuconfig -------------------------------------------------- - -.. only:: esp32s3 - - 外部 PHY 配置 - ------------- - - {IDF_TARGET_NAME} 内部集成了两个 USB 控制器 —— USB-OTG 和 USB-Serial-JTAG。这两个控制器 **共用同一个 PHY**，因此同一时间只能有一个控制器工作。如果在 USB-Serial-JTAG 工作时（如调试或烧录）时仍需使用 USB 主机功能，必须使用 **外部 PHY**，因为此时内部 PHY 已被 USB-Serial-JTAG 占用。 - - .. note:: - 使用外部 PHY 并不是在 USB 主机或设备功能开启时同时实现调试的唯一办法。也可以通过烧录对应的 eFuse，将调试接口从 USB-Serial-JTAG 切换为传统的 JTAG 接口。具体步骤请参考 ESP-IDF 编程指南中针对你的芯片的 `JTAG 调试 `_ 章节。 - - {IDF_TARGET_NAME} 支持连接外部 PHY 芯片，从而实现 USB-OTG 和 USB-Serial-JTAG 控制器的独立工作。不同的外部 PHY 芯片可能需要不同的硬件配置，具体请参阅各芯片的规格书。乐鑫官方文档提供了通用的连接示意图用于参考：`使用外部 PHY `__。 - - **已测试的外部 PHY 芯片如下：** - - - **SP5301** — {IDF_TARGET_NAME} 原生支持此芯片。原理图与布线方法请参考上文链接。 - - **TUSB1106** — {IDF_TARGET_NAME} 原生支持。可通过 GPIO 映射与外部 PHY 驱动配合使用。请遵循 TUSB1106 数据手册中的参考连接（供电方案以及在 D+/D– 上建议的串联电阻）。 - - **STUSB03E** — 需要通过模拟开关进行信号路由。请参考下方示例。 - - .. figure:: ../../../_static/usb_host/ext_phy_schematic_stusb03e.png - :align: center - :alt: 使用模拟开关的外部 PHY 原理图（主机模式） - - 使用 STUSB03E 与模拟开关的连接示例（主机模式） - - .. note:: - - 此原理图为简化示例，用于演示外部 PHY 连接方式，未包含完整 {IDF_TARGET_NAME} 设计所需的所有元器件和信号（如 VCC、GND、RESET 等）。 - - 图中包含 +5 V 电源轨（用于为 USB 设备供电）和 VCC 电源轨（通常为 3.3 V）。VCC 电压应与芯片供电电压保持一致。确保为 USB 总线提供的 +5 V 电源可靠，并具备必要的保护措施（如电源开关和限流设计）在支持 USB 总线供电设备时，务必遵守 USB 主机的供电规范。 - - 硬件配置通过将 GPIO 映射到 PHY 引脚实现。任何未使用的引脚（如 :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num`） **必须设置为 -1**。 - - .. note:: - - :cpp:member:`usb_phy_ext_io_conf_t::suspend_n_io_num` 引脚 **当前不支持**，无需连接。 - - **示例代码：** - - .. code-block:: c - - // 外部 PHY 的 GPIO 配置 - const usb_phy_ext_io_conf_t ext_io_conf = { - .vp_io_num = 8, - .vm_io_num = 5, - .rcv_io_num = 11, - .oen_io_num = 17, - .vpo_io_num = 4, - .vmo_io_num = 46, - .fs_edge_sel_io_num = 38, - .suspend_n_io_num = -1, - }; - - // 针对 OTG 控制器（Host 模式）的外部 PHY 配置与初始化 - const usb_phy_config_t phy_config = { - .controller = USB_PHY_CTRL_OTG, - .target = USB_PHY_TARGET_EXT, - .otg_mode = USB_OTG_MODE_HOST, - .otg_speed = USB_PHY_SPEED_FULL, - .ext_io_conf = &ext_io_conf - }; - - usb_phy_handle_t phy_hdl; - ESP_ERROR_CHECK(usb_new_phy(&phy_config, &phy_hdl)); - - // 配置 USB 主机使用外部初始化的 PHY - usb_host_config_t host_config = { - .skip_phy_setup = true, - // 根据需求添加其他 host 配置字段 - }; - ESP_ERROR_CHECK(usb_host_install(&host_config)); - - 该配置确保 USB 主机协议栈使用 **外部 PHY**，并跳过 PHY 初始化步骤。 - -主机栈配置 ----------- - -非兼容设备支持 -^^^^^^^^^^^^^^ - -为了支持某些非兼容或具有特定行为的 USB 设备，可以对 USB 主机栈进行配置。 - -USB 设备可能是热插拔的，因此必须配置电源开关和设备连接之间的延迟，以及设备内部电源稳定后的延迟。 - -枚举配置 -"""""""" - -在枚举已连接 USB 设备的过程中，需要给一些事件配置合适的间隔时间以确保设备正常运行。 - -.. figure:: ../../../_static/usb_host/poweron-timings.png - :align: center - :alt: USB 根集线器上电和连接事件时序 - - USB 根集线器上电和连接事件时序 - -上图展示了与连接设备时开启端口电源和热插拔设备相关的所有间隔时间。 - -* 端口复位或恢复运行后，USB 系统软件应提供 10 毫秒的恢复时间，此后连接到端口的设备才会响应数据传输。 -* 恢复时间结束后，如果设备收到 ``SetAddress()`` 请求，设备必须能够完成对该请求的处理，并能在 50 毫秒内成功完成请求的状态 (Status) 阶段。 -* 状态阶段结束后，设备允许有 2 毫秒的 ``SetAddress()`` 恢复时间。 - -.. note:: - - 有关连接事件时序的更多信息，请参阅 `通用串行总线 2.0 规范 `_ > 第 7.1.7.3 章 *连接和断开信令*。 - -可通过 Menuconfig 选项设置 USB 主机栈的可配置参数。 - -* `CONFIG_USB_HOST_DEBOUNCE_DELAY_MS` 用于配置防抖延迟。 -* `CONFIG_USB_HOST_RESET_HOLD_MS` 用于配置重置保持时间。 -* `CONFIG_USB_HOST_RESET_RECOVERY_MS` 用于配置重置恢复时间。 -* `CONFIG_USB_HOST_SET_ADDR_RECOVERY_MS` 用于配置 ``SetAddress()`` 恢复时间。 - -下游端口配置 -^^^^^^^^^^^^ - -当支持外部 Hub 功能时，可以为外部 Hub 端口配置多个参数。 - -每个外部 Hub 都有一个 Hub 描述符，用于描述设备特性。 - -.. note:: - - 有关 Hub 描述符的详细信息，请参考 `USB 2.0 规范 `_ > 章节 11.23.2.1 *Hub Descriptor*。 - -可以通过 Menuconfig 配置下游端口的可配置参数。 - -* 对于在端口上电后稳定电源的自定义值（PwrOn2PwrGood 值），请参阅 `CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_MS`。 -* 对于复位恢复间隔，请参阅 `CONFIG_USB_HOST_EXT_PORT_RESET_RECOVERY_DELAY_MS`。 - -.. note:: - - 规范规定，对于没有电源开关的 Hub，PwrOn2PwrGood 必须设置为零。同时，对于某些设备，可以增加此值以提供额外的上电时间。如需启用此功能，请参考 `CONFIG_USB_HOST_EXT_PORT_CUSTOM_POWER_ON_DELAY_ENABLE`。 - -主机通道 -""""""""""""" - -当启用外部 Hub 支持功能（`CONFIG_USB_HOST_HUBS_SUPPORTED`）时，主机通道的数量非常重要，因为每个下游设备都需要空闲通道。 - -每个连接的设备需要不同数量的通道，而所需通道数则取决于设备类别（EP 数量）。 - -对于 {IDF_TARGET_NAME}，支持的通道数量为 {IDF_TARGET_OTG_NUM_HOST_CHAN}。 - -.. note:: - - - 需要一个空闲通道来枚举设备。 - - 需要 1 到 N（N 为 EP 数量）个空闲通道来占用接口。 - - 如果所有的主机通道都已经被占用，则设备无法进行枚举，也无法获取接口。 - - -多项配置支持 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -对于具有多项配置的 USB 设备，可以在设备枚举过程中指定所需的配置编号。 - -枚举过滤器 -"""""""""""""""""" - -枚举过滤器是类型为 :cpp:type:`usb_host_enum_filter_cb_t` 的回调函数。从新连接的 USB 设备上读取设备描述符后，USB 主机栈会在枚举过程开始时调用枚举过滤器，从而为用户提供读取的设备描述符。借助此回调，用户得以： - -* 选择 USB 设备的配置。 -* 过滤应该进行枚举的 USB 设备。 - -在 menuconfig 中启用 `CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK` 选项即可启用枚举过滤器。可以通过设置 :cpp:member:`usb_host_config_t::enum_filter_cb` 来指定回调函数，该函数会在调用 :cpp:func:`usb_host_install` 时传递至主机库。 - -.. -------------------------------------------------- API Reference ---------------------------------------------------- - -API 参考 --------- - -USB 主机库的 API 包含以下头文件，但应用程序调用该 API 时只需 ``#include "usb/usb_host.h"``，就可以包含所有 USB 主机库的头文件。 - -- `usb/include/usb/usb_host.h` 包含 USB 主机库的函数和类型。 -- `usb/include/usb/usb_helpers.h` 包含与 USB 协议相关的各种辅助函数，如描述符解析等。 -- `usb/include/usb/usb_types_stack.h` 包含在 USB 主机栈的多个层次中使用的类型。 -- `usb/include/usb/usb_types_ch9.h` 包含了与 USB 2.0 规范中第 9 章相关的类型和宏，即描述符和标准请求。 -- `usb/include/usb/usb_types_ch11.h` 包含与 USB2.0 规范第 11 章相关的类型和宏，即集线器规范。 - -头文件 -^^^^^^^ - -- ``usb_host.h`` 可以通过以下方式包含： - -.. code:: c - - #include "usb/usb_host.h" - -- 该头文件是 ``usb`` 组件提供的 API 的一部分。``usb`` 组件通过 `乐鑫组件注册表 `__ 分发。因此，若要使用该组件，请通过以下命令将 Host Stack 组件添加为依赖项： - -.. code:: bash - - idf.py add-dependency usb - -.. ------------------------------------------------ Maintainers Notes -------------------------------------------------- - -维护注意事项 ------------------ - -.. note:: - - 有关 USB 主机栈内部实现的更多细节，请参阅 :doc:`/api-reference/peripherals/usb_host/usb_host_notes_index`。 - -.. toctree:: - :hidden: - :maxdepth: 0 - - usb_host/usb_host_notes_index +USB 主机文档已迁移到 `ESP-USB `_。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst deleted file mode 100644 index 34a16d47d0..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_arch.rst +++ /dev/null @@ -1,60 +0,0 @@ -USB 主机维护者注释（架构） -=========================== - -:link_to_translation:`en:[English]` - -主机协议栈大致分为多个抽象层，每个层代表不同的 USB 概念和不同级别的 USB 主机操作。例如，较高的层可能呈现为设备和应用数据传输的抽象，而较低的层则为端点和 USB 传输的抽象。 - -层描述 ------- - -从最低层（离用户最远的层）到最高层（离用户最近的层），主机协议栈的层描述如下表所示： - -.. list-table:: 主机协议栈的各层功能简述 - :widths: 20 10 70 - :header-rows: 1 - - * - 层 - - 文件 - - 描述 - * - 主机控制器 (DWC_OTG) - - N/A - - 此层代表 {IDF_TARGET_NAME} 的 USB 控制器硬件，所提供的 API 是控制器的寄存器接口。 - * - LL - - ``usbh_ll.h`` - - LL（低级）层根据 ESP-IDF 的 :doc:`硬件抽象 API 指南 <../../../api-guides/hardware-abstraction>` 抽象了 USB 控制器的基本寄存器访问。换句话说，此层提供的 API 能访问控制寄存器，也可以格式化/解析控制器的 DMA 描述符。 - * - HAL - - ``usbh_hal.h``， ``usbh_hal.c`` - - HAL（硬件抽象层）根据 ESP-IDF 的 :doc:`硬件抽象 API 指南 <../../../api-guides/hardware-abstraction>`，将 USB 控制器的操作步骤抽象成函数。此层还将控制器的主机端口和主机通道抽象化，并提供操作它们的 API。 - * - HCD - - ``hcd.h``， ``hcd.c`` - - HCD（主机控制器驱动程序）是一个与硬件无关的 API，适用于任何 USB 控制器（理论上，此 API 可以与任何 USB 控制器实现一同使用）。此层还抽象了根端口（根集线器）和 USB 管道。 - * - USBH 和集线器驱动程序 - - ``usbh.h``， ``usbh.c`` - - USBH（USB 主机驱动程序）层等效于 USB2.0 规范第 10 章中描述的 USBD 层。USBH 提供 USB 设备的抽象，在内部管理已连接设备的列表（即，设备池），还仲裁客户端之间的设备共享（即，跟踪正在使用的端点并提供一个共享端点 0）。 - * - 集线器驱动程序 - - ``hub.h``， ``hub.c`` - - 集线器驱动程序层是 USBH 的特殊客户端，负责处理设备的连接/断开，并通知 USBH 此类事件。对于设备的连接，集线器驱动程序还会处理枚举过程。 - * - USB 主机库 - - ``usb_host.h``， ``usb_host.c`` - - USB 主机库层是主机协议栈的最低公共 API 层，并呈现 USB 主机客户端的概念。客户端的抽象允许多个 class 驱动程序同时存在（其中每个类大致映射到一个单独的客户端），这也是一种分工机制（其中每个客户端负责各自的处理以及事件处理）。 - * - 主机 Class 驱动程序 - - 请参阅 `ESP-USB 存储库 `_ 或是 ESP-IDF 中的 USB 主机示例 :example:`peripherals/usb/host`。 - - 主机 Class 驱动程序能实现特定设备类（例如，CDC、MSC、HID）的主机端。每个 class 驱动程序具有特定的公开 API 接口。 - -层依赖关系 ----------- - -主机协议栈大致遵循自顶向下的层次结构，具有层间依赖关系。假设存在层 A（最高层）、B 、 C（最低层），则主机协议栈具有以下层间依赖规则： - -- 特定层可以使用其直接下层的 API（层 A 可以使用层 B 的 API）。 -- 特定层可以使用其间接下层的 API（层 A 可以使用层 C 的 API），即可以隔层调用。 -- 特定层不能使用其任何上层的 API（层 C 无法使用层 A/B 的 API）。 - -.. note:: - - 允许跳过层次以避免在多个层次之间重复相同的抽象。例如，管道的抽象都位于 HCD 层，但被上面的多个层使用。 - -.. todo:: - - 添加图示以说明不同层之间的 API 依赖关系 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_design.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_design.rst deleted file mode 100644 index 5a1f7314e7..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_design.rst +++ /dev/null @@ -1,144 +0,0 @@ -USB 主机维护者注意事项（设计指南） -===================================== - -:link_to_translation:`en:[English]` - -设计考虑 --------- - -设计主机协议栈时应考虑以下要点： - -**硬件资源有限：** - -与较大的主机系统相比，嵌入式主机协议栈的硬件资源（如内存和处理能力）有限。 - -**USB 2.0 第 10 章：** - -USB 2.0 规范的第 10 章中规定了 USB 主机系统的某些要求，特别是 USB 主机系统软件所需的必要层次。 - -**用例复杂性广泛：** - -嵌入式主机协议栈用例广泛，包含不同的复杂性。一些 USB 主机应用只支持单个厂商的特定设备，而其他应用则需要支持不同类别的各种设备。 - -要求 ----- - -考虑到以上设计要素，在设计主机协议栈时满足了以下要求： - -支持 DMA -^^^^^^^^^^ - -**要求：主机协议栈必须支持 DMA。** - -为降低 CPU 负载，主机协议栈必须支持 DMA。通过 DMA，无需 CPU 干预，即可自动复制 USB 传输数据到主机控制器中，以及自动从主机控制器中复制 USB 传输数据。这一点对于嵌入式 CPU（即，较低的 CPU 频率）和较大的最大 USB 传输数据负载（例如，同步传输的 1023 字节）来说尤为重要。 - -减少内存拷贝 -^^^^^^^^^^^^ - -**要求：在不同层之间传递数据时主机协议栈应尽量减少内存拷贝次数。** - -各种数据和对象（例如 USB 传输）需要在主机协议栈的多个层之间传递。主机协议栈应一次性为数据或对象分配内存，并在各层之间传递指向该数据或对象的指针，从而减少各层间的内存拷贝次数。因此，主机协议栈需要能够在不同层之间共享的标准化数据类型（参见 USB 2.0 规范的第 10.3.4 节）。 - -支持事件驱动 -^^^^^^^^^^^^ - -**要求：主机协议栈必须支持事件驱动（即，主机协议栈的 API 不是轮询的方式）。** - -主机协议栈应支持 CPU 密集型应用场景，例如视频流传输（即，UVC Class）。因此，主机协议栈应支持事件驱动操作，减少 CPU 占用，从而将大部分 CPU 时间留给应用本身（如，视频编码或解码）。 - -主机协议栈需要通过中断、回调和 FreeRTOS 同步原语（例如队列和信号量）在各层之间传递事件。 - -不得创建任务 -^^^^^^^^^^^^ - -**要求：主机库层及其下层的所有主机协议栈层都不得创建任何任务。** - -任务栈通常是 ESP-IDF 应用程序中最占内存的部分之一。由于应用场景广泛，创建的任务数量（以及任务的栈大小）差别可能很大。例如： - -- 需要低延迟或高吞吐量（例如同步传输）的应用可能会创建一个专门的任务来处理传输数据，确保延迟最小化。 -- 对延迟要求不高（例如批量传输）的应用可能会通过共享任务来处理传输数据，以节省内存。 - -因此，主机库层及其下层的所有主机协议栈层都不得创建任何任务，而应公开处理函数，供上层创建的任务调用。任务创建将委托给 Class 驱动程序或应用程序层。 - -可在不同层操作 -^^^^^^^^^^^^^^ - -主机协议栈用例广泛，情况复杂，应确保其可在不同层操作。因此无论是在较低层（例如 HCD 或 HAL），还是在较高层（例如 Class 驱动程序），用户都可以使用主机协议栈。 - -用户可以在不同的层上使用主机协议栈，并根据应用程序的特点，权衡便利性、可控性和优化度，例如： - -- 支持专用定制设备的主机协议栈应用可能会使用较低级别的抽象，从而调用优化度高、可控性强、简单便利的 API。 -- 支持各种设备 Class 的主机协议栈应用需要使用完整的主机协议栈，以便自动处理设备枚举。 - -编码约定 --------- - -主机协议栈遵循下列编码规范，以提高代码可读性与可维护性： - -符号应使用层名作为前缀 -^^^^^^^^^^^^^^^^^^^^^^ - -主机协议栈每层公开的符号（即函数、类型、宏）必须以该层的名称作为前缀。例如，HCD 层公开的符号将以 ``hcd_...`` 或 ``HCD_...`` 为前缀。 - -但内部符号（例如静态函数）**不应** 以其所在层的名称作为前缀，以便修改该层源代码时能更好地区分内部和外部符号。 - -临界区函数应以 ``_`` 为前缀 -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -主机协议栈的每层中都有各种必须在临界区内调用的静态函数。这些函数的名称以 ``_`` 为前缀（例如，``_func_called_from_crit()``），以便维护者更好地区分哪些函数应该从临界区内调用。例如： - -.. code-block:: c - - some_func(); // 从临界区外调用 - taskENTER_CRITICAL(&some_lock); - _some_func_crit(); // 从临界区内调用。使用 _ 前缀，使其便于区分 - taskEXIT_CRITICAL(&some_lock); - -根据锁机制对结构体成员进行分组 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -主机协议栈的某些层使用多种锁机制（例如临界区和任务互斥锁）来确保线程安全。每种锁机制能提供不同级别的保护，而同一对象的成员变量受不同锁机制保护。因此，为了清晰地区分不同的锁机制及其相关变量，结构体成员按锁机制被分组为嵌套结构体。 - -.. list-table:: 锁机制 - :widths: 20 10 80 - :header-rows: 1 - - * - 锁机制 - - 嵌套结构体 - - 描述 - * - 临界区 - - ``dynamic`` - - 从任务上下文和 ISR 上下文访问的共享数据受临界区保护。 - * - 任务互斥锁 - - ``mux_protected`` - - 仅从任务上下文访问的共享数据受 FreeRTOS 互斥锁保护。 - * - 单线程 - - ``single_thread`` - - 只由同一任务访问的数据无需锁保护。 - * - 常量 - - ``constant`` - - 在对象实例化时设置常量数据，之后常量将不再改变。因此，只要变量不被写入，任何任务或 ISR 都可以自由访问常量数据。 - -根据锁机制对结构体成员进行分组，能清晰地显示访问特定成员变量时需要哪种锁机制，使得代码易于维护，如下所示： - -.. code-block:: c - - typedef struct some_obj some_obj_t; - - some_obj_t obj; - - // 访问动态成员需要临界区 - taskENTER_CRITICAL(&some_lock); - obj.dynamic.varA = 1; - taskEXIT_CRITICAL(&some_lock); - - // 访问受互斥锁保护的成员需要获取互斥锁 - xSemaphoreTake(&some_mux, portMAX_DELAY); - obj.mux_protected.varB = 1; - xSemaphoreGive(&some_mux); - - // 只由某一任务访问的单线程成员数据无需锁保护 - obj.single_thread.varC = 1; - - // 访问常量成员无需锁保护，但此种访问为只读 - int local_var = obj.constant.varD; diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst deleted file mode 100644 index 63d2b3d272..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_dwc_otg.rst +++ /dev/null @@ -1,224 +0,0 @@ -USB 主机维护者注意事项（DWC_OTG 控制器） -========================================= - -:link_to_translation:`en:[English]` - -{IDF_TARGET_NAME} 使用 DesignWare USB 2.0 On-the-Go 控制器（后文简称为 DWC_OTG）作为其底层硬件控制器。启用分散/聚集式 DMA 功能后，DWC_OTG 将以主机模式运行。 - -.. note:: - - 本节高度概括了 DWC_OTG 在主机模式下的操作。有关 DWC_OTG 的详细信息，请参阅 DWC_OTG 技术规格书和编程指南。 - -主机模式操作模型 ----------------- - -下图展示了 DWC_OTG 在主机模式下的简化操作模型。该图包含了 DWC_OTG 主机模式下的一些关键概念及术语。 - -.. figure:: ../../../../_static/usb_host/dwc-otg-operation.png - :align: center - :alt: DWC_OTG 主机模式操作模型 - :figclass: align-center - -.. note:: - - 详情请参阅技术规格书第 2.1.4 节（主机架构）。 - -主机端口 -^^^^^^^^^ - -主机端口指的是 DWC_OTG 提供的单个 USB 端口（在 USB 术语中，也被视为总线根集线器的单个 USB 端口）。主机端口通常只能连接一个设备，但可以通过集线器连接更多设备。 - -主机端口具有以下功能： - -- 检测直连设备的连接/断开情况。 -- 检测直连设备的速度。 -- 发送各种总线信号（如挂起、恢复、复位）。 - -主机通道 -^^^^^^^^ - -在主机模式下，DWC_OTG 使用通道与设备端点通信，每个通道会映射到特定的端点（在 USB 术语中，通道是管道的硬件表示）。例如，有个通道将映射到 EP 1 OUT。每个通道都有一组控制和状态寄存器 (CSR)，可以进行独立配置和控制，主要用于： - -- 指定通道目标端点的详细信息（例如，设备地址、端点编号、传输类型、通道方向）。 -- 启动通道传输（如设置 DMA 描述符）。 - -使用分散/聚集式 DMA 功能时，主机通道上的传输完全由事件驱动，用户只需填写恰当的 DMA 描述符，填充通道的 CSR，然后启用通道即可。传输完成后，通道将生成中断。 - -数据 FIFO -^^^^^^^^^^ - -主机模式下，DWC_OTG 使用多个 FIFO 作为 USB 传输数据负载的暂存区。使用 DMA 时，DMA 引擎将在 TX/RX FIFO 和 {IDF_TARGET_NAME} 的内部存储器之间复制数据： - -- 对于 OUT 传输，数据负载将由 DMA 从主内存复制到某个 TX FIFO 中。MAC 层将按照 USB 数据包格式传输该数据负载。 -- 对于 IN 传输，MAC 层会解析接收到的 USB 数据包，并将接收的数据负载存储在 RX FIFO 中。之后，由 DMA 将数据复制到主内存中。 - -目标 FIFO 由通道的方向和传输类型决定： - -- 所有 IN 通道数据进入 RX FIFO。 -- 所有非周期性（即控制和批量）OUT 通道数据进入非周期性 TX (NPTX) FIFO。 -- 所有周期性（即中断和同步）OUT 通道数据进入周期性 TX (PTX) FIFO。 - -.. note:: - - 非周期性和周期性 OUT 通道数据应分别进入 NPTX 和 PTX FIFO，因为中断和同步端点具有周期性特性（由端点的 ``bInterval`` 值指定）。DWC_OTG 会自动调度周期性传输，因此 PTX FIFO 能单独暂存这些周期性传输。 - -DMA 引擎 -^^^^^^^^ - -DMA 引擎负责在 FIFO 和主内存之间复制数据。启用主机模式分散/聚集式 DMA 功能，无需软件干预，特定通道即可自动执行多个传输。下图展示了 DWC_OTG 主机模式分散/聚集式 DMA 内存结构。 - -.. figure:: ../../../../_static/usb_host/dwc-otg-scatter-gather.png - :align: center - :alt: DWC_OTG 主机模式分散/聚集式 DMA 内存结构 - :figclass: align-center - -- USB 传输由队列传输描述符 (QTD) 描述。每个 QTD 包含： - - - 一个 32 位的 buffer 状态四元组，用来指定有关传输的详细信息，且会在传输完成后报告传输状态。buffer 状态四元组可以指定 QTD 在传输完成后生成中断或是停止通道，也指定上述两种情况同时发生。 - - 一个 32 位指针，指向一个包含 OUT 传输数据负载的 buffer，或是指向一个空的 buffer，这个空 buffer 将用来存储 IN 传输的数据负载。 - -- 每个 QTD 的数据负载可以大于其目标端点的最大数据包大小 (MPS)。DWC_OTG 能够自动拆分传输。 -- 多个 QTD 可以放入一个 QTD 列表中。通道将自动执行列表中的每个 QTD，并可设置是否要循环执行。 -- 在通道开始传输数据之前，会为其配置 QTD 列表（以及 QTD 列表长度）。一旦启用通道，DWC_OTG 将自动开始 USB 传输。 -- 在特定 QTD 或整个 QTD 列表结束任务后，通道将生成中断（可配置）。 - -.. note:: - - 详情请参阅编程指南第 6.2.1 节（描述符内存结构）。 - -硬件配置 --------- - -DWC_OTG IP 是可配置的。有关 {IDF_TARGET_NAME} 的 DWC_OTG 的重要主机配置，请参阅下表： - -.. only:: esp32p4 - - .. list-table:: {IDF_TARGET_NAME} 的 DWC_OTG 配置 - :widths: 70 30 - :header-rows: 1 - - * - 描述 - - 配置 - * - 支持 OTG 的主机和设备模式 - - ``OTG_MODE = 0`` - * - 支持高速 (HS)、全速 (FS) 和低速 (LS) - - ``OTG_FSPHY_INTERFACE = 2``、``OTG_HSPHY_INTERFACE = 3`` - * - 支持分散/聚集式 DMA 功能的内部 DMA 控制器 - - ``OTG_ARCHITECTURE = 2``、 ``OTG_EN_DESC_DMA = 1`` - * - 不支持分割传输 - - ``OTG_SINGLE_POINT = 1`` - * - 16 个主机模式通道 - - ``OTG_NUM_HOST_CHAN = 16`` - * - 支持包括 ISOC 和 INTR OUT 传输在内的所有传输类型 - - ``OTG_EN_PERIO_HOST = 1`` - * - 动态大小的 4096 字节（1024 行）数据 FIFO - - ``OTG_DFIFO_DYNAMIC = 1``、``OTG_DFIFO_DEPTH = 1024`` - * - 每个微帧仅支持 4 个周期性和 4 个非周期性事务 - - ``OTG_NPERIO_TX_QUEUE_DEPTH = 4``、``OTG_PERIO_TX_QUEUE_DEPTH = 4`` - -.. only:: esp32s2 or esp32s3 or esp32h4 - - .. list-table:: {IDF_TARGET_NAME} 的 DWC_OTG 配置 - :widths: 70 30 - :header-rows: 1 - - * - 描述 - - 配置 - * - 支持 OTG 的主机和设备模式 - - ``OTG_MODE = 0`` - * - 支持全速 (FS) 和低速 (LS) - - ``OTG_FSPHY_INTERFACE = 1``、``OTG_HSPHY_INTERFACE = 0`` - * - 支持分散/聚集式 DMA 功能的内部 DMA 控制器 - - ``OTG_ARCHITECTURE = 2``、 ``OTG_EN_DESC_DMA = 1`` - * - 8 个主机模式通道 - - ``OTG_NUM_HOST_CHAN = 8`` - * - 支持包括 ISOC 和 INTR OUT 传输在内的所有传输类型 - - ``OTG_EN_PERIO_HOST = 1`` - * - 动态大小的 1024 字节（256 行）数据 FIFO - - ``OTG_DFIFO_DYNAMIC = 1``, ``OTG_DFIFO_DEPTH = 256`` - -分散/聚集式 DMA 传输 ---------------------- - -主机通道传输的基本操作步骤如下： - -#. 准备好数据 buffer、QTD 及 QTD 列表，确保有 QTD 能在完成任务后停止通道并生成中断。 -#. 通过 CSR 设置通道和端点的特性（如 EP 地址、传输类型、EP MPS 等）。 -#. 设置有关通道 QTD 列表的 CSR（如 QTD 列表指针和 QTD 列表长度）及通道中断 CSR。 -#. 启用通道。硬件将使用 DMA 自动处理传输。 -#. 在发生通道事件（如 QTD 完成任务或通道报错）时，通道将生成中断。 -#. 解析通道中断，确定通道事件类型。 -#. 解析 QTD，确定每个单独传输的结果。 - -若传输类型不同，在通道操作和 QTD 列表使用上也会有一些细微差别。 - -批量传输 -^^^^^^^^ - -批量传输最为简单。每个 QTD 代表特定方向的批量传输，DWC_OTG 会自动将特定 QTD 拆分为多个 MPS 大小的传输。因此，可以用多次批量传输填充一个 QTD 列表，并自动执行整个列表（即，只在最后一个 QTD 完成任务时发送中断）。 - -控制传输 -^^^^^^^^ - -控制传输是双向的，因而较为复杂（即，每个控制传输阶段可以有不同的方向）。每个阶段需要一个单独的 QTD，并且每个 QTD 必须在完成任务后停止传输通道，从而确保能通过重新配置通道的 CSR 来改变通道的方向。通常来说，控制传输需要 3 个 QTD（每个阶段一个）。 - -中断传输 -^^^^^^^^ - -根据 USB 2.0 规范，中断传输在端点指定的服务周期（即 ``bInterval``）执行传输事务。特定中断端点在一个服务周期内不得执行多次中断传输。服务周期由微帧或帧的数量指定，因此特定中断端点通常每隔 N 个微帧或帧执行一次传输，直至完成传输。特定中断通道的服务周期（即 ``bInterval``）由主机帧列表指定（详见编程指南第 6.5 节）。 - -.. note:: - - HS USB 允许一个中断端点在一个微帧内执行三次中断传输。详情请参阅 USB 2.0 规范第 5.7.3 节（中断传输数据包大小限制）。 - -总的来说，主机模式分散/聚集式 DMA 中的中断传输具有以下特点： - -- 如果 QTD 数据负载大于端点的 MPS，通道会自动将传输拆分为多个 MPS 大小的传输事务（类似于批量传输）。但每次传输将在端点指定的服务周期内执行（即每个 ``bInterval`` 时间段内执行一次传输），直至完成传输。 -- 对于中断 IN 传输，若收到短包（即传输的数据负载小于 MPS），则表明端点已无需要发送的数据，此时： - - - 即便 QTD 未设置 IOC（完成时中断）位，通道也会生成额外的通道中断。 - - 即使生成了额外的通道中断，通道也不会停止。 - - 软件必须使用这个额外的中断手动停止中断通道，从而取消 QTD 列表中剩余的 QTD。 - - -.. note:: - - 基于上述中断传输的特点，对于软件来说，为每次传输分配一个 QTD 可能比为整个传输分配一个 QTD 更加容易。 - -同步传输 -^^^^^^^^ - -根据 USB 2.0 规范，同步传输在端点指定的服务周期（即 ``bInterval``）执行传输事务，以实现恒定的数据传输速率。特定同步端点在一个服务周期内不得执行多次中断传输。服务周期由微帧或帧的数量指定，因此特定同步端点通常每隔 N 个微帧或帧执行一次传输，直至完成传输。特定同步通道的服务周期（即 ``bInterval``）由主机帧列表指定（详见编程指南第 6.5 节）。 - -但与中断传输不同，由于同步传输需要保持恒定的数据传输速率，即便传输失败（或收到 NAK），同步传输也不会重试， - -.. note:: - - HS USB 允许一个同步端点在一个微帧内执行三次同步传输。详情请参阅 USB 2.0 规范第 5.6.3 节（同步传输数据包大小限制）。 - -总的来说，主机模式分散/聚集式 DMA 中的同步传输具有以下特点： - -- 必须为每微帧或帧分配一个 QTD，但非服务周期的 QTD 应保持空白（即，如果通道的服务周期是每 N 个微帧或帧，则只需填充每第 N 个 QTD）。 -- **每个已填充的 QTD 只能代表一次传输事务，而非整个传输过程**。 -- 同步传输不会在失败时重试，因此必须检查每个完成任务的 QTD 的状态。 - -补充说明 --------- - -某些 DWC_OTG 行为在技术规格书或编程指南中均未提及。本节解释了一些与主机协议栈的实现相关的行为。 - -端口错误不会触发通道中断 -^^^^^^^^^^^^^^^^^^^^^^^^ - -一个或多个通道运行时，若发生端口错误（例如突然断连或端口过流），则： - -- 通道仍可运行（即，保持设置 ``HCCHAR.ChEna``）且不会生成通道中断。 -- 理论上可以通过设置 ``HCCHAR.ChDis`` 来禁用通道，但这对同步通道无效，因为通道禁用中断未能生成。 - -因此，发生端口错误时，应使用控制器软复位以确保禁用所有通道。 - -端口复位中断 -^^^^^^^^^^^^ - -- DWC_OTG 在其端口上发出复位信号，如果设备在此期间断开连接，则断连中断（即 ``HPRT.PrtConnDet``）不会在取消复位前生成。 -- 在复位已经启用的端口（即 ``HPRT.PrtEna``）时，如枚举期间的二次复位或是设备运行期间的复位，无论是在复位信号生效还是失效时，都会生成端口启用/禁用更改中断（即 ``HPRT.PrtEnChng``）。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst deleted file mode 100644 index a1a7a8a98d..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_enum.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. Translation not required: According to the USB developers, all of the ``usb_host_notes_*`` files are just internal notes for ESP-IDF developers, not for our end users. So we don't need to translate them at all. - -.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_enum.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst deleted file mode 100644 index e8bab47973..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_ext_hub.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst deleted file mode 100644 index 6833910aa4..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_ext_port.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst deleted file mode 100644 index 09d410debf..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_index.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_index.rst diff --git a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst b/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst deleted file mode 100644 index 7a7bb4d796..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst +++ /dev/null @@ -1,3 +0,0 @@ -.. Translation not required: According to the USB developers, all of the ``usb_host_notes_*`` files are just internal notes for ESP-IDF developers, not for our end users. So we don't need to translate them at all. - -.. include:: ../../../../en/api-reference/peripherals/usb_host/usb_host_notes_usbh.rst From c30851292fdf6e85514afe2f12c1f92c049e4e0c Mon Sep 17 00:00:00 2001 From: "igor.masar" Date: Mon, 2 Mar 2026 23:20:19 +0100 Subject: [PATCH 2/2] docs(usb): Update links and example checks Replace the peripherals index USB entries with direct links to ESP-USB so the generated pages are no longer redirect-only stubs. Keep legacy USB URLs working via redirects, including the individual USB host maintainer notes pages. Remove the obsolete placeholder documents and stale CODEOWNERS pattern. Mark the moved USB examples as KNOWN_MISSING in the example documentation checker until it can also read the ESP-USB guide. --- .gitlab/CODEOWNERS | 1 - docs/conf_common.py | 13 +++++-------- docs/docs_not_updated/esp32c61.txt | 2 -- docs/docs_not_updated/esp32h21.txt | 2 -- docs/en/api-reference/peripherals/index.rst | 4 ++-- docs/en/api-reference/peripherals/usb_device.rst | 6 ------ docs/en/api-reference/peripherals/usb_host.rst | 6 ------ docs/page_redirects.txt | 14 +++++++++++--- docs/zh_CN/api-reference/peripherals/index.rst | 4 ++-- .../zh_CN/api-reference/peripherals/usb_device.rst | 6 ------ docs/zh_CN/api-reference/peripherals/usb_host.rst | 6 ------ tools/ci/check_examples_documented.py | 13 +++++++++++++ 12 files changed, 33 insertions(+), 44 deletions(-) delete mode 100644 docs/en/api-reference/peripherals/usb_device.rst delete mode 100644 docs/en/api-reference/peripherals/usb_host.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_device.rst delete mode 100644 docs/zh_CN/api-reference/peripherals/usb_host.rst diff --git a/.gitlab/CODEOWNERS b/.gitlab/CODEOWNERS index eba6b025a3..667d0d9f2d 100644 --- a/.gitlab/CODEOWNERS +++ b/.gitlab/CODEOWNERS @@ -177,7 +177,6 @@ /docs/**/api-reference/bluetooth/ @esp-idf-codeowners/bluetooth /docs/**/api-reference/network/ @esp-idf-codeowners/network @esp-idf-codeowners/wifi /docs/**/api-reference/peripherals/ @esp-idf-codeowners/peripherals -/docs/**/api-reference/peripherals/usb* @esp-idf-codeowners/peripherals @esp-idf-codeowners/peripherals/usb /docs/**/api-reference/protocols/ @esp-idf-codeowners/network @esp-idf-codeowners/app-utilities /docs/**/api-reference/provisioning/ @esp-idf-codeowners/app-utilities/provisioning /docs/**/api-reference/storage/ @esp-idf-codeowners/storage diff --git a/docs/conf_common.py b/docs/conf_common.py index 5c3db11c42..81e26364dd 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -154,11 +154,6 @@ TOUCH_SENSOR_DOCS = ['api-reference/peripherals/cap_touch_sens.rst'] SPIRAM_DOCS = ['api-guides/external-ram.rst'] -USB_DOCS = [ - 'api-reference/peripherals/usb_device.rst', - 'api-reference/peripherals/usb_host.rst', -] - I80_LCD_DOCS = ['api-reference/peripherals/lcd/i80_lcd.rst'] RGB_LCD_DOCS = ['api-reference/peripherals/lcd/rgb_lcd.rst'] DSI_LCD_DOCS = ['api-reference/peripherals/lcd/dsi_lcd.rst'] @@ -351,7 +346,6 @@ conditional_include_dict = { 'SOC_SDMMC_HOST_SUPPORTED': SDMMC_DOCS, 'SOC_SDIO_SLAVE_SUPPORTED': SDIO_SLAVE_DOCS, 'SOC_MCPWM_SUPPORTED': MCPWM_DOCS, - 'SOC_USB_OTG_SUPPORTED': USB_DOCS, 'SOC_USB_SERIAL_JTAG_SUPPORTED': USB_SERIAL_JTAG_DOCS, 'SOC_DEDICATED_GPIO_SUPPORTED': DEDIC_GPIO_DOCS, 'SOC_LCD_I80_SUPPORTED': I80_LCD_DOCS, @@ -501,9 +495,10 @@ QEMU_TARGETS = ['esp32', 'esp32c3', 'esp32s3'] ESP_TEE_TARGETS = ['esp32c6', 'esp32h2', 'esp32c5', 'esp32c61'] -def _resolve_redirect_page_macros(redirect_pages, target): +def _resolve_redirect_page_macros(redirect_pages, target, language): replace_map = { '{IDF_TARGET_PATH_NAME}': target, + '{IDF_DOCS_LANGUAGE}': language, } resolved_redirect_pages = [] @@ -537,7 +532,9 @@ def conf_setup(app, config): # Not for all target pass - config.html_redirect_pages = _resolve_redirect_page_macros(config.html_redirect_pages, config.idf_target) + config.html_redirect_pages = _resolve_redirect_page_macros( + config.html_redirect_pages, config.idf_target, config.language + ) config.html_baseurl = f'https://docs.espressif.com/projects/esp-idf/{config.language}/stable/{config.idf_target}' diff --git a/docs/docs_not_updated/esp32c61.txt b/docs/docs_not_updated/esp32c61.txt index 9d68d04582..65356a1993 100644 --- a/docs/docs_not_updated/esp32c61.txt +++ b/docs/docs_not_updated/esp32c61.txt @@ -22,8 +22,6 @@ api-reference/storage/mass_mfg.rst api-reference/storage/fatfsgen.rst api-reference/storage/index.rst api-reference/storage/nvs_partition_parse.rst -api-reference/peripherals/usb_host.rst -api-reference/peripherals/usb_device.rst api-reference/peripherals/sd_pullup_requirements.rst api-reference/network/esp_eth.rst api-reference/network/esp_netif_driver.rst diff --git a/docs/docs_not_updated/esp32h21.txt b/docs/docs_not_updated/esp32h21.txt index 32ae626f73..884fe94591 100644 --- a/docs/docs_not_updated/esp32h21.txt +++ b/docs/docs_not_updated/esp32h21.txt @@ -105,8 +105,6 @@ api-reference/peripherals/cap_touch_sens.rst api-reference/peripherals/index.rst api-reference/peripherals/sdio_slave.rst api-reference/peripherals/temp_sensor.rst -api-reference/peripherals/usb_device.rst -api-reference/peripherals/usb_host.rst api-reference/peripherals/camera_driver.rst api-reference/peripherals/adc_oneshot.rst api-reference/peripherals/sdspi_share.rst diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index d58f00bb6e..bcdb1e0a26 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -49,7 +49,7 @@ Peripherals API :SOC_TOUCH_SENSOR_SUPPORTED: cap_touch_sens :SOC_TWAI_SUPPORTED: twai uart - :SOC_USB_OTG_SUPPORTED: usb_device - :SOC_USB_OTG_SUPPORTED: usb_host + :SOC_USB_OTG_SUPPORTED: USB Device Stack + :SOC_USB_OTG_SUPPORTED: USB Host Code examples for this API section are provided in the :example:`peripherals` directory of ESP-IDF examples. diff --git a/docs/en/api-reference/peripherals/usb_device.rst b/docs/en/api-reference/peripherals/usb_device.rst deleted file mode 100644 index 422483ec38..0000000000 --- a/docs/en/api-reference/peripherals/usb_device.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB Device Stack -================ - -:link_to_translation:`zh_CN:[中文]` - -USB Device documentation has moved to `ESP-USB `_. diff --git a/docs/en/api-reference/peripherals/usb_host.rst b/docs/en/api-reference/peripherals/usb_host.rst deleted file mode 100644 index bcd6e6d4e5..0000000000 --- a/docs/en/api-reference/peripherals/usb_host.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB Host -======== - -:link_to_translation:`zh_CN:[中文]` - -USB Host documentation has moved to `ESP-USB `_. diff --git a/docs/page_redirects.txt b/docs/page_redirects.txt index 8c043176fa..13b346d93e 100644 --- a/docs/page_redirects.txt +++ b/docs/page_redirects.txt @@ -16,9 +16,17 @@ api-reference/ethernet/esp_eth api-reference/network/esp_eth api-reference/mesh/index api-reference/network/index api-reference/mesh/esp_mesh api-reference/network/esp_mesh api-reference/peripherals/can api-reference/peripherals/twai -api-reference/peripherals/usb api-reference/peripherals/usb_device -api-reference/peripherals/usb_device "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" -api-reference/peripherals/usb_host "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host.html" +api-reference/peripherals/usb "https://docs.espressif.com/projects/esp-usb/{IDF_DOCS_LANGUAGE}/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" +api-reference/peripherals/usb_device "https://docs.espressif.com/projects/esp-usb/{IDF_DOCS_LANGUAGE}/latest/{IDF_TARGET_PATH_NAME}/usb_device.html" +api-reference/peripherals/usb_host "https://docs.espressif.com/projects/esp-usb/{IDF_DOCS_LANGUAGE}/latest/{IDF_TARGET_PATH_NAME}/usb_host.html" +api-reference/peripherals/usb_host/usb_host_notes_index "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_index.html" +api-reference/peripherals/usb_host/usb_host_notes_arch "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_arch.html" +api-reference/peripherals/usb_host/usb_host_notes_design "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_design.html" +api-reference/peripherals/usb_host/usb_host_notes_dwc_otg "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_dwc_otg.html" +api-reference/peripherals/usb_host/usb_host_notes_usbh "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_usbh.html" +api-reference/peripherals/usb_host/usb_host_notes_enum "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_enum.html" +api-reference/peripherals/usb_host/usb_host_notes_ext_hub "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_ext_hub.html" +api-reference/peripherals/usb_host/usb_host_notes_ext_port "https://docs.espressif.com/projects/esp-usb/en/latest/{IDF_TARGET_PATH_NAME}/usb_host/usb_host_notes_ext_port.html" api-reference/wifi/index api-reference/network/index api-reference/wifi/esp_now api-reference/network/esp_now api-reference/wifi/esp_smartconfig api-reference/network/esp_smartconfig diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 8b66cc9869..c33ced5c04 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -49,7 +49,7 @@ :SOC_TOUCH_SENSOR_SUPPORTED: cap_touch_sens :SOC_TWAI_SUPPORTED: twai uart - :SOC_USB_OTG_SUPPORTED: usb_device - :SOC_USB_OTG_SUPPORTED: usb_host + :SOC_USB_OTG_SUPPORTED: USB 设备栈 + :SOC_USB_OTG_SUPPORTED: USB 主机 本部分的 API 示例代码存放在 ESP-IDF 示例项目的 :example:`peripherals` 目录下。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_device.rst b/docs/zh_CN/api-reference/peripherals/usb_device.rst deleted file mode 100644 index 36c4d19f34..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_device.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB 设备栈 -========== - -:link_to_translation:`en:[English]` - -USB 设备文档已迁移到 `ESP-USB `_。 diff --git a/docs/zh_CN/api-reference/peripherals/usb_host.rst b/docs/zh_CN/api-reference/peripherals/usb_host.rst deleted file mode 100644 index 6c61392806..0000000000 --- a/docs/zh_CN/api-reference/peripherals/usb_host.rst +++ /dev/null @@ -1,6 +0,0 @@ -USB 主机 -======== - -:link_to_translation:`en:[English]` - -USB 主机文档已迁移到 `ESP-USB `_。 diff --git a/tools/ci/check_examples_documented.py b/tools/ci/check_examples_documented.py index 4f2ada41a0..fa40be81c3 100644 --- a/tools/ci/check_examples_documented.py +++ b/tools/ci/check_examples_documented.py @@ -150,8 +150,21 @@ KNOWN_MISSING = { 'peripherals/spi_slave_hd/segment_mode/seg_slave', 'peripherals/twai/twai_network/twai_listen_only', 'peripherals/twai/twai_network/twai_sender', + # TODO: remove once the checker can also account for the ESP-USB programming guide. 'peripherals/usb/device/cherryusb_serial_device', + 'peripherals/usb/device/tusb_composite_msc_serialdevice', + 'peripherals/usb/device/tusb_console', + 'peripherals/usb/device/tusb_hid', + 'peripherals/usb/device/tusb_midi', + 'peripherals/usb/device/tusb_msc', + 'peripherals/usb/device/tusb_ncm', + 'peripherals/usb/device/tusb_serial_device', + 'peripherals/usb/host/cdc', 'peripherals/usb/host/cherryusb_host', + 'peripherals/usb/host/hid', + 'peripherals/usb/host/msc', + 'peripherals/usb/host/usb_host_lib', + 'peripherals/usb/host/uvc', # TODO IDF-15383: add :example: references for protocols examples 'protocols/dns_over_https', 'protocols/http_request',