Lx]s6F?0 1 jR=M QOa
`O #~8.tv2m qS x7TCd
+zýƯP#W:bAeG f*~/>陮:q,Kp%{!pî_U{2\>͓Qź]PJP)u\7A -y-cw;wByX>DK(
: CfhT?2ű[EYg+Vg~:&9J0HьmJVsF
g WЈkB%
F b9n۶YR|ĆRHc[ `zmD;}Jh*4xJ@se9y+LSFG 'AIT}-LcZmUmw5"8!VyOǽI@0;}̸oGv|ԓu,s yPumhC:v&
3*&56D1?
nn{=1OR-T;'<ǽnB3I<؊ROXg;T$m7|:-nk `,QΜC)Tk]+W
g&슛h>=L?80 U{aUa>o0D9>}/kdz ev0eC APPŢP>~.++0Te'>=mHUBٲ
+b({a蘊*c,b8:"=KôHĸX40>B!&
+kQ7$0FZ0(!֫m̠TNhJv0JYHzbt`ZhƁ`fAB_}hC/9XȘ {GAB$ |P:1ݷ 'ӚcE 6i6@ DN@-sI$)i2{ 9% FREy_\ `b[f@m/l$U|Pv] vƭbĘ[q'x6v-1> 7T# õ2ee,hZգkrQ+*iz0 V^'A0 1
Fļt8MyT!uk-l5B7{/Kž( ]ѷ~F\c(|[G6\wJHH
+Nggش '[LzZǥ`f&)pu8=0# p~=R` zjfrj "0J1>[pYO~<G xI7ALv=,݂qdgcI%L&t2] VP
ѷo%q4YkＨf#q'~WќsaZ= }cՖO-YRGtt3щ #ow ![ M_ |ЉUtUIs{Cx9+[펛Jzq!+3y{c)pRX8Fj}G_R(mDt{W0.q[Rm0{I'{|-vb𐨩Mt` &xXJi5c0O3XKr6}9Io>'P={yq >"F/ y!I3+B!17&E$+sλ1j?b{D̼k ފ(0)Ĭi0ULǻ@gRMWѢ<тpyc^V=;(?Aⴭ}֑ B&@Aߪ]uơiHS껬K
+K(\{mgu\w n,TT7Ɣƛ=QZ0:;w$G CKxQۊ#0T.~ö ~vґw Yh1z!RF>X 31>mc249$gaj &:*sG>:#ʒy* 7Bs:\mXc>6L杂p R ;15 1gѕh-X kg62J BU9|ӧ-dqOҐs,DuL'&Қ4]|w,Vԝ1{gDM>^ rR<=GXp- [ӓqޥOlD쯷٩qT 4yæ0$x焗G4hzw0-.Kt1_I3`i
& ?ckaFb}0L L Y ucDu91q'
*#9
:F*3=?L&'\F x+X$}pUJ" zTL)+ҔT:
+P-Iט^Q7. $w.0;B~C9EQ4ze+rH|1@+龈@9s4oă gq|6>wq-LE0rXӢG>[b "_nj0L q^+bt *
v
+ kcIq]hm, Hz12bƙCh ^Ս 7O83 > >,3oz*t3*Eʞ!!jkaN SΤ(6-d~Ӓ( )JQ`(p;:ERKGİ^ k+qsoP7&Q2Ns 0{-*tZ `T3뜻'Y*~=5ĎPS3Wl3_;F< !jn\Nv<)C Y3rm|O2G$ʚs
A5&< k!\϶sE!,O|49cA w2f*J="wU* zJ@ɔň3L3&`2ukP1)jK=Kq0D qY'5vr`h4ƶDMt
Ƌ8
'h0yF>p[u~pEH`MHYs/e4 L-K} mBʌ7F_jbNNV¢hHM @h+
+qyZXbb0ΎlL=AϹ1#E'\Icݘ$!#gc &i ѕ
+ka
2ZΜ -u Ɩݣia$iOXOg!D;lmA 8HᙕJ#V=>Gg$QFչ$D`@$31 mc7 o 1*k˯X$Ɠ+SaEȐƌzϕo f 9a\>x5Shf錹p! 3+#kx_w qH&76YFĭU5$g2wcӈύ1KdM5 3úl߬~N;;+UTu5f≊} yuj í2K-
+:0;+ !7Z eRBI{ß&-'gù5q/4l ps]-cjPݘMNZδb`DUT>9 Q9gI&zc+7sZ)Ujͦc GڀM&n'ȕI5,E% ?U[Yӓ`WxaQKw?qzv BHu>+SK2?u7.Ko\SG Ew
I=GUc)S 2\P qÁܜ>!LGgYT
Dvϱbi'؛sM
+13 lk^ю4WO0:k X{!V={aC'JB)$g~ Ƽ 1̱` =QB;V4R#*ǀQ8s,S\WdF}k2]E x `"E \s{0jBe[Egxxabya60oHۿTvIr0!!;]af[WG sjS?|~H蟩2YLVxIxҢ, N]&;\1r0KN;]lӨV6$apD?4˝<8p=<\ Y_C 6wxOz$ m}5줍ZCaϽ~^awa>c<Ԥ{">ddx9|#>Fq\8e8'poD=1RBo\-$, *sr !j00FgıRJ_/8.B*h
|/LS@ՙ )f W(_ ov^Nfp]4wFoWC)AqŖxr=\T8i-cyW-4t. USWkSnnٓМ %/$p Yt^Fۿtj7NRr,=a`41=܂i)91^ I[g҄Zl=CNH[5Lhb;U:'3f#;Kc`Mx]]uf2ousaB
Өc8Ѧ ͝de)k0g`^|y&Tr LH` .6͓ŔY{/\EM{X繓\K:Qu)BUkN9Čۍ`8br=^z ,5w\b*UZ&g>զG(9:Yuns{@ΘUSb[Xfbj"9H8 4434w%uD1za`,ٷ
+8R#695p
X}@*wҧB4^=}#LoamiqDrɤ:6V _1vW#U t0D 8
+njnY' ȎzgF> G^=6^6:T$4l̡f
`fOG^w̓T # qm@g~1]-Y< d
5NZa`0(gNڊd1<"*8ĕ`pe}2}vM4\~7` G^@$_27颜 m',q e~0eC}eϡ!x s"Ǣ> SP~.++0Te'>}HUBٲ
+b(ka蘊*c,b8:"=KHqǸX40>m
+kQ7$$,{/da`ɣX[ߘAeP7Zsa0{ #ҁ9Z[hƁ`fAB_}h |C/9XȘ {GAB$ |P:1ݷ 'ӚcE
<6i6@ DN@-sI$)7թd&X!>9% FREy_\ `b[f@m/l$U5;W[O cboŝnB <3 P$ ˔ᗱ0i]=^QOCplu`Dw3ƹ0lʭ wKka{AX* DqfEsY7Ona p9k+ !)S;=<;Ʀ%d<7X.{ɤu\
fFmr ^ 3 3A./ $]V8@LN-òRFI7rm G[ǃ0ψ/f0Ty;}-K` 8YřXRɞ^~
+&c:c.+4T04E&BC[d y M5rW^T
aK~UќsaZ= }c՞O( Ҭ!UF!9UO F#Ō(sEx%U'R"b!20@a*z}G?o-)O+15qL+^|bf.*8vbbN#apC-W
B a1ef=fJ\!Q0%^C)ۛp"y/DpDJc!LAbf# 6<3> 2.Í
ggO*pּ;~bs
FRm_C
ȸL.FJs1]V 1kD
^9o^Lw{JLgO J ixi!xx;0*/< M]{_7?>COS?cNi8F'i,q`SVу7c)#NaAcuI?^sŐ0@MI[<'1g1J.;4C;1j` 欄n6#k~F scM̊"s},Qa $5ybZlAt ģ/&OC\dDȱO* U!:gGTw hp>|Hʜ ^ZCu}.7HI($S_Ieb];tUkl
ǎ 4HU| W W`
+I= :
L+pfRσYͲAc>s< 7iv1}:)SX).B ]"aЮO/( OS"tESqZs$f4`JspX -t#H-@HK[1:m]e5Sqծ\=H3ɠIBrx֎< +_q]C{$|oc2abW*J^Qq@W1I4 ˀ9yk0)K#V>%+(ٴeh& Gkjr4ͷM:鈁8"dž3c4
-
+E `q; ,}bh oU8De{!CnԝВ~guLv(W>_d V)0;sa1ABGt`
sLQ#V/ CW3aGΎs @Ũ#0zzF68D#f,5*'Z i~#@("2gAW[Y4RTGxU1:,$LTS ՈadF8:÷dbJYm`4Zby6Ũn9>'ť~,מ]9Evfc{+H~bx? \;-fQĐNlZYH 4 ]@%CL v%f ũ1MGp#f =8G*~gyEhFW10auYB1c;WG8+1}G0kRr;m$A*qe?El
+⊙L6`xbE= &͎`Ob8 1CoE;BH3} Մ!b40r#1;VѸ S?(@Q1h6:AȲOHNLRo)Kƃuyd423P"U>,FW:2Aߏ`=:,2;Yn tM @? Ƣ) md= |.<5 6[ ǰ ;}H̲J|-cp>̊%~OaB31.FM-J/wxĆofbMUȶ!*=11X=
Q 1`ޡ祈'pagk vao.%0 = cʀY^b
+Sb|x3P:䆴. m;;#{!zsi' ȗz0uq\6捁bQaj8
ck}@ HZR/Zq FøeoTXƑ*Ɔ_ ˔H YLJ5qb mYHYf 2\j y:'P̖<3%B{ PL;n ƬIEPKe`)] V3F (r {&f:tWYX:jWW|O^pcύu82
+>)/-cAhRx (ቑ Ktrm}? HҦ@GG
kKϣC06< HJbl =t I=mĨv ~ୢ,T ^7=@sdii;Vq+1\8$q06#40TX&j[b3:"CMa{L+l *g5j^Sӎacyg'/ CY+> K
20ʉY؉ 0D] ۨ((`v3{tt E`'@ig
+q;X5~iMB; otbx;hIs&{6^)M ZKK G3daU !u3 &;`LX*J@tzS
TUutL<1`\]$w?+
& RhrW&CADC#+yk` ;!d+ 2 (|0Kb " cww`*Y`]sV(Ksyg;XwߓWQu"-8P<8;cEݧf|aB|T6W|r RM IET#--Mz z*DxFF=*1M s2w7o đ1v><!sc11@shG:8 a|3^wgYLlߝ Md79/^K}tДa.b}Ś54Pe raN0f0ocE) iA+x:> |f H:_9=UT
+fg';)pfPr-N2$
+5H~c& W\:3M~v a0VF*``0;XDݡ ǁ 4ew%"V?0 qS#_҃kܹ($séx h?KzsF~λ8.iֈw }
[A 2i;a1^lfI5 R=?ep_ꀐv0s%s`;; aXt /-j Gw W k/1ܥ2HgJT "Hח^2<seyX.BJ 5PU# TM녂&5Ix.rZ ?Ԁpr+
+Pk|
+Pa(>LS??1 ¬LaxfY 4 %0MO^nf$X LdA_ cf"'w:[0Q'/.-3bap|^0;$fޯ&f 1sT@z݅90v6EuaSda0LEg'>I =:$
+
b
+(>G Y`VaG4- k _/pqm(\utZsAJ)^0ǘXuCby;+k.6 NLԗAu( !:Lnq.L<opS|) MIIcX Qt0W4'ZMmu_qOEx@z.T Lg)7HkbX3^>$Ԥ㢙B8φ1cV-O^Z!Q/3/~בJ)Xz1szlaSc#C|\a0=Y>_Ә5'w(F7hcbhLng A(ފ A += \҃1l1f0}4tga$(|B+ KdI= SCUQE0Eٰ0a$S cDY c*`#@;>ұ'fT -VªVE3FHñ a:`X6s-LIu0T ^W."[S La͆ )BFN5 ?Ydu \̭AH6ň]nMɖ"]?' бo1 H1 ّQ%3܄Vp4(HT,=")E ha xc3 j[(@ BI| D ʉR+8f[NXI W>$1heD~)gÕSuY5~1N7g05:c7ƒfKBV)+KHgY t*Į?#n &&d%Vx3]t~M%pR027_u2Gʇ!q <2m,zIVvg1:K^GøcrX0z L3mm|Q]IE,N2M0gޘ'J]\YT~!EjW_.gb$'6JS3NE EjM2
+cNJ@ ~:{B+i%yZ˼6gc2.#MVKl;^ ^tD탱d&h%ڭ/
+sԚ2 I_ 6Ng*1 ]1!|>8oMVտ+b]7s8_0l,<ƪey21F'sי0x}6Li NO e2s0 Z鱿* QĶ0l/Sأ`zDpЪOs:T30gtUQԹf?#8m yFPC*+gLl 42# LH ^>=g1=QeD`8~&nLr0%౾#'c T ]gzěn-;B gi$+0|NQ9=ox,*`08L'c 'fa, Sgc=lcI"X *P awFdv7#5ɒa (۵&n^5uP odXGeE[_$ߞ^W:T'&Ci~>4
+3 KgL{ A:p_@숾'U P߷I{z04osssdzQz|x4&L q~ş ϯ7?s~,.j9+?ԜM sbzHZ00u -/4]5#t d\>dN`2
QKU8 wQ|~ƆK#h6=~
+ gajzmͮ}cg&X(_O*Q#6瞋Jgc) 6]|vЕ=PQ/L;`]' u;](剧IFm 34#e üqDSW34)sO|9Ҙgܜ+)
+ݟ瞺qsWymOQG&cC]pC8NxcQ+97 w}8;B0Ӿ)R9Fڞ702%Jܿe`69H>xי'9%I7&y6њl̝pP\}z.F@{º> @Y+ }|#8F3<=MGXw ]$4d+6CP@ܼE1s p]ɳ&q"-NY[jE5I)fkp#B1X?<))`dcGMٳ :ǜ{[IE\mYDZ,kL3 =s?C!=cA$.,+^<1WU>M{[mKٟJB㴑xJr,R }x^AV0\b BO_f.Jab]fm ۀQv"1F*@QLی= ,cz~Z$tigA:V'ぅ\N8C #;qBFCvoH I&u| F9M]T:RrC0>ar!' e.|S{;0 @\}¯mcu[""Ư<&t0GWUȐ[OǿcAW ͡/ tEGwX=ijh R
+Q;kW3)Sz+35_4#JԾ%%C?o\pXMS)
+?zi;xCNǺ svK@AԲ#(H->aݢy>!TşhiDk
?cb{J"_̘u&gT7m}_mٚ JW|
kj?@Ig{ st1%>&QwRk)Z>P盭b}㯳dQ; 0:{|Y( d&Rׄ&وVL)L
+ճFc"o > Z|rO\_2}&Ynyr FMg>oѕ>߹CpO0W\? 0Y7лu֥?"%h] e|CM^s ˩Tz6 !|Ĝ Py¤$oאַ+nP˝gw"B\)f$ax> R%UB> %ێ`qV(̑R%ٙ! 2& v90涮
+ &PY ;-fiUaU3(da{)db(îhc<Ǩ8ͦ"a fu9gV2rK&&a]>B*1K{PM>$ gy6Q8B~ƾɾ TvG 0Ǒ2XٚUt;1)S=[G8C4~CG rN(IN>jW* ϖx 51[! ;kĘC|1x~kd-q¨ :tNLєzv /wy6zVafeR_UEk00N K1Q &qd( GN_%YV 90Fv}colnwE/15=AufobSa]?uC7TjU\&1vcޙE$ UN Kð Ǻ4.7f R0pA kРkb({̗qȅ/oӠǸvo Q]*a*c9#Snۖn`Τ*5_$o8t5W:a3 4, e_ w8TqVRٛvEyH= 3ۈX e܇2XJ~߱+p-S4aQt{N2W,&wc[X7(r؎VPKu: yI ׀T^[ oT -&9+=Ajּ)oYe_G0v$<>0bҕYbK|x&. cTw$j'e#0V V,8J9mYe 5R åP61gs7:"aINVZ-Tp暚/맦;f\wWHĠ%F@LrRA H{> !]$pVyt5>?#] zzv&T( aٮ4+07yx+'6 W+
3e+M:<-6z&TcUaH]fg@@`; *Rm~LZZSw a'f{X%^]5!jE ,ja 術 ,<w
+DU{Bd74,2:LLA h.X e;_1qP \cωE{# ">)ÕOR߉^eoWq'ޟoi2n쓡
+#13!yo̻Qoh|!5cS)1g
+;Nt8
\qf_s^r Lo:ot+=ya߯[lk{TT
s1'+^0AzQF})
4ɠ9kaqy0 ~.(jS%VJ0+ znTN{D s_+#QԴ ka=4e7/wѵjygkXݦW`{Dxc4?%4Bs<{M7"UQEaz&AbHN%K5Q
+L;11D" kBdF14l%IE! &ޑXHXH 1 0҈g5ƔU͌85FdW;IojQ/Sy %j^γTY9;5nfsPSAK_ңKZY&IA6wy *Z
$d]$ ,-Ŕ@8x /A9Μq[:J7ʺ;9*i]^tcn -j!LM*o3:y` q 'S(ҰÇo-7T=sٙ!âs<yh UM\/p?ŜP(bm].鋤|, R$>ٮ9!ӘwseqiZ~!1pxDRLLEgN`xnV(0 Qj 9j gs pE\~&NXhV ,*f&4CX|X.B85Pi "|v <"l
+ⓩ=$)גSx!zPj@xs
+J1 Pa(.oʟfaV&Sz]6C~a18~``I
bStdOnfF0` m,+OUZL`&&Y#DB5ZQ6@ ߌV*{y d{u敆0``n I-;N*y{X5pa췕3
+l)GwGnhSJ0rY*J`TW斤}wI j5Ii1QiH[9ԡgob D 7]bV@JWCw(ka t Csh3:ɰu= ڙ!2b0LEMI.bl˦]nAXtj6Tfߐ<e( U U`M|Ch5M=@p6(Xuzr }̡bdA4{N ;h6h@I1 D-r0z ̛xSiDIð(tt0CMb %F~hӅ>zf!8b8*T0Dn`Tg`Uh5b*QH& Lv!ԎK$f2F
<`GkdXxJ*D7םXOc"vLh@72if1pJ~$L?N'8PtfMc% sIa3~1U)
+t3'\itMW2躍LJC3;9 SC9 c9Fz+$Hr R.tBMm !t1 -;D`kJ6i^CO%j KL=S*BLjc) ^F3TB8fL}Q(TZ p,(-dQ DJ+b6iH'!
+s`ExjCwdKLGA x _A`(2$ H#"b5쑘!tX Tcu BQ垇-~+S{R#4N< /DPCT F_qA7 Lu0(ZˋuSSb wT@X_b*# H{ ^sdX rჀ:Gx[|Y{$q_OSY7|4 Rbb'0$LS Y sasxG@A%`<3D:RSKJt`fw@ܝbݷI] Hp[SwLmXϞcC50} /=4FD,` C`pK:pwS\8Ͼ Š|$rE}w= 14*jLRkߏ?O?;|O~~~rzˮH%qbSqX]!(%3US
`I73 '_3KkaJGwu 3,je"6쫩j<ZaYS~d~=%7S$IT$_ݧ(Kؒ/Rl\N_q0
+҃JDQz2S5}4] DכKY-z\E\G @Cli_=_:Gl \9 #A%89]]#ȯ0Ry /NxI϶W,JOgaMwr3g>0s*^ ֒sbQ!!b,4)+Jram^h4P8 B)I UQ
+"M ؕ } NL7[
ʻc6 ^H
+FM8ckA9d yw˰BEP)MNۣ=6Ku ^v%)p`BMڒ2:8EDiiw6S0JpDh ʡ) (F 02AE] ~Z>̚Kָ8./`D)&ѻu ]NFJR&p.6n d(혰DR}?3=*tlŶ]sd\W j
endstream
endobj
22 0 obj
<>stream
+HLc7 #p@E $oǧڵ[i {gϜs,o\3V_L( U{1b"X$2Wxm֎5Ŭme¤uW|1wF) k[bd0sG{9j,Lj_ճj^. Uq{E^Lw[- m6A^̴ms݂to fG 2nd;6t̜/f{6 zo>N2` rfOb*wE}0aكܓ)Pk0.ATT*F8.#L&Ni?rjP_P)8;P; ^ޓN~m2FZתE&'hL:TynS0179{74FYS_Sgd]XS3_>
˧v/L _ǩ6Tk/f6?n26 `=p{ ?:Ks0L&5 O*8p043AzWŀ3 `)6CÜ*96ý[ck2%R:( tM]KH\߁ЉbP_Jε㐊R͕r)F)Q<1֔)j閯BHIHiJ"6ue(+,F ƫ?gu Y0lpT=B(LAHm H_Y9®iF>qq Fr78 Lpa~
!2>؈-a0AT#b ZV 1EN!W0g3sDHγR pK_3Ec/Hy>s8abtN08t*n
i
+o0XgI7q1vd20R,; bL2U c| '$jK؇biKFԆU×$_H;Q>czbO%~lǽAɤҶ` 3 zZ_u @q*Vc1) L S&3)͠
+p.8{KR &TE}9H
1ot^ +mѕOma7*ZWBI5\%&Ä -N\z֝?Zx b& ˹9@oK,7&I5\?kn
T|7x.LNZ_Q'Iڗ%85(Ԙ 6sW
gr}GɜY.~^N;_ c-롨a܆\g<ڣC68{$R l!%5-;dLY aal }-^` )1?LBQRB曱]~Dl ܨoCg]9 0n3uueOfC$:*j/}Si(:(:}J܍¨Qo0#jR7a.J S"k|`% N0N1 #nFکWVo%We%+-繂Y2Ӈ i .<ϲΊ5 YܸNgۄ1=ܣ W{M0FC{ R5yםЖ {ExW´8厶(ajY}0z):6q֞QzHE `32?-(y_DUuX0/3u)sKnci\Ϊq9eIºޕAZ"CgMY,i% _+J1 mό?R]
|
"0,
3})C.-oX;U[ھF@P( cB܇MI8_RRf ,>g>`M aBP;*17ajڠ`?uWcK뢣`LUvV F oKBztDŽ# WHTۂZcJ>$J8#@ ҅$aN\Q3|[+X, fZ =Y
+0(ݹB lcTrʁXEJ fXR /!MIaa;E0H\m YB+Gj[ūp%EW$.#ۧkC
+S; -Ȇ{curI(0#o P0fYV,.mcTfHZ2HS݅wdoL:~2 \[U`UL_/>D}aujx9eY7m%6\y?zCfV𒑐Dd
ԛ8
IP"FAG|Iw#k^*}wo0$ MK>v_<0vE: [IrGSZh JEz!l[`<\x2#
+2%J'/nd,l Zgg嚼ɥӤv7*018]`f
+ * Yf;^2+`2Ky\Vè_}$_;f_Ĉvo>Djzc2: #1h!^6u{6.^7r
wH8X@\",j.o0XAMcb.X3+f,Ag{s>`(
Ǝ##;qK3WԸ2- \ xŷ|K sN0O.(9PUrEL7FLLF`J:= GK95'`YrXi} E vYIEú/imtmCPg$Oף+Tc#lk
+iruZ}6&c`z? a21
+\T:2}ZBI0f3==(_<)pv9&mCTI(q*JS;EI O0' =6DIw-W_߉7a8`FT6svCh y0='{z g\)Ru a5Gyfl0y2,O!G3EB\}CM(t!)A Iz״zY% ĩf.:Ap
+M~UYxVXaZj i(͔oYΖ mo<08cU0.;wۏp xM#ifSU$YsHY` &Բ\o/OQ0Eo}vIY)Ӆ_uL^lTA[vKZ 4mo۵>1TB |YgT\ȇ7%ǿ4I 3a\#xјhмb#
9àϙ{Xiu1 wJKb tu~ K)&L֢+9=Oͥ . -W{$ųC*[H4jXDy#ͪ-Iif0q˔WSUsbQlguݓ|L <0D:LYrdddY*٫* ؊8sR-
zK:ߜ^I @&5}5o:zNx\Pܟwb JbS1* -Nq/j d`$=lJ(GlL!vDtiM{x,@X*lXorkFmj輭Oɉ[\"6KNjua`dQń#ƾ%rsa 1dD,$2ᑭumz|#.b<#]e}Pi]ؼ# !-J=Si2 ;n凟?ӏҏ~ O퓘[OVKD UJ4~|×<(cXN+K
+Q-V5U?}#&rLl$w, gď -? Ldz'G^4Zo%ّ:]&}'l 昢R2/w`PaHi3ջ Ʒ [ 3VZ''a&&"ev\#c]c+12f l0W_\`Qt,03OK$W ɉvjcD
+[i-OI`eOE#9d& EII0F#Iǐi JEɭ5LM2]+// f'D?pW m3-S.ycZ̖nrXv s$TlXxNG/ y8;aF֡2T}}V$5c؍j!+gP)@g [/ = `rf/5HL!%ȳ
|f g0
.KF( z r* Dy `I!1Yd yur6vmk{lW,*$lgMЛX0_gzM-!^ɤ/Փ=AƠ ~X빼Z9z0OL ||
Q:9$)| ɼ?㍁F˅e7n^Q aXu>qM%]T }C.yNf~|:e2#K~j A4 N߉ᑾN/֧階O hoD fR=Y:'<H1`d[/7?1#Q+QmO`!|>$jƇ |{t bC]H`lZV垅h0٢HCxՑu,ZߊXO(R&1l&HncU:N Lm3 dH9%q Ts%$F]f1&#
@'=^.[ <`8{cD`Jzi-=dP)CdYqhk'kbcCκ*ZַVfېZBЄȂ РL6\3Z'erQ<fzrFۆA!:&!U c!a[lZ B]1WvuR~`0t%ٍ#A݊V\LPIN iDy 7eJ)1g%= 1 h0 -c_{J=%b-V 7!fQ6G|hPΕL ﲮ
eE WTլdg=ٵA$b<bWpM^AH;yM1qF?It-!ff2^~Z=7`%c0:߬/^A5,A+AGe Gt%:FLRQ=;Lm ھsd_ a
+-Qsd>_-"| -)*"DxdCzu)Eo
+ue" d1q3x9rTvpL X&9,ML!}0o:k:Cv211Q [Jψ7:erCZSo+_d$o/)O9=% Ču9Ww1i)?.래u"9ƉgG-݃ӅuYYl^bo|8Z$ͽ<c}:19yލp+:\Ͷ&HI2@Iq'80R?GS1*~e *ҹCTzVA'FbKӬgz7^B#a%=NW!a'c@xKwxWݪu. doϛ _wՇ8L1p>1{Ϲ^Abo ya`̫ȉ珷:GG~Pa蚁lĘ !Z4p$>ʱ FeWb_݂q[ooTم4Nmv>t} tAXs8[3sa4r=bŔe&7T =TDNK<cp<_lZ>ٟ 2ot +M*)%QuyK()h50c]B'Y;\֯W<jpB 7ي%)ƅkͺf[28~]9>r=&'KaMŶ7Kth \3z\'ƃ[r[ɜ
_ ΆwS٦mfux(jbؼӰc/Kc:/*>lS J̲VCjS<
+a=֚EZ^`Xgb_LPen7c; {?513[kӗQ 8r c ͨ&4eOfB `כϳd 2^"}
+˶~lFa#jSxY'f\*̒{]|̠V= CxsJkB q7
+ުZ7҈oJ㯴8s2哛{{e)G}w8Nsmh퓛縶ф!7 h='[jgpV1Ww=0[No)m8.JakjcﱖVPakQE?{ר0Z_+h~MGǙs 7'İA
)S{52fP9\Ƚٸie,RrDkE 0`sbVÐ/.Z,Һo9ޙ21
m(O /Zだc w 6r nJ s|IɚM P{x|ƃx9ݷa
+qM:l aey<B:k CGCˆ0 "oƽ'ly/SA92{_kI2aO/.;3ꄩ8TJ_ 2J(Lێ0(_d5 2Kpigƈ":P4B]Ee q$'cs# U iƮE^68
+SNczS6SaHe\
+na LFv_$6iQa.Kag ٺ )l1?6"L.
+XTuQ @+;p P <w #m1-~!Q^]d& N~3۠aJX,^+ 3s[~!=ܹ+
+y19a61ZJ91 !XR /!˛¬ fz*Fb@>u8Raxǽz^B+"k~Sūp%EgW۫kS
фob1 :?;ƾXVb27ξߤ}0Ey`zۨfu=K6;T{z#h=+xHHwb,Œx^C=őg?1_N$\hc6:j;H>c=) ̡Bѿ2]}P1i g31+ʵc=P4e6QVZI]g0-%q(՟DQz
F{K玌
+yF~Y^ uTXgR:Ph =H$`zj;?xFJ
+%霌,
MwnZ@-W[:RzT-u6}[veFjM (܃}kř|vqk
Kܰә0jtxQ=uϑ.4oi1
YhkgJr]): a #{tcsF@;zb)I,Ce lBB}'N=;@aΗ\.J(vddħX qL2O Ttqm9(2X ]&7[E82=TN'L](2g2m{mUJNJ;{:y=IoJI @ϾL7I -fY '}{ %m9n%wJ W#d[lUVfkj\p.=GlrZ}kcB ǢsKkb!i^TDZl[L?Ǫi}mDކc8, wJ'@NIG\3Lca 2 n Y#Nry3D umۺC&Gk[;!,
+{bD"W>'#YR~? Ͽo|[?>7?l> 4c}r3i;{P)ӣXaʯ -a[z F* e\Nnޓ8ѐLNȢSwbfOp(I0HC2n ʮALxԆ j>s|q=$ʹYe(FDTo=W"!qWǍу,QaZzPniVt4Xu xE> CΠܐns '<
GtߘK$IE* $
tq_<&(^Lj đZ+Ǹ#_֦ ة4K>+^ACVZhP. ˳Sm>r .˾06Q[XF!OzxUFX Im8!%a\NcO~s!%r( q) -o=n5:wAI*yf(
81( M1IhU :>+ȗǦr_2>U={<{rfc"k?F\{ $BU1_#WY>-P
+Vgד4^t6 VӧyNB.i mnDM'W['LyC*rc 93 FT9Oiܵt[iea$jnM
u\1NJL"iw< ks8fu:apLgߵ/{=EZ &ĉZ#jɓ"ub"ijZ'F$҄k~ 3uKQ/LZQ P# uވX0gy]bÝ0jo<px0̩٦o (gX,&:g յRq#(=1*@=b _9jl
+"OA( h
+T($/i c+\q ٟu)[BD.*6_imvkQ(>{{Q
+|IȣϟChRz*~m:ON`bTklA{pU->Xgi-&_y kޢp8"c̎p)oٯLV S:<ԙQ
+B=(YHvaoAuM<60i흈RAoNֵ[ Jƭ=3ܾc[ f|&]q>; >>0|ʛzx?K:aO_}* Fe 2$.|'Kj:?=&QSZ$Xo!)VƐJ 鞈)Y$zz,
c5T0ƥTnZ"dRXcyZ\2%@X71΄(( k/$f:MVH: : 6;}`z?
+x'g`gJh^i%t7b}0{Yi8 丷`<)_CsY|I.}9L$c=O/W CKΈ;,:}ڦ) "eFȽ#]gٕ@@%cWA1wT~gz7y\O`B~ٳf .Nv(\5-#bּ8KFA1\v94wG%D ސ1zǾamOW0ʉ ~q
{ kk. u EV?[T όbGc#wz)oPxS o$ FK)N &K&E+Z}D{2S[_2GB0W Qtcwab4i0"EL5覡|~NCV9F鯑j~g7!wv$+\`
6 s.(k<ƅ_c;n s;,;:BE ̵0w3cq41l˕^DYU 5;%V^;tF ] oNM,!u#K=_{a#xO9y`">=Tc 1 ~%f`U_1Kɕ6*k׳ZQ$h\ =oυ&7Xvsas)eEe+Džї|{_[\!YȌ?ŝ >` .C8JKCS->h[p_C"A5/ 3Kp01 E;Y iéas -'M]4hxLbgFT\
+hS?´"22wAuT%!76-7\LiBr`|9r\}`ݾeLT{BĸY2~FQX+j^ XVH7"Y'~w_/l_T_laZ,L|OG< oczl^k(!93u:!q:9gQ+h}}y ̸|wY8ogcyd5;YuXδ~FaBUFW0W M. \߳XLjj%ҘQW=~υ%e\NZS
+cl#Pqm R&jd
+M呚a 懹Bg0ϑOe+̋ ;0d%s,qVKQ ҞY1
+_Sl'ama~J?1\q:QC7>L}`T;XeN8sЕNé Qj
ǘOy¤" <佶F!h a, y.l1,x$r*^a8HS>u W)5濿8%Ų;g$h({υ$;ث_> k;fgD;GzXCG}TUf<##'`#j;8;FḴdvY|iZeokfO]qJ I B*8n-BG7Rs:t1DiǻN%,@ݱn0M}(0eϗN`8WhYXf
ėrD#חI>O?ً
+T DezVnoQt5\gd)oe FhK^!; ]eGL ab`rmHH%q JfUҝ%f[? 5z){{A%Duo3.߸GۇтY0_n?m>096scD9\ E9 ;-E-2M}ěr'
+rbo3?[} SOV" r2
+{& u8퉫PeTqut;ZXOg<7ߘڬsLH5R}ejp*Yȼ ^lDuglom'R u{f^}1Xu7(XL}{z[
+5Y=U3{|!X~?XvP QcRK c8"tյdcNndTVK[ y!% ;>όgu$|1< [GfFHXc E+ >6:whԃh`Ha_ " ,wΤM_ݳFG7r(kg.9~М)Wrp7/ƃff yJ>
ct1S {`azI$/F=_ꙶH<p++]Wwl/۩@:Z-DgޡCPaB")&B\8cD}֚Hg5 @E>@ Q↉/y+*& ;_{K{YAJ8ڮg#=՜؋F _t9{AX;9 'θuąJcEh 5=)~
+X!C&:
+v+KE ԕqJ]-*['d^Ӯ0ڴMxxgPLxS$50u3M
CQ,zai&-9רqHLp.Fozh}ۏq)ka~<|=* K ύq~}Dzqa6/9xc x>艼U(^1"}ܐ
`
*n(@k@4b a ]8k28z=*OĢ;g-Mڼލ8XsCd`A'*M!F. uPLuv
+T'1EBdupQb2Qq$JobsQm/@
+3CL0t `ˎ ;|
+! gi0(IS,: LK)G`;Y$1^+~yt)sH~¼4 -?Љ ) k鑊I ۜ FŠv/05ֱf6 68
iC 鐳r#Oi6m*:yl-U("CBc;WbO35z}!=9 OjMv3h4`_ҥ~Zf38O`[U
+U̮\DQ<~U!
MƲ&^Td?@4~ OXBTxU`פjZr/IaB፧$ iEFƃacJl阅wσW$n=֔/``oYit }# LLӢg}i}ECYx_ 4/q"Qnj=4p2XkjC|34Js,% :ρ/x g/ʆb:w1Nq)F3"o2Ό ӃRP
+xlddQʬ/YK*ϵ@-& 6&PZ KJ4/Fꃢg
+~N
t6MP*@~]96$ fu6\}Bsq0l2nX
mX~NÕa RF0L
MZNl1<; V'pP{2=
+ FFM4mo7KELbuƲ*}3Dɵ1yi\ui GO
.gL)ď%$I4scS6d `fЇrirdy,3Bň_wT>3jV%V^;tFnLWi 7&zH"Ϻ%ՖW6tnUjS7 &csKu`#ïDB W+f)ZZWvzvK+{"4ƕ1DJS`˟Ю6f>gRf\l1ҿ8^6pzH 2#ϡtq'cQ l1(v5 (/ M
+ԯ>:n]Hl̽3P\PgMOw0̷ch9nzFS1-Ɋ)hDť6nLM!"351
+M!JBd3o0l+Zn{c2 =-Gp}Qwn-ezM?.'͒qF3jl26M?`ظ9pbY-#gc[YMOz Qu[a'0y6&>[gG< `z½QC's0 gṍu:!q:9gQ+}}y qVp_:'jɞ+jvw:7 fi
47x`l#-N0t[:7j욅}wŘ{a\~bϷWodL>U
+kC'.bZY0!TA#\qjPT0oȁ㢬
+V ^\1452[p}b25J1+$ K4ʸ4ZS
+cl#P_`X52iĠ Bge]=v`$n JX8VKQ Ҟ٣1
+_S%$]O{~bbt 67>>0 ,2
+R 69@'ԍfcLkcR S]LkqLޫ{Pimaȳwaga1#SJ9Jƌ70C=zM 1؋I6[hc|f}}\e1))]9#DCyo
&i^kۘ= Nbr? Eu Ze6uCȒ <^w11.1^CG_m%̗VU&6SW\GRGκe_XjN?CSH=xTB? ԌMvaoC$Œ>_:?B#ĒVh #
+9mLcXLZ~żA+{T_ua/daZ/78vƲspU[{q?DK
+jc,;sCg}+If8RB:WiofvӂZ!דgqbw> TzWφ#xdLQA[r^^6c8Y)ta̰08/pU| WJwΗno]r~jSoxkn"&K { %N3.߸%hA?l0_n?ҭ>`axv&rs yf^<~H+7|s[iRL?$ 6?b9G3>H*FA"}2rf GlY<5(Hxka8Y) 30!Ä}|S#eUA$Y$U> çcǫ] yawQ/]-zM5==(VI{S>N`4YC2aN~+ΐ>Ͻޅdl>?],x9_ď g1 ֶ9sc
D jp; s
+z8|ƳxqӴ+o&xL沞hȀ F'5>(>`xim2_#N\$VNuDŞ+ >4G#52Uz;&d㊂J8vec#zkKY/:-Wg<7_keutgO5Rudjfy9 oڔrQ'jMf߄:0Y#Pg0ޖЭ &s 싆
ĈM
DAMv MQK #R͠ lU<e`c}v*;JǤ|y qD*9-yPg<&&Ŋ%^GR=h}u["3sIGݰCjJ Ki"Z%T/[T03@SQoϤ[28z5#1=w.u|2jM:#_Rߘ$}b |W̿Va ! Y s-=r"ma GPK
AM gi\:aƸv : 6A[ 3 / ˮ{bTw'Fhwy{B%=PaKm F>CA? ; 0g:3 5%XEx
L`y($A=Fҗsa&`bR{@0fGeL:N{bC ̱{Dy'^u 7c L 7E:nLLCU_L`ұ:֑lszL%Q·®0$P!
/iŦ~@*J0#0VZC a83 ̰
+\/3I#
+9(A ?2SԒ+ т E-V!&cANa+/ؐFU?GU]ū QvY[qeKoa'1F0#Ŵc`?Chus X RVWFra~zf鄳1*ԠmuBìGʩq PIFf]iNj y0Tޫ˩z%LzxN n? Br- gy ӴDӐ̙Cb̑d`Nj)n]ԓ6-sF3l,SHƴ['UuVΐuLw#!-uǷk0UfA\\G=$^^v ٌ Q#u<>i_DH㭠aϏZ w-v8FNp ;CsI!T _$\g GxiO(jxRm9!:װW9:=9I2奞V"A0/h_I{!z ꘖat6D^`fVs9)k$
+W$u \p*Wvg-\E 'co|1\^ӿ(֮61<8:T333T{/
+qB}1fDz"7Fm|lj
+$ 22~Gj0)8̑P^E,ݱ̩Ҥ={#k柉 gJ#
+سR0=h0 ߅;!S05EZg6\8Rg}ə獎7HR4fr.նx
+CZ n7qcx k )\k~<<ݶuNފya+&[ĉ Tck#C `+A
D;#z
e yL"}aj &+u>:+560* -_2=A:̈́[ 8'"3niSR`%bf|0nhd=#:?>yn[
Qҋ
++A-:̟2sսb< j\>Kj Hb˄m $ah%6O|,`6ambF;ɘϡ)< RX{Mڵ If i&/R-sx LoWclΑ1~-KORJDŽ`@cO1KcYǧ~gʾ_У+>h~'
c(!+]gM MI7h {E'DD؈y u' {.%y4 ,0=IxŃ=E cK+3#/A&'Co6bZ{̒˞5\FDzXyJHtV4švW {'f1P)_aSхټLoz"R Cxo1 4r;7GX_m:t2p TIGmE$ U`]E
y=J9ЪOy0Xf7ЂV OaǴ`xHV] ѽ:O8!wQklѹcרG>wLnv={
+oB~G]*c[ܝIhyE G7sTJar#,jvx%D){RhxFn$Ĥ-5'UV8RNB}5M>!j1]0)A
9V{aZ-ugez`0/ &R@2yM a{ X:~,W%hbd &ybU O;3rP [ȚzbrTNQOdUM`=bD
+:2걹% l@I
+hKx?tQM=; Q3vcΧ k mVf>2sv5ny%6ų/q»;E4Plik1h?ύ1~{֧2u>BTFm}3Zsu:O 5?Lv;YV0Ϊ[ғI$(L =nmM?Mk `|ܛ
+Ĩ )sV짏Z̝{=
+j|KS|@Ju&GD-om-;A-wQZ|[4;3 *chLh=C&ڷ $$:>ِ5lġ_6ٵ+k ` ʱ3Y=ʕ(x{0bǔ$ we܅cQ7
+>ރ0Y;fć!ԙ`̹, @. NZ4X%BǞc3JdƲ1bA7!J~<+'܇zJ@5` }J;aTˆϊFIQ@6`ƕlHq< R| w͍#̕1YOdF/m3 1^7&D7RE
;clSrm20-buknI ){O
+X{`Mo*f~(j&.H K;[Duwhb䖍16/<Y`%F8mN< D5y~= )ď;x?SUgM;G[1 Dj¼1B L2zGR1 ad(2L2x{V>+:ƴ+$0(qqı-T»E
3$Px[0L[?r0}R|V| Bi+o D&ce)ƠMڬ" o26bMdtDŽ-I
|MR-, VMf}$-#o cRތ U-
WzSiq
qٸQx[/#0,8Y; 1lSffcѸw]]X"cctm6̻l|l
+lL[a辯Fc}p~F% ]Zύ dQ<0X%}a
+*$RbA a|{&OqOۘd{>x+ &j+37 (zWE<6*_W
+E쏜RFXkAJ${ 0v3C$#=
+-նզFHT{,ZQ fk:
' ~}淞4muº8(UFɠyh-R0}Ey.C*$jWv0l9<7i
1y7L$)%ٮoL^S'j0)ƷƄ|_IJ0FV>`//̝'1᧐$;E>e.&ouELz: ?sąښyIK"9%Z^ k-f kˣِju, &ksdYՇ ^B#wU\UBDy\3D$[7&#žːs '\OGc.2h19&-6/ ğWA߲b 2=lx./)['@^ʻU=d: ^GV1k Q#n`ؐ4S$
+gKdzrz>gp^Qao
+:eU?繎 A^Ukg}Qo !WE?DfĖҥI_'ƲX1k ߺp`_~nwZLNtw\Q=#Ѯ?XP,smXzTWwզo=+ƔnX=zR:)@Lm'LGo[O` 9
endstream
endobj
23 0 obj
<>stream
+HD۵e'#89zӟ~ݫkJlQ>/ 20s u19m:=n0Z2sV 8bVV7l9*ﬖŜ5Yw/ 3w;36^/DHdp*qqP\HwnAf5cwLG) Ԫ bVE() ,&i9 -rƼV.bUcbaxu1` j1OU0R\Rv-O\vM0F$% #o foAja: r{ ;zub,.@HQe{DY afwQE (,TR 銹=>ؤ60 Q\̞Q<'&0zPXJOQNB - d S)' TfBZ0t19܉SpR b*WaI*f]vxyb6]9~ؿA<$MG &\~tHbҐ <* gHb5)x> 1 S@d@ "\>/H
sa3,dS}圃'
+11ҼC XN/ǾeDc\BCp TrΉ{`ѩ%L1wHBGl17C
+aHOŬsΠl ʛ=Lcޘo ރ'a3a.q ##q\~)|-Q b& c>V6ޛƫ
Ea ăR/PT-Jɧ=h$$. ~Q%ل&L&NlEѿE8Tօ9ME(a#Da(6
+2q0#æIl~>sUQ;c[rTFE[X= C0~ h0N \>bwhCZ"(&1 %E?rG|o4$ iÔSJQ18xok.=ĥ1Dq̍
&s qa |9yq|W&Y5q9T$opOh<,2 > NQIڇas
a1w ܖV6 ]?LB
%^UJ=U!h3cIӯw9Q5ص( Y" q،4b3 L]
+9S<3mKm_'3\F 6bLV=kt)Gu9HdAb9F{xks`n t:iD8֙ڲ!3>J-~],(GY zs8V8aIwJ)ra}h`Ȗ܅.3?`D lSc+VːWIa LEr6&1d%T^j` UǽӞvW0N4z 1Ug bd&7 TL9 UW15h|k8HM F)I `Y`!T|?F ;fv@%
+w1j@0 x=z x40_Y-"°`a #Ab_ }aR< $!DZ]9b1 ȵȎJ'e
|?lC5
+M&A=5sd\xj0 =#h"4{? ͇A!]8}T\O>zAj0gtK sC ?K`ĿF9̻η`J ƪ&5~Uy3ń`B3EY{DE n;R~D0:'9[~kƨ a,[H1N>"IaZ)ՄG[ofhFD9n-Rk[SL`kbE\)vmX:iU7KvJ]gDqt79CeyPYnywz n/ơ(dQ(b
+%qU6m^^1p ǘˀar]@HIfǘPaR-* V|A@IywN0I<:l,f&n̝,=# qK+c,W7&q:Ǚw1lOr퉶8xIэ].0 &qOw5
E\nIDz^u1/C[>9;CtufdFH4SO@°-F9i^=Ls00 -Ĩ Ck Rs ۏXQdbf@ s$ iU]X5bX'$Z
+3ŷW;B:;)uM >2gF5+ԞG-Ajgou.Ln *Of9"%!`8l}s33]F&Ӧp.,JN uZϚ{'"`0-]8Sfu MCe I㮮 jR:ILњ2j`ݐB
[q<1<$R){uKq"B5&T:g&"Ø5*EĶ$S aZf{
+oB~G]*ѱPKF 6G푾ar4ـۘ Z Fj[q(ecbG: ǫ\xҏG
+I`:D-F3!:-~0yU-ذLk %D
+Hz0Ē^64\9_
H|'Z:^"J@ L*Ū;+LAnE"k>Q9E>ߑU56suĈI[S[͍
.3yFp9w\t'|Ĝw&W?bی:ͼe$ e,Jl(gr kmwy@ Ι4O}=7X[%iDZB!*#F:rtim_]a
w]BMN$e E3tg '] CϺ[zj:{]1ӥ0OJcs+MA{)*_{r3v:L&,a23+>q<g "Jo& yt׃Ce!X g}C&&ZT| y/TS`PxJo#c ic& ƋcGgQʕ(s La45V'M! iw!*$
+6oA }͈cCӽsYwt1f[jbZsJ { QJ 33
b TOs\O>Sx6D?`.o9[] }6HxLHyZybhc 8W0Os$I[C/ Ax$='xy&nag1ӑ쥦q04V6m\CBXZt>OL/u17$]Ez̹Z0m.|SǕ@3j }8vA ]FTᎧ"=.X̙ܲ0ŘG p" 죤Elu%cZ9rB>K+y~i`ǝ$z'#|adՉ1£IE}aeׅ9}k``~m<`=י[ &ID#'}|g1"nfY(E5Ef k>)L6U Q2ua&m" ߃˳ #3&3{x/K<¸bS}+[72_YrUl}KTY Kw1;NĨDB4T¼iX4n{'H0^m֪ + sW:#q1
+>JNژ .y Q+& *
L .<;Ih-u1f\{'2Lgp^a樰7`X2=h{ir\7uԉ0g
+\q+smg pP_~LtbDh i*%IILE;25mCAk̚eOEMocᷭ=DS`(:crʹU=s) IKDR 8?y#?qWqV#>x c'˳MBiԴq3D3Q {d/3q sDUY^B/{^×}HXKC~oEN1X^/签_1h ;KBx5u}?{'i{
h=IJm< 8Y }_Vhr G^Tih{^~yzs4\ SehK!>UJuyٙu}% ? Gӣ4Ll,&gcғxP&@;a~o3PAQ1H\WS0yY b 24vL"ATia
+ ֑{U~؉@˼2\@l;ic#u i&H?1:Wk L\p Ew gwZw\v<c ?l,}1bUrq_) m<ܷ <*:$ {i싩Mߘ>U\d4G&w'x)Mƶ +cRɑ{ D\ޅA W2#]CD 6XzywZL
f$Taߘw0$'$E'~SǸqҟLgW01e,Ŏ037LWX*jy9QypQ w9lC %h|kaX W1r0і CPGR~۬.`*xF}fh
+H\G mՉLW]+2jX4o<((wjQ%*[}p QsoY@z k{Js~9ż91f
+ g $N{F{rMLX '{cHL.TBozm?Chr'wa ~`
2co/ُ=n+-K?V&JeCٚVqmוmV1
+9Kk OΡ( :Jc7hۯħXHuO(oSV ^Ox:~ v rڠe@dӗ]!R#syN ?L/Yu'?uYRYM8?pxSZ'?dŗwȍkN+ +w"lhķw"2KE
Mw2" X@Ї>V?mnxiqut)qu^ϧn.kJ &WylyH$g0g
Q=/{a`ν[ϳ?DQ[`NIkz !Q'jNѤ%
>TGQt8RdY+'ȯA߃a:T>e1jsT ~Hx0c4 Ěfف`֣Ԟ9mpa&
CcMD>|$ (.j|;lw~ =kZ?[sGh1pAGN(
+2acL 1 6\Lk 6q0S@{-K@M1( :x>~QPc(s !τdxyqJI
˝NY'0$ `JT?==p]3 [n;qtq\]ܞ(_p= 1'ɜ 3 _vRa HpbD$i'0QxA~S
+_Ĭ0Zu /,~, }f4"7;CiX
+ &S˗jyBh| 05W,[=sۂ˨CAO@;QQc c8:ׄ`+T?Z1ײ.S"7&9͒i
Zu~0+3dޔ+nAV 06DWYboB1Dds++fڍQ
+'ˍYa] 3YFXܿ'-;O{:vd6 `+5~[N"Ǯɱz~տ??/~?¯~//fY.e[ ~ ok9/Q6*AO!:Lx%ƄE )>{瘌jRTHs#aoXtL+#M/L% |uOeB D&/sX FG' Yƞ`>d}rH
+OCm'w͙Ǽ`\&SBz\n?FZzy/7W}jr61%. a_kks^9C?ʇ1"g| ך| |ۗ?~b4>"bOi&rr^e`ɆV/RP"ʳ 5꿍WsXg$c9b<&F fc=OSB5qWĜi'qz[;7d٢kX.q1Li*( a3T?u ? z0{ wq>'D>je6V;n; Ay RnA7Yq`VEp5v%J UU&1`92 eޘ4)et<(
+[7e'٥cW(\g+-TlEO($&"e4dV{֕x}u M%,Y@T>c=b U7]S {FEj R`غ$in<V˟3e%rӯߚHs17C G\XQ[2ꃱWB}렃 X0(fYR
n2]ej#a5k,j'} BF go Ѡzj>v? Z]o#"u6[^FcpGYPE4or~Wn־`ҹn4Tc6h<\Nje/ra>ca_l&]5ܲݫ\X'O/So U65 rKD 4 l\_iuPXM3ǎg, }Qga6SQόl$a{=o` wa>TlmL9ڍ@q
8Ѵ$LfH al1Tod,cr@G
-J3( OZs˂8o `!=lJxkh":Xp!jfTYƘ'8 d4&k`n(?QM4gd7ߘ4 5
+6d{ӆ IѮtC$*Id%ŏdqT]q=Iki똌vl'#k Wn>1ۺaeh0"vTĠj!"@ӧ&ao(t UFv=R~cө a4 s0h(h< [8sVu93sV&= rG#:$i'-T*`07uNE9YfF.l
s9&|ꨢ{ 5k#acL~Uy%1F%ޘLJw;n#f@8gᐾܤWӡ&
+:H؟?{43\{e.vֿ
#~T#<Ħ0Mh@oF
+'JQNX 1E91CNq+ ׅPs4ى#\j|?NN)ig! EoT[(~摖{l(9 kOd d_7R#LMmGN&ԉwĪ ._VQb_/NogFݩSzs. @ vƂafUr >i$l#KRшCh M*D&3ҵd_ 픑Oߣ<gtq.Vk%6\#f*{^E.R8 mi˞KEkOii99k#%V:C(!٘5].+gL_=j"e&KqMȜoVd$)t1,'Nn^v ZfaVQaqA
+%q| P\iy?(BhO!U*W|r V6Zt,c.]Ņjl/@"kG [q7&Ԧ?[uF;??-(#(pŪqM=H)mޞ}=X@Ae5לpY
+=ڜ*f ^2rw&YaFM{#^H_. jLޚW;K[N s>kVވ )Dua8cM{Tb>#⌢ pWL*mw m0Y}K&+5 䨁oZISCsiT`7B+e=+Ucwf4ܑH&5X<ڌ|npChFM6
+z49lYҽIyYjhb|a)2Tl\--:*WR%㛷8߬lAڒmD3KbOx*\E'^7(65:ofbWt'qi !.Ba5H2լJB̘(Ǭ\/nndwr}pݻqjZcn BV $rZ"?..w j^Y*y?Gf#2*Ov8kB].,&>b2T䂛Xg{R
`Aݬ\WS,Q쳎<]bĄYZbp)]?ҕnyW}Y%
+7:fKJ/I`&{: v<#9T&ܯ[R-ˎ =k.X-:u
+ndNy6kӬI S'Pm_g
C -,t$G&Gרop,BǬ\Q
+o0jbs0Y^wi㔍 ;ҶUaI{~Wr% &꾶?G_ܹ.l~SWEYS+%g@k 72 qf _b|$pQ 9tt`BW3z
a0g8:+X¶;J~OA{v Sz9)L@X}0 %O-gi͎6}Vc R ~3mm6淽oRZF:ϬiKB9bj30W
+"S =@ kc]˱hcş2P. qqX~m2( t#bf61A,- r*:\\1 ڑ+rNykZ͚ *~&K8 sn9J^۾ç i| eDMos?T&jub
Ù'Yp<\Q钟 J3B, 79W \!IW [\phpBwrlRUle=x~4fI?\b0s3[^kgƥoO0êL"2 rk
.s)).f )PAmGgFl'HlUУQf{*5HBX1gK\
;ʠ{0Vy6tV@ J/7y \ +ti_hRDMk PzOxϼf5~I
gsvDr,a\MwEBiJ̚Oh8F b
q h@Lt.@<(aGB.:|Y
P gƩ@>j; CҊj> #հt45f
+Xtpg=5R:/<h=
a[GǗ%4W| .Q
#lQ bKBue"H%oͯI + 5PZiF
m5Vj\_/Ix rTQ 鵻KGA"A! }~85d{_}=&9LCiiYϡ HY#8Y,C"zeY'ɂftQi Nu[4F5:l%9k
+eo⨨p{pT
@q]f%
+nv"@Ԅ =*_vo&r[x5S M"ծpK moߓ1lVL:\5=p?y?4CFbLZin
R3!YCp=_O5#6nNw%u;xƈ/[5; LOnщZ]#➅"^,R\,Jkac$sՅ;sC)0V/x^0>glu z=k܇spڑf&,D<Lh@2J($"{i*byu
+!hs+G] -S8=[h2aq;k֒x5#4@uEN?]5Z!L3c7&`W8 L75Ĉ+g=(&4 %=cH|)kNTٍRkaO=qL37gru织W{R㈡3v SEfR̐RfW
Z|LL%
+\+4s]:ʵR
Sa8h ѧ&K6N9 o
Vɦ{
+'Ơ{IdA& YEbhf}!G蓜P=Խh.n4;Zb ]◁g?DqFt$]n9 ?^0L68wMgvEA1!Khkķ?OR9Ԥa^䎒֙$k9D ){LwVێ;kozXއe-a;U3ԛ=DT]@` 11MGI"AiXlCk}kDT Uj\'9|O1vC Pjs #o+ꤑn|@Y+9j?"ubvk5a+$i
+ml#Jl"}U
H D8=*)# @,xUԤ0 H6cSW5-f1nLDr/rw٠̖#X~L3!/0>E@[TH]ѵK(eSVS Fm$- $` $skfr:|v&*P]`2?o #8,USuK<4 rcl~dCYzr3yrF@0d艽&< dI6QܪzWf?ĥ+~ Q85}%7y| ^5jl N"$(s\(1}ᅭV-'% "}aHL oϧ#fެŞ?RpdgK;ٔ}
+8t wp VƵdw2S&=GmVW =S05 iWueXsI4ߘ͔h(0jGaXy,/}J쯝t
+5f&C{7\K|cOM>(F̠I\#!Z(wjxL/xc1L2dan+RNvM] !c`m]a߉ h?bQXiv)dgS
+xq/4tOOSs/zi;I35A[GV ٌҔh@5ҧ_I1[""hƵkrq=#~J hghs#Z5. ayA'v-UjS#B|`Nf (! ΐUPL EXKU"_C;!09U?w<>IԸΠC-1{0]=K %6 CCJٙ3c%ڮДMيo
y)Qc0
Sbt$C n{$e:VlǴ8
+
xB0@ 6^9k7? ˏ?o?;? |;?V>??^&+B1 1%yV `WA4Dkq2k./:dlH+ϵ0BcWjhTޝunhlgy'yQ"SCɺ}5 ϮI|DyhKHHq0+=ٌ& n M9lC y)[tE)9-LIXwX|'15$^ڻ XZR3aIlf芩
+|lmYX>ܬ5RS%TP275uңםIdog -KChQw | ol Jڂ(B/ q &?:tXN K6K7of8X`fz\tx-zYia~`e :&XXkf`6t<"ް&a7sgEVvJSgTqw6ϭ%%*PZ5oKT"e~Nq2j6]&%Jt Yn@J`Bcs.E=1w5J ڌ]#p'FJcX%+ ;@p%{{5vG5"3NVu1GM;f jhI:y_r$۔d V,{--[Gjy$\7`˴2?[ɇx-1Otƞ jm<
+e
+[5my P= !*. u \R2Xl7ON26& @ dth U @qw!}IC-M|5^uԑX 0Ls]Y60*:/3` Ma Hf4cyI WH*L$*{T,1M;ta{A+T<3mu-ƪf)(
+讉rcީ.Q_N WtuRO1M > q^(y"l(ο\H=6'Hwiw1/}EHQb05 :P'%&ݫk~[F|4;kϢ>S$3s#D]:+lq(4/+[ }L+)5<IZ_FnЖ㳚 M7*D&3ҵd__ 픑O?溬gtq.Vk%6#3=p&s7) gδeOץߢ5~h'4\ eVﺎC(!٘5]x
ʝ<3i/ 52ݥ8&V]fdN7e$)t1,o'DBo-~ɰr+QaqA
+%q| P\iy?(BhO!U*W|r V6Zt,c.]Ņjl/@"kG [q7&Ԧ?[uE;?vw^~bոUTҞ] +mޞ}3X@Ae5לpY
+=ڜ>*f ^2rw&Y~aFM{#^H_. jLޚW;K[N s>kVވ )Duc8cM{Tb>#⌢$1ls} T\ X`A2Faf1"&+Y
7w$I/-6# v1Q Mg[lR^F5 mX
+ /+5wpK DʕTfb-7)$[Pd)̒S5
+W/t7.
+4
ƞ6YM۬Y[P$9-`vw1q8dMh4=9PF
ұzL5k﷼3918˨[3;ꮜs5\)c\V)Xۇe\경}!!p~~h ~ |?+yj6+i7j3,b1]S\+l/Z!,Ȼk5~jb%&O<|X)1a\iJt%[U_|ox~fw
$0[j h ;~#9T&<[R-ˎ 3k=kb8ܪ
.^
++YYƭī6EY
d)Vɇy!
W:#}v#kԷH8YZcg+ڸ<\2LVWSy8ecGŶmgX^2\C H5?>m+'w8"ȖZ7uE[4l5R
Vr-.'Lj1M,W u ȾN@
&zy:3GsV%lO~ V2(`OβrJ/'? 3DYf?~^I)_P6[snx+s%oPΠ&r
+'L/va 還=Odݯt ~2#x _SADr3cl40qq,*ePsVz^wX;T!v F`ztD .Li._(gjFb{8-qnAjݘJ=%߇+sVC? $.#NM¡Amނ0v- C1*HVp'_bGqGٱ+FBD6m.JWRc졆h\
;A{V jyڹ
P6h җn߱j^e^A͑uOOwUT
+$Kd#@ɣՈ{1 Oj`8%|x1"cѥt+)MK^s0A UBe-@!) Zr;ŰKC=zV160(AjW TGjKFg V wp B(,M^ , ZF6F㩡4KnLw a jS+^#&
\s\ ārͪyKiDG1VԜQ>&I'BzW161&9̅v2C=2q ,!}>4Լ'ɂZ^bTQ\ YN=
+ i s[[r4~CW*
+ ']34zh5.
o]}ՔH&p^IF LP&1:-T{c@yHaVP%\s7NNW%y:x'Oùlּ?ADtbgȟxdHW+[[j @ixFxĝ!GӒf.='}]V1
z]5>8NMX0 y. 0Ѐd-ΕPHD351<8RC9ÙΎWc;S8=7uwdW||Q)j =Кgj:|:kYZ!t3b7$]תy'Fp/F65b6kkUhdПU"x,IM+U?',A0}sdO;z~b(7ܫ
+J"PTH-_LΙto)1B(u:*'\+頎vNTC> bXm!ԤyWwzajDy߯dRB#cP5R$S Wj"14ڳ 3p#IN4a7@A
1a*e {O5Q7Ul9 ?^i0L68VM m+CZBBA`Q ܹ\BN=~=jEA!KLkjķ?OR{qPBy3JqZG>wrlR 7\{6tzzLDՑ}kbjF7?ߒcD1Dt~d/(E&ՏFD=_T p4ϏQ3 -X@~33|| tce|MԑwՄ5쒜
RhF 7 vU$^oHG[FxC6Ζ
+ĄS)JM:d36uUsW3¬~ fD SN7Oj"1l{ JoقWK7S K
iljбs
+6R0#:W %lho=6t D`ntΠ*1֫e :&|0>Ȣ\%9إ> /Iyp˳}Rn̐f wgS#{ƑiV# ]Xj܉&< dK6Qܪzת/q錁 rv$ Mᅁ_{F MéVdyc%'^Jcu'ĺ 2*fl- gL]V6ͮ 'Yyce[6lNʸ
+YKĺ盳+ua"tD>p]$R2obJ 4Q h 5G0WJr mAX5k&BҼ =k ꃢj\ )qvT'č p
++5B<ӱ&LsӟUlwQ5XpkcG8V"B`1ڭ,2 m4. 4yjB>^$
75\^#t+D )}##lFbiJ\@+}WRו.\59p iھb0W%gfƖ'dk9ң~Ss'WbdY5wBѰ7~lƔ3bT7ij4y uN Qu@朗'%1ܔnv;@c=,a: aդ)J_rjDJA DO>p7
^WdN Qy8X%Z
dWX5y,N8ΠCo.a:*=CZ(lԻ CCJ#c%UC)2 _i 8w2RF Q&3 0 \O!r-b?WMpM-&)P[}"8PhܦƋ +5\ٰGGӯ~~ok /~۾};nǾi@ ti'\"RuRbӽU{s3^oIvZ@tJ*|\u*k6I2`yOIפ 眚ui]l'-W,zm3'j:tPףl a$m\oӆ06ӌ9L-⊈۹ ,L,,1[K]ua{y J GӺ}D2)@ jql?WFu>Zkbj\]zqXIkL=ML+ba>M%38Fɰ:s8pywt)dZDr |@RQSfp =c;$;%2fb0EBO -@+
+\Rd O JSt*!R10n
UB>?YwU9b#hYL_ vXvZ M QX
+&c-sH߉q`~0^CD
+FP3e42s^ ?<0w`̥t6[cf'FJ)0'B0s e17 Wz"TJ栾kǃ0ɵ1ʇζ?aᜆu{-a>>oh+֪*~o$$l#&p;W650v38N0F2i2 l RTs0-Erl,w;
+vQvØ-ƀjOR?W* vlP?.>-05NQ[JYJ^#fO{{,k,/w|tgnFo`o˚ԭnbwW2@OOuUZ !c u=?x0heČX{kWjVrmm c\It{jѤ-47a _^u5s0FŻ'\ٷv~? qƽ[;^&RSַ`Ҽsk /o%ݍ%UmH*|$ @Xdƾ% Ez\ƛ"[ݷ)i&&"l&l%hIvi6MpAp(?#W{!.m2cudduSzO3_t3}7?-mcEב́{/9тhƕ.xS LU jyEcEl&mv* C N.i 0XlD0 ?.uA+)DdNh}ylYzK4fD+͂c($k`Bv 0 ;wq:U h>̑rd 5Q;O*oh10`ἡ0'ռ0t0k a Rr s:#S 骆 G=-qD/ A5BZb Yg (۽ Vv:i A0:"K)qw?y ~hf"Jt(y <%OQ"ߨ3gCwԙcdc;ϙ`$gpf~>J
+\@ (} 3.Ys[g<Æ iZcaP\$ҬzW־ H" h0H2V 畟Wi3[3l0V3XR SS݊ 틉Z pX%6pVw[d c8l]sϢ.kB o1V3/,LY/i)+z݇9p
+3c7Shh1!ŝ~#S %sI_ yHv8rVmd*za6qR>3t?g-0-BMa!X4Dd7[n?+V bs5
+گsw+g)^쀉Bt6Y 3Lo֗|^w_\s$<ܕM բvSx-粕iO1|Qi5b]ʼnO ݀SȱnaO2όx씂=ώzȔJ#;
+nwg?/*+jCnjzk9?/b?G7Pa|/c'ט-'[ˎ7-[V [I/b+:߸D`ʾc<`I٤#gX /{@N|~.}<{/kh%\{ TX[2Y',Sm Xg4y/~nyWBH9noP=seO.PΠ qcqV07Kb廻zk+}1Ym.Xe+sUDa\~HJ\|vb35Bju5"jdz_js <3ݷѯ/~amsj TOXTRETB0d&A1àyaKxFI{ Ӱ+Je\GT_ +u]u pfOF¦zFCrsؙ\'aG ա_E/2F h0&9OO "yޔ(anq -aٲob Yht ҝg sHVd%Xވ# Kq$xM_Z+ʂv3dSlcY.F<~M_䤭Ak E&>:Kv b(^A(N7 e`bf7e, ;eA1.^*QWweBz=9>^wBJ w9CH5nyqqS|*+?
yP1b4|=R2
k lI_,>_g MS:ln_hD]{%=v <ȧ=\ z% c"/ {vC!9v;bJso:;Fޝg tO>ews
>K I
"Au-uw%4;GY sIO9s_s=>y켞h 9rHřWwd
8V4Y3G9M&*gf 휫l}-Nn-Y Z@и Hs'iPS(rWNƊОc_F=_- Io!qLփΗ<ݫ ld}ʗ ҴkeY_3mY<ؕ YVܶ-'bP/soY7e0
+NP'eBD|VE4zWWC]bglL5l{X%qf(}wF)^"j U2ȟ|A4neI)$RTa{{/j1oo/mXk'ULekY m?DYx`KiF }oiɼe/NnKpoXK|e.jiZ n?|m5U96WƲڎhDg4ƻڲhDע vΩ<ַ'aq8:chpH{}fx=72R5 >v%qc}J(Yc "g^,)#h3| M
7 < "%J$ZEӥ*E0@h۽m4HU;щ(Ys dQ(bnP -7EvÛec5z4=Ҍa18G,A4wX! $"d PgהVS7 hz"_+M08ö Iă-Mۥ1Y
+[֑zBM y-%fQMu̘oIÄ^*Rk~ +H$z2J'q#^:B4;jpT"wVErfϣ0ܫw%.l$ h̔`1 %}QrW\å{5˥bra$\"O}g+jrPaD#Lک ^n1P]=Zr{ߚa8У1ΣA5 '
룉O;a:t Oh6eݮH/g y We`K)Ҟ#W{' \){i"I] +[K4]}4-)3?^s_3Hܷꭎ8 H^
0}M%M=U} -ؗU2ިeh#`Tm :L3ޕǹ/ wk"+lx:) T.=w,b/)# u` q=^iq1*^4.0"8pK3 g)k@je4]:AZ;6VwFPt4A82եgMv+C;ȢYU`}] 3UXFh c_F1
Lft2;HCh+. Y,cKє
as.1el<&s,q&NV4"Ύ%}3y˒PjTIwUJiٔX7lư^;L4w/7 Sw` f&~
endstream
endobj
24 0 obj
<>stream
+Hʥ9axMU%
7 "#:0 s>+ow{vϪU+ezx++ ӺGX+`ódKV2k^blxG[mYo\|WσIY=F/+aՖ}ԁT8nܘ|{F1˹>`;궦0@**19g`Rk^m ~/?~ן^竽['s_ҍ_˛ןB rhO8Ǡgi;x:݅ K1j|3)
+"$]fZ H䵄Ib|灘
u
i[,? S3D kM*1""Tr\Ud@TO}p cU9jCh 3x91 B]I9V $`xH ^aNkv ()>H3#MdLtn$[nnc PXp`1I'fҌ8Ϩ?l~6neXhxaRjFvw5Q9ccarqZ-3占HGdY~q!7C- g{.! ]KQF Lz7JHvZ ]D2mWA֙}ڗ߹;0WBya$f/#c(R}ڻf'IbWZYV ``\`ȒtI}scH^~Bf608]dszF}0)Tk,SCc'Ck!T 76CfA2RUEH
+j;ZcTJ3S̄|Q:aYAAgIZ@P1SAYqaI|0P2ɆL 5b G9aL f8B[)z'Ub 1 sOeKr95v+dQK?6~Maah߈aMmNR;ug=3䆴B8t% 6b&xV[)ɸ1~Gvcu{Zl( ڪwa5Vܫ:juqVY cP\ *);CPaI>~e!T/fW6wCYAIE:`XHpuɚN5o3
+D˚D|u-ˮDHSL:_ L Uu(TU
+`
+y^%5&[MAp"U[E u`moP2<eފֱepB3!R ־p>C;kZ[Xz,OȢ^lddFy+z} *Wc V=2hsRv7a@pju5s`,$WONje[ְyT ?|!.r`JS)Hjyq9oC\A
+Ыw>(,"Cl"y{ A_h]yWSJCՙWbhXc o&NG
CE^`vQ[U&M^W`Щ 9D_ kU07s]=!,.LEZZ`&u^h8 )LJ*Y D՟xiB UN2鴓`y#@@FWl H f.bQLN"^z%!RzHVX] x4+Ì$0ĕB0wNZRj9 |0Ms4+d4FcΆԶۺ4NiA/ineؑŞgM LWt:gk9 :( "j~ W
+nF
Ol FT!Pl@#i dTh!fe,&oV|f̒9֒C9 -_:^ LLaDDܘe:X>E xw=OL `l^T!g (}G^
+ (8asf[ՃY4cG=R+ Fӊ\Ex>t+#Qf#51 bh}]ElWo
f@BJhSFߚv^dc:|(no )#Z°,8dc4b5I22
+a~ Xrذ;?X+ 5AQ/Rp yY &~sI 7p\M̌6j
+YC;x.[f 1wcegJٹX N|zYh N!U='RF\R9W.GT \QX,6Ce/*?
+b5j9^17j2_~_8PJ&yRKl}Mˎ;V'͖R%0-rE Weg' SKa%eV#>gǃoM'Z.}@pڴv1Slc,z#._䤭]7r O4r :eA3.pUloEB nwuc tŸLvH䵃H:.m*<>J7q즒[}B HE
+uyRm❉p{u_> WrE,tC:C!=+e ߈~' 0ywD\x0n*;n9rb.bOv#bXc3{
+xU
;\˼3^s04Lw?k
+$
l z;=_q6!`M;
A}A\Q&ob &U(P{9-oLv.`s/*gᮀG<iF=hn9Te?`
8+ Fdc]i;NGŦFC
uJq/L 4)ߺ5"Jj 2#DW L͠:gV\gcgb-z C*ZV8rU{zխ&Z/Ceh_1X3hw[@2 3y, 18-n^Ֆғ+< g6~:&.l-Vy {QbؗKs5y}Kl3*ZsI-o#"eNX%74XѕHq.]Soi渝dD7{U._]vQؐhӽl.ٖHj8A.}ir"y5:y-:c7`SG@B2 :% tu[@JxyqC,B̘hH fJPdFXLE8+M=UBC\R*9GVOٜ4(@2q*Uw34dS$v*SC\'^VQX/UTFC}bRpo U A&L(S h;ndK#yG !4#^4T4 5{gAD}K.\cR {լ7oH|>sܥt,
+iQ<_wïf?4-OsåуK]Uzp `Ѿ> YB#~O! NQ2]S
yv[~K'ߡkLb va( O۽Lc-xϷ˶,?e]we^uQݗ*S<:bU
+q|{;` -
endstream
endobj
6 0 obj
[5 0 R]
endobj
25 0 obj
<>
endobj
xref
0 26
0000000000 65535 f
+0000000016 00000 n
+0000000144 00000 n
+0000025173 00000 n
+0000000000 00000 f
+0000065496 00000 n
+0000216446 00000 n
+0000025224 00000 n
+0000025562 00000 n
+0000065799 00000 n
+0000065686 00000 n
+0000064745 00000 n
+0000064935 00000 n
+0000064983 00000 n
+0000065570 00000 n
+0000065601 00000 n
+0000065872 00000 n
+0000066155 00000 n
+0000067473 00000 n
+0000085125 00000 n
+0000098214 00000 n
+0000119906 00000 n
+0000150354 00000 n
+0000180599 00000 n
+0000210222 00000 n
+0000216469 00000 n
+trailer
<<636425E0298441309A895498F62E903C>]>>
startxref
216662
%%EOF
\ No newline at end of file
diff --git a/docs/_static/get-started-garbled-output.png b/docs/_static/get-started-garbled-output.png
new file mode 100644
index 0000000000..2e6dd68ca3
Binary files /dev/null and b/docs/_static/get-started-garbled-output.png differ
diff --git a/docs/conf_common.py b/docs/conf_common.py
index 5fecc7a9fe..673d480ddd 100644
--- a/docs/conf_common.py
+++ b/docs/conf_common.py
@@ -19,16 +19,21 @@ from __future__ import unicode_literals
import sys
import os
import subprocess
+from sanitize_version import sanitize_version
+from get_github_rev import get_github_rev
+
# Note: If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute
-from local_util import run_cmd_get_output, copy_if_modified
+from local_util import copy_if_modified
# build_docs on the CI server sometimes fails under Python3. This is a workaround:
sys.setrecursionlimit(3500)
+config_dir = os.path.abspath(os.path.dirname(__file__))
+
try:
builddir = os.environ['BUILDDIR']
except KeyError:
@@ -142,6 +147,7 @@ suppress_warnings = ['image.nonlocal_uri']
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['breathe',
+ 'sphinx_idf_theme',
'link-roles',
'sphinxcontrib.blockdiag',
'sphinxcontrib.seqdiag',
@@ -150,6 +156,7 @@ extensions = ['breathe',
'sphinxcontrib.rackdiag',
'sphinxcontrib.packetdiag',
'html_redirects',
+ 'latex_builder',
]
# Set up font for blockdiag, nwdiag, rackdiag and packetdiag
@@ -192,16 +199,14 @@ master_doc = 'index'
# built documents.
#
-# Readthedocs largely ignores 'version' and 'release', and displays one of
-# 'latest', tag name, or branch name, depending on the build type.
-# Still, this is useful for non-RTD builds.
-# This is supposed to be "the short X.Y version", but it's the only version
+# This is the full exact version, canonical git version description
# visible when you open index.html.
-# Display full version to make things less confusing.
-version = run_cmd_get_output('git describe')
-# The full version, including alpha/beta/rc tags.
-# If needed, nearest tag is returned by 'git describe --abbrev=0'.
-release = version
+version = subprocess.check_output(['git', 'describe']).strip().decode('utf-8')
+
+# The 'release' version is the same as version for non-CI builds, but for CI
+# builds on a branch then it's replaced with the branch name
+release = sanitize_version(version)
+
print('Version: {0} Release: {1}'.format(version, release))
# There are two options for replacing |today|: either, you set today to some
@@ -232,6 +237,13 @@ exclude_patterns = ['_build','README.md']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
+# Extra options required by sphinx_idf_theme
+project_slug = 'esp-idf'
+versions_url = 'https://dl.espressif.com/dl/esp-idf/idf_versions.js'
+
+languages = ['en', 'zh_CN']
+
+
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
@@ -257,7 +269,15 @@ html_redirect_pages = [('api-reference/ethernet/index', 'api-reference/network/i
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinx_idf_theme'
+
+# context used by sphinx_idf_theme
+html_context = {
+ "display_github": True, # Add 'Edit on Github' link instead of 'View page source'
+ "github_user": "espressif",
+ "github_repo": "esp-idf",
+ "github_version": get_github_rev(),
+}
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@@ -340,28 +360,41 @@ htmlhelp_basename = 'ReadtheDocsTemplatedoc'
# -- Options for LaTeX output ---------------------------------------------
-latex_elements = {
- # The paper size ('letterpaper' or 'a4paper').
- # 'papersize': 'letterpaper',
- #
- # The font size ('10pt', '11pt' or '12pt').
- # 'pointsize': '10pt',
- #
- # Additional stuff for the LaTeX preamble.
- # 'preamble': '',
-}
+latex_template_dir = os.path.join(config_dir, 'latex_templates')
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-# author, documentclass [howto, manual, or own class]).
-latex_documents = [
- ('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation',
- u'Read the Docs', 'manual'),
-]
+preamble = ''
+with open(os.path.join(latex_template_dir, 'preamble.tex')) as f:
+ preamble = f.read()
+
+titlepage = ''
+with open(os.path.join(latex_template_dir, 'titlepage.tex')) as f:
+ titlepage = f.read()
+
+
+latex_elements = {
+ 'papersize': 'a4paper',
+
+ # Latex figure (float) alignment
+ 'figure_align':'htbp',
+
+ 'pointsize': '10pt',
+
+ # Additional stuff for the LaTeX preamble.
+ 'fncychap': '\\usepackage[Sonny]{fncychap}',
+
+ 'preamble': preamble,
+
+ 'maketitle': titlepage,
+}
# The name of an image file (relative to this directory) to place at the top of
# the title page.
-# latex_logo = None
+
+# The name of an image file (relative to this directory) to place at the bottom of
+# the title page.
+latex_logo = "../_static/espressif2.pdf"
+latex_engine = 'xelatex'
+latex_use_xindy = False
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
@@ -422,3 +455,24 @@ texinfo_documents = [
def setup(app):
app.add_stylesheet('theme_overrides.css')
generate_version_specific_includes(app)
+
+ # Not all config variables are set when setup is called
+ app.connect('config-inited', setup_config_values)
+ app.connect('config-inited', setup_html_context)
+
+
+def setup_config_values(app, config):
+ # Sets up global config values needed by other extensions
+ idf_target_title_dict = {
+ 'esp32': 'ESP32',
+ }
+
+ app.add_config_value('idf_target_title_dict', idf_target_title_dict, 'env')
+
+ pdf_name = "esp-idf-{}-{}-{}".format(app.config.language, app.config.version, "esp32")
+ app.add_config_value('pdf_file', pdf_name, 'env')
+
+
+def setup_html_context(app, config):
+ # Setup path for 'edit on github'-link
+ app.config.html_context['conf_py_path'] = "/docs/{}/".format(app.config.language)
diff --git a/docs/en/conf.py b/docs/en/conf.py
index cb77736dd3..f30829d2e0 100644
--- a/docs/en/conf.py
+++ b/docs/en/conf.py
@@ -16,7 +16,7 @@ except ImportError:
# General information about the project.
project = u'ESP-IDF Programming Guide'
-copyright = u'2016 - 2020, Espressif Systems (Shanghai) CO., LTD'
+copyright = u'2016 - 2021, Espressif Systems (Shanghai) CO., LTD'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/en/get-started-cmake/index.rst b/docs/en/get-started-cmake/index.rst
index 1d19dff7f0..c1467cfe78 100644
--- a/docs/en/get-started-cmake/index.rst
+++ b/docs/en/get-started-cmake/index.rst
@@ -82,14 +82,14 @@ If you have different board, move to sections below.
Step 1. Set up Toolchain
========================
-The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
+The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
.. toctree::
:hidden:
Windows
- Linux
- MacOS
+ Linux
+ MacOS
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
@@ -298,12 +298,12 @@ This command will compile the application and all the ESP-IDF components, genera
-- Building empty aws_iot component due to configuration
-- Component names: ...
-- Component paths: ...
-
+
... (more lines of build system output)
-
+
[527/527] Generating hello-world.bin
esptool.py v2.3.1
-
+
Project build complete. To flash, run this command:
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
or run 'idf.py -p PORT flash'
@@ -352,7 +352,7 @@ This step will flash the binaries that you just built to your ESP32 board.
Compressed 136672 bytes to 67544...
Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
Hash of data verified.
-
+
Leaving...
Hard resetting via RTS pin...
@@ -393,14 +393,13 @@ Several lines below, after start up and diagnostic log, you should see "Hello wo
To exit the monitor use shortcut ``Ctrl+]``.
-.. note::
+If instead of the messages above, you see a random garbage similar to what is shown below, or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
- If instead of the messages above, you see a random garbage similar to::
+.. figure:: ../../_static/get-started-garbled-output.png
+ :align: center
+ :alt: Garbled output
+ :figclass: align-center
- e���)(Xn@�y.!��(�PW+)��Hn9a/9�!�t5��P�~�k��e�ea�5�jA
- ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
-
- or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
.. note::
diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst
index db0bc0ce5a..cbb0cd8f8a 100644
--- a/docs/en/get-started/index.rst
+++ b/docs/en/get-started/index.rst
@@ -1,376 +1,375 @@
-***********
-Get Started
-***********
-:link_to_translation:`zh_CN:[中文]`
-
-This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
-
-.. include:: /_build/inc/version-note.inc
-
-Introduction
-============
-
-ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
-
-Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
-
-
-What You Need
-=============
-
-To develop applications for ESP32 you need:
-
-* **PC** loaded with either Windows, Linux or Mac operating system
-* **Toolchain** to build the **Application** for ESP32
-* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
-* A text editor to write programs (**Projects**) in C, e.g. `Eclipse `_
-* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
-
-.. figure:: ../../_static/what-you-need.png
- :align: center
- :alt: Development of applications for ESP32
- :figclass: align-center
-
- Development of applications for ESP32
-
-Preparation of development environment consists of three steps:
-
-1. Setup of **Toolchain**
-2. Getting of **ESP-IDF** from GitHub
-3. Installation and configuration of **Eclipse**
-
-You may skip the last step, if you prefer to use different editor.
-
-Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
-
-1. Configuration of a **Project** and writing the code
-2. Compilation of the **Project** and linking it to build an **Application**
-3. Flashing (uploading) of the **Application** to **ESP32**
-4. Monitoring / debugging of the **Application**
-
-See instructions below that will walk you through these steps.
-
-
-Guides
-======
-
-If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
-
-.. toctree::
- :maxdepth: 1
-
- ESP32 DevKitC
- ESP-WROVER-KIT
- ESP32-PICO-KIT
-
-If you have different board, move to sections below.
-
-
-.. _get-started-setup-toolchain:
-
-Setup Toolchain
-===============
-
-The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
-
-.. toctree::
- :hidden:
-
- Windows
- Linux
- MacOS
-
-+-------------------+-------------------+-------------------+
-| |windows-logo| | |linux-logo| | |macos-logo| |
-+-------------------+-------------------+-------------------+
-| `Windows`_ | `Linux`_ | `Mac OS`_ |
-+-------------------+-------------------+-------------------+
-
-.. |windows-logo| image:: ../../_static/windows-logo.png
- :target: ../get-started/windows-setup.html
-
-.. |linux-logo| image:: ../../_static/linux-logo.png
- :target: ../get-started/linux-setup.html
-
-.. |macos-logo| image:: ../../_static/macos-logo.png
- :target: ../get-started/macos-setup.html
-
-.. _Windows: ../get-started/windows-setup.html
-.. _Linux: ../get-started/linux-setup.html
-.. _Mac OS: ../get-started/macos-setup.html
-
-.. note::
-
- We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
-
-Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
-
-Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
-
-
-.. _get-started-get-esp-idf:
-
-Get ESP-IDF
-===========
-
-.. highlight:: bash
-
-Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_.
-
-To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command:
-
-.. include:: /_build/inc/git-clone-bash.inc
-
-ESP-IDF will be downloaded into ``~/esp/esp-idf``.
-
-Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
-
-.. include:: /_build/inc/git-clone-notes.inc
-
-.. note::
-
- Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
-
- cd esp-idf
- git submodule update --init --recursive
-
-.. _get-started-setup-path:
-
-Setup Path to ESP-IDF
-=====================
-
-The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`.
-
-.. _get-started-get-packages:
-
-Install the Required Python Packages
-====================================
-
-Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running::
-
- python -m pip install --user -r $IDF_PATH/requirements.txt
-
-.. note::
-
- Please invoke that version of the Python interpreter which you will be using with ESP-IDF. The version of the
- interpreter can be checked by running command ``python --version`` and depending on the result, you might want to
- use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.::
-
- python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
-
-.. _get-started-start-project:
-
-Start a Project
-===============
-
-Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
-
-Copy :example:`get-started/hello_world` to ``~/esp`` directory::
-
- cd ~/esp
- cp -r $IDF_PATH/examples/get-started/hello_world .
-
-You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
-
-.. important::
-
- The esp-idf build system does not support spaces in paths to esp-idf or to projects.
-
-
-.. _get-started-connect:
-
-Connect
-=======
-
-You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
-
-
-.. _get-started-configure:
-
-Configure
-=========
-
-Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
-
- cd ~/esp/hello_world
- make menuconfig
-
-If previous steps have been done correctly, the following menu will be displayed:
-
-.. figure:: ../../_static/project-configuration.png
- :align: center
- :alt: Project configuration - Home window
- :figclass: align-center
-
- Project configuration - Home window
-
-In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
-
-.. note::
-
- On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
- (See :doc:`establish-serial-connection` for full details.)
-
-Here are couple of tips on navigation and use of ``menuconfig``:
-
-* Use up & down arrow keys to navigate the menu.
-* Use Enter key to go into a submenu, Escape key to go out or to exit.
-* Type ``?`` to see a help screen. Enter key exits the help screen.
-* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
-* Pressing ``?`` while highlighting a configuration item displays help about that item.
-* Type ``/`` to search the configuration items.
-
-.. note::
-
- If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
-
-
-.. attention::
-
- When using ESP32-DevKitC board with ESP32-SOLO-1 module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing example applications.
-
-
-.. _get-started-build-flash:
-
-Build and Flash
-===============
-
-Now you can build and flash the application. Run::
-
- make flash
-
-This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
-
-.. highlight:: none
-
-::
-
- esptool.py v2.0-beta2
- Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
- esptool.py v2.0-beta2
- Connecting........___
- Uploading stub...
- Running stub...
- Stub running...
- Changing baud rate to 921600
- Changed.
- Attaching SPI flash...
- Configuring flash size...
- Auto-detected Flash size: 4MB
- Flash params set to 0x0220
- Compressed 11616 bytes to 6695...
- Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
- Hash of data verified.
- Compressed 408096 bytes to 171625...
- Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
- Hash of data verified.
- Compressed 3072 bytes to 82...
- Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
- Hash of data verified.
-
- Leaving...
- Hard resetting...
-
-If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
-
-If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `.
-
-
-.. _get-started-build-monitor:
-
-Monitor
-=======
-
-To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor ` application::
-
- $ make monitor
- MONITOR
- --- idf_monitor on /dev/ttyUSB0 115200 ---
- --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
- ets Jun 8 2016 00:22:57
-
- rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
- ets Jun 8 2016 00:22:57
- ...
-
-Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
-
- ...
- Hello world!
- Restarting in 10 seconds...
- I (211) cpu_start: Starting scheduler on APP CPU.
- Restarting in 9 seconds...
- Restarting in 8 seconds...
- Restarting in 7 seconds...
-
-To exit the monitor use shortcut ``Ctrl+]``.
-
-.. note::
-
- If instead of the messages above, you see a random garbage similar to::
-
- e���)(Xn@�y.!��(�PW+)��Hn9a/9�!�t5��P�~�k��e�ea�5�jA
- ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
-
- or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
-
-To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application.
-
-That's all what you need to get started with ESP32!
-
-Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
-
-
-Environment Variables
-=====================
-
-Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without needing to reconfigure them using** ``make menuconfig``.
-
-+-----------------+--------------------------------------------------------------+
-| Variables | Description & Usage |
-+=================+==============================================================+
-| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. |
-| | |
-| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, |
-| | ``make monitor ESPPORT=COM1`` |
-+-----------------+--------------------------------------------------------------+
-| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. |
-| | |
-| | Example: ``make flash ESPBAUD=9600`` |
-+-----------------+--------------------------------------------------------------+
-| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. |
-| | |
-| | Example: ``make monitor MONITORBAUD=9600`` |
-+-----------------+--------------------------------------------------------------+
-
-.. note::
- Users can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``).
- All subsequent calls of ``make`` within the same terminal session will use
- the exported value given that the variable is not simultaneously overridden.
-
-Updating ESP-IDF
-================
-
-After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
-
-If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location.
-
-Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `.
-
-
-Related Documents
-=================
-
-.. toctree::
- :maxdepth: 1
-
- add-idf_path-to-profile
- establish-serial-connection
- make-project
- eclipse-setup
- idf-monitor
- toolchain-setup-scratch
-
-.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
-.. _Releases page: https://github.com/espressif/esp-idf/releases
-
+***********
+Get Started
+***********
+:link_to_translation:`zh_CN:[中文]`
+
+This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
+
+.. include:: /_build/inc/version-note.inc
+
+Introduction
+============
+
+ESP32 integrates Wi-Fi (2.4 GHz band) and Bluetooth 4.2 solutions on a single chip, along with dual high performance cores, Ultra Low Power co-processor and several peripherals. Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform to meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
+
+Espressif provides the basic hardware and software resources that help application developers to build their ideas around the ESP32 series hardware. The software development framework by Espressif is intended for rapidly developing Internet-of-Things (IoT) applications, with Wi-Fi, Bluetooth, power management and several other system features.
+
+
+What You Need
+=============
+
+To develop applications for ESP32 you need:
+
+* **PC** loaded with either Windows, Linux or Mac operating system
+* **Toolchain** to build the **Application** for ESP32
+* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
+* A text editor to write programs (**Projects**) in C, e.g. `Eclipse `_
+* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
+
+.. figure:: ../../_static/what-you-need.png
+ :align: center
+ :alt: Development of applications for ESP32
+ :figclass: align-center
+
+ Development of applications for ESP32
+
+Preparation of development environment consists of three steps:
+
+1. Setup of **Toolchain**
+2. Getting of **ESP-IDF** from GitHub
+3. Installation and configuration of **Eclipse**
+
+You may skip the last step, if you prefer to use different editor.
+
+Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
+
+1. Configuration of a **Project** and writing the code
+2. Compilation of the **Project** and linking it to build an **Application**
+3. Flashing (uploading) of the **Application** to **ESP32**
+4. Monitoring / debugging of the **Application**
+
+See instructions below that will walk you through these steps.
+
+
+Guides
+======
+
+If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
+
+.. toctree::
+ :maxdepth: 1
+
+ ESP32 DevKitC
+ ESP-WROVER-KIT
+ ESP32-PICO-KIT
+
+If you have different board, move to sections below.
+
+
+.. _get-started-setup-toolchain:
+
+Setup Toolchain
+===============
+
+The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
+
+.. toctree::
+ :hidden:
+
+ Windows
+ Linux
+ MacOS
+
++-------------------+-------------------+-------------------+
+| |windows-logo| | |linux-logo| | |macos-logo| |
++-------------------+-------------------+-------------------+
+| `Windows`_ | `Linux`_ | `Mac OS`_ |
++-------------------+-------------------+-------------------+
+
+.. |windows-logo| image:: ../../_static/windows-logo.png
+ :target: ../get-started/windows-setup.html
+
+.. |linux-logo| image:: ../../_static/linux-logo.png
+ :target: ../get-started/linux-setup.html
+
+.. |macos-logo| image:: ../../_static/macos-logo.png
+ :target: ../get-started/macos-setup.html
+
+.. _Windows: ../get-started/windows-setup.html
+.. _Linux: ../get-started/linux-setup.html
+.. _Mac OS: ../get-started/macos-setup.html
+
+.. note::
+
+ We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
+
+Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
+
+Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
+
+
+.. _get-started-get-esp-idf:
+
+Get ESP-IDF
+===========
+
+.. highlight:: bash
+
+Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository `_.
+
+To obtain a local copy: open terminal, navigate to the directory you want to put ESP-IDF, and clone the repository using ``git clone`` command:
+
+.. include:: /_build/inc/git-clone-bash.inc
+
+ESP-IDF will be downloaded into ``~/esp/esp-idf``.
+
+Consult :doc:`/versions` for information about which version of ESP-IDF to use in a given situation.
+
+.. include:: /_build/inc/git-clone-notes.inc
+
+.. note::
+
+ Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
+
+ cd esp-idf
+ git submodule update --init --recursive
+
+.. _get-started-setup-path:
+
+Setup Path to ESP-IDF
+=====================
+
+The toolchain programs access ESP-IDF using ``IDF_PATH`` environment variable. This variable should be set up on your PC, otherwise projects will not build. Setting may be done manually, each time PC is restarted. Another option is to set up it permanently by defining ``IDF_PATH`` in user profile. To do so, follow instructions specific to :ref:`Windows ` , :ref:`Linux and MacOS ` in section :doc:`add-idf_path-to-profile`.
+
+.. _get-started-get-packages:
+
+Install the Required Python Packages
+====================================
+
+Python packages required by ESP-IDF are located in the ``$IDF_PATH/requirements.txt`` file. You can install them by running::
+
+ python -m pip install --user -r $IDF_PATH/requirements.txt
+
+.. note::
+
+ Please invoke that version of the Python interpreter which you will be using with ESP-IDF. The version of the
+ interpreter can be checked by running command ``python --version`` and depending on the result, you might want to
+ use ``python2``, ``python2.7`` or similar instead of ``python``, e.g.::
+
+ python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
+
+.. _get-started-start-project:
+
+Start a Project
+===============
+
+Now you are ready to prepare your application for ESP32. To start off quickly, we will use :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
+
+Copy :example:`get-started/hello_world` to ``~/esp`` directory::
+
+ cd ~/esp
+ cp -r $IDF_PATH/examples/get-started/hello_world .
+
+You can also find a range of example projects under the :idf:`examples` directory in ESP-IDF. These example project directories can be copied in the same way as presented above, to begin your own projects.
+
+.. important::
+
+ The esp-idf build system does not support spaces in paths to esp-idf or to projects.
+
+
+.. _get-started-connect:
+
+Connect
+=======
+
+You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
+
+
+.. _get-started-configure:
+
+Configure
+=========
+
+Being in terminal window, go to directory of ``hello_world`` application by typing ``cd ~/esp/hello_world``. Then start project configuration utility ``menuconfig``::
+
+ cd ~/esp/hello_world
+ make menuconfig
+
+If previous steps have been done correctly, the following menu will be displayed:
+
+.. figure:: ../../_static/project-configuration.png
+ :align: center
+ :alt: Project configuration - Home window
+ :figclass: align-center
+
+ Project configuration - Home window
+
+In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit application by selecting ``< Exit >``.
+
+.. note::
+
+ On Windows, serial ports have names like COM1. On MacOS, they start with ``/dev/cu.``. On Linux, they start with ``/dev/tty``.
+ (See :doc:`establish-serial-connection` for full details.)
+
+Here are couple of tips on navigation and use of ``menuconfig``:
+
+* Use up & down arrow keys to navigate the menu.
+* Use Enter key to go into a submenu, Escape key to go out or to exit.
+* Type ``?`` to see a help screen. Enter key exits the help screen.
+* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
+* Pressing ``?`` while highlighting a configuration item displays help about that item.
+* Type ``/`` to search the configuration items.
+
+.. note::
+
+ If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
+
+
+.. attention::
+
+ When using ESP32-DevKitC board with ESP32-SOLO-1 module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing example applications.
+
+
+.. _get-started-build-flash:
+
+Build and Flash
+===============
+
+Now you can build and flash the application. Run::
+
+ make flash
+
+This will compile the application and all the ESP-IDF components, generate bootloader, partition table, and application binaries, and flash these binaries to your ESP32 board.
+
+.. highlight:: none
+
+::
+
+ esptool.py v2.0-beta2
+ Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
+ esptool.py v2.0-beta2
+ Connecting........___
+ Uploading stub...
+ Running stub...
+ Stub running...
+ Changing baud rate to 921600
+ Changed.
+ Attaching SPI flash...
+ Configuring flash size...
+ Auto-detected Flash size: 4MB
+ Flash params set to 0x0220
+ Compressed 11616 bytes to 6695...
+ Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
+ Hash of data verified.
+ Compressed 408096 bytes to 171625...
+ Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
+ Hash of data verified.
+ Compressed 3072 bytes to 82...
+ Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
+ Hash of data verified.
+
+ Leaving...
+ Hard resetting...
+
+If there are no issues, at the end of build process, you should see messages describing progress of loading process. Finally, the end module will be reset and "hello_world" application will start.
+
+If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide `.
+
+
+.. _get-started-build-monitor:
+
+Monitor
+=======
+
+To see if "hello_world" application is indeed running, type ``make monitor``. This command is launching :doc:`IDF Monitor ` application::
+
+ $ make monitor
+ MONITOR
+ --- idf_monitor on /dev/ttyUSB0 115200 ---
+ --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+ ets Jun 8 2016 00:22:57
+
+ rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
+ ets Jun 8 2016 00:22:57
+ ...
+
+Several lines below, after start up and diagnostic log, you should see "Hello world!" printed out by the application. ::
+
+ ...
+ Hello world!
+ Restarting in 10 seconds...
+ I (211) cpu_start: Starting scheduler on APP CPU.
+ Restarting in 9 seconds...
+ Restarting in 8 seconds...
+ Restarting in 7 seconds...
+
+To exit the monitor use shortcut ``Ctrl+]``.
+
+If instead of the messages above, you see a random garbage similar to what is shown below, or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig `, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash ` the application again. This is found under ``make menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
+
+.. figure:: ../../_static/get-started-garbled-output.png
+ :align: center
+ :alt: Garbled output
+ :figclass: align-center
+
+
+To execute ``make flash`` and ``make monitor`` in one go, type ``make flash monitor``. Check section :doc:`IDF Monitor ` for handy shortcuts and more details on using this application.
+
+That's all what you need to get started with ESP32!
+
+Now you are ready to try some other :idf:`examples`, or go right to developing your own applications.
+
+
+Environment Variables
+=====================
+
+Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without needing to reconfigure them using** ``make menuconfig``.
+
++-----------------+--------------------------------------------------------------+
+| Variables | Description & Usage |
++=================+==============================================================+
+| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. |
+| | |
+| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, |
+| | ``make monitor ESPPORT=COM1`` |
++-----------------+--------------------------------------------------------------+
+| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. |
+| | |
+| | Example: ``make flash ESPBAUD=9600`` |
++-----------------+--------------------------------------------------------------+
+| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. |
+| | |
+| | Example: ``make monitor MONITORBAUD=9600`` |
++-----------------+--------------------------------------------------------------+
+
+.. note::
+ Users can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``).
+ All subsequent calls of ``make`` within the same terminal session will use
+ the exported value given that the variable is not simultaneously overridden.
+
+Updating ESP-IDF
+================
+
+After some time of using ESP-IDF, you may want to update it to take advantage of new features or bug fixes. The simplest way to do so is by deleting existing ``esp-idf`` folder and cloning it again, exactly as when doing initial installation described in sections :ref:`get-started-get-esp-idf`.
+
+If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts know where to find the ESP-IDF in its release specific location.
+
+Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `.
+
+
+Related Documents
+=================
+
+.. toctree::
+ :maxdepth: 1
+
+ add-idf_path-to-profile
+ establish-serial-connection
+ make-project
+ eclipse-setup
+ idf-monitor
+ toolchain-setup-scratch
+
+.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
+.. _Releases page: https://github.com/espressif/esp-idf/releases
+
diff --git a/docs/gen-version-specific-includes.py b/docs/gen-version-specific-includes.py
index 6bd377c4b1..1e2ae4fbbc 100755
--- a/docs/gen-version-specific-includes.py
+++ b/docs/gen-version-specific-includes.py
@@ -189,34 +189,29 @@ def write_version_note(template, out_dir, version, ver_type, is_stable):
def get_version():
"""
- Returns a tuple of (name of branch/tag, type branch/tag, is_stable)
+ Returns a tuple of (name of branch/tag/commit-id, type branch/tag/commit, is_stable)
"""
- # Trust what RTD says our version is, if it is set
- version = os.environ.get("READTHEDOCS_VERSION", None)
- if version == "latest":
- return ("master", "branch", False)
-
- # Otherwise, use git to look for a tag
+ # Use git to look for a tag
try:
- tag = subprocess.check_output(["git", "describe", "--exact-match"]).strip()
+ tag = subprocess.check_output(["git", "describe", "--exact-match"]).strip().decode('utf-8')
is_stable = re.match(r"v[0-9\.]+$", tag) is not None
return (tag, "tag", is_stable)
except subprocess.CalledProcessError:
pass
- # No tag, look for a branch
- refs = subprocess.check_output(["git", "for-each-ref", "--points-at", "HEAD", "--format", "%(refname)"])
- print("refs:\n%s" % refs)
- refs = refs.split(b"\n")
- # Note: this looks for branches in 'origin' because GitLab CI doesn't check out a local branch
- branches = [r.replace(b"refs/remotes/origin/",b"").strip() for r in refs if r.startswith(b"refs/remotes/origin/")]
- if len(branches) == 0:
- # last resort, return the commit (may happen on Gitlab CI sometimes, unclear why)
- return (subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]).strip(), "commit", False)
- if "master" in branches:
- return ("master", "branch", False)
- else:
- return (branches[0], "branch", False) # take whatever the first branch is
+ # No tag, look at branch name from CI, this will give the correct branch name even if the ref for the branch we
+ # merge into has moved forward before the pipeline runs
+ branch = os.environ.get("CI_COMMIT_REF_NAME", None)
+ if branch is not None:
+ return (branch, "branch", False)
+
+ # Try to find the branch name even if docs are built locally
+ branch = subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"]).strip().decode('utf-8')
+ if branch != "HEAD":
+ return (branch, "branch", False)
+
+ # As a last resort we return commit SHA-1, should never happen in CI/docs that should be published
+ return (subprocess.check_output(["git", "rev-parse", "--short", "HEAD"]).strip().decode('utf-8'), "commit", False)
if __name__ == "__main__":
diff --git a/docs/get_github_rev.py b/docs/get_github_rev.py
new file mode 100644
index 0000000000..7dc2da5635
--- /dev/null
+++ b/docs/get_github_rev.py
@@ -0,0 +1,15 @@
+import subprocess
+
+
+# Get revision used for constructing github URLs
+def get_github_rev():
+ path = subprocess.check_output(['git', 'rev-parse', '--short', 'HEAD']).strip().decode('utf-8')
+ try:
+ tag = subprocess.check_output(['git', 'describe', '--exact-match']).strip().decode('utf-8')
+ except subprocess.CalledProcessError:
+ tag = None
+ print('Git commit ID: ', path)
+ if tag:
+ print('Git tag: ', tag)
+ return tag
+ return path
diff --git a/docs/latex_builder.py b/docs/latex_builder.py
new file mode 100644
index 0000000000..270eb594f1
--- /dev/null
+++ b/docs/latex_builder.py
@@ -0,0 +1,55 @@
+from sphinx.builders.latex import LaTeXBuilder
+import os
+
+
+# Overrides the default Sphinx latex build
+class IdfLatexBuilder(LaTeXBuilder):
+
+ def __init__(self, app):
+
+ # Sets up the latex_documents config value, done here instead of conf.py since it depends on the runtime value 'idf_target'
+ self.init_latex_documents(app)
+
+ super().__init__(app)
+
+ def init_latex_documents(self, app):
+
+ file_name = app.config.pdf_file + '.tex'
+
+ if app.config.language == 'zh_CN':
+ latex_documents = [('index', file_name, u'ESP-IDF 编程指南', u'乐鑫信息科技', 'manual')]
+ else:
+ # Default to english naming
+ latex_documents = [('index', file_name, u'ESP-IDF Programming Guide', u'Espressif Systems', 'manual')]
+
+ app.config.latex_documents = latex_documents
+
+ def prepare_latex_macros(self, package_path, config):
+
+ PACKAGE_NAME = "espidf.sty"
+ latex_package = ''
+ with open(package_path, 'r') as template:
+
+ latex_package = template.read()
+
+ idf_target_title = "ESP32"
+ latex_package = latex_package.replace('', idf_target_title)
+
+ # Release name for the PDF front page, remove '_' as this is used for subscript in Latex
+ idf_release_name = "Release {}".format(config.version.replace('_', '-'))
+ latex_package = latex_package.replace('', idf_release_name)
+
+ with open(os.path.join(self.outdir, PACKAGE_NAME), 'w') as package_file:
+ package_file.write(latex_package)
+
+ def finish(self):
+ super().finish()
+
+ TEMPLATE_PATH = "../latex_templates/espidf.sty"
+ self.prepare_latex_macros(os.path.join(self.confdir,TEMPLATE_PATH), self.config)
+
+
+def setup(app):
+ app.add_builder(IdfLatexBuilder, override=True)
+
+ return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'}
diff --git a/docs/latex_templates/espidf.sty b/docs/latex_templates/espidf.sty
new file mode 100644
index 0000000000..a41f764060
--- /dev/null
+++ b/docs/latex_templates/espidf.sty
@@ -0,0 +1,7 @@
+\NeedsTeXFormat{LaTeX2e}[1995/12/01]
+\ProvidesPackage{espidf}[2020/03/25 v0.1.0 LaTeX package (ESP-IDF markup)]
+
+\newcommand{\idfTarget}{}
+\newcommand{\idfReleaseName}{}
+
+\endinput
\ No newline at end of file
diff --git a/docs/latex_templates/preamble.tex b/docs/latex_templates/preamble.tex
new file mode 100644
index 0000000000..67d4890599
--- /dev/null
+++ b/docs/latex_templates/preamble.tex
@@ -0,0 +1,129 @@
+% package with esp-idf specific macros
+\usepackage{espidf}
+
+\setcounter{secnumdepth}{2}
+\setcounter{tocdepth}{2}
+
+\usepackage{amsmath,amsfonts,amssymb,amsthm}
+\usepackage{graphicx}
+%%% reduce spaces for Table of contents, figures and tables
+%%% it is used "\addtocontents{toc}{\vskip -1.2cm}" etc. in the document
+\usepackage[notlot,nottoc,notlof]{}
+
+\usepackage{color}
+\usepackage{transparent}
+\usepackage{eso-pic}
+\usepackage{lipsum}
+
+%%% Needed for displaying Chinese in English documentation
+\usepackage{xeCJK}
+
+\usepackage{footnotebackref} %%link at the footnote to go to the place of footnote in the text
+
+%% spacing between line
+\usepackage{setspace}
+\singlespacing
+
+
+\definecolor{myred}{RGB}{229, 32, 26}
+\definecolor{mygrayy}{RGB}{127, 127, 127}
+\definecolor{myblack}{RGB}{64, 64, 64}
+
+
+%%%%%%%%%%% datetime
+\usepackage{datetime}
+
+\newdateformat{MonthYearFormat}{%
+ \monthname[\THEMONTH], \THEYEAR}
+
+
+%% RO, LE will not work for 'oneside' layout.
+%% Change oneside to twoside in document class
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+\fancyhf{}
+
+% Header and footer
+\makeatletter
+ \fancypagestyle{normal}{
+ \fancyhf{}
+ \fancyhead[L]{\nouppercase{\leftmark}}
+ \fancyfoot[C]{\py@HeaderFamily\thepage \\ \href{https://www.espressif.com/en/company/documents/documentation_feedback?docId=4287§ions=&version=\idfReleaseName}{Submit Document Feedback}}
+ \fancyfoot[L]{Espressif Systems}
+ \fancyfoot[R]{\idfReleaseName}
+ \renewcommand{\headrulewidth}{0.4pt}
+ \renewcommand{\footrulewidth}{0.4pt}
+ }
+\makeatother
+
+\renewcommand{\headrulewidth}{0.5pt}
+\renewcommand{\footrulewidth}{0.5pt}
+
+
+% Define a spacing for section, subsection and subsubsection
+% http://tex.stackexchange.com/questions/108684/spacing-before-and-after-section-titles
+
+\titlespacing*{\section}{0pt}{6pt plus 0pt minus 0pt}{6pt plus 0pt minus 0pt}
+\titlespacing*{\subsection}{0pt}{18pt plus 64pt minus 0pt}{0pt}
+\titlespacing*{\subsubsection}{0pt}{12pt plus 0pt minus 0pt}{0pt}
+\titlespacing*{\paragraph} {0pt}{3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}
+\titlespacing*{\subparagraph} {0pt}{3.25ex plus 1ex minus .2ex}{1.5ex plus .2ex}
+
+% Define the colors of table of contents
+% This is helpful to understand http://tex.stackexchange.com/questions/110253/what-the-first-argument-for-lsubsection-actually-is
+\definecolor{LochmaraColor}{HTML}{1020A0}
+
+% Hyperlinks
+\hypersetup{
+ colorlinks = true,
+ allcolors = {LochmaraColor},
+}
+
+
+\RequirePackage{tocbibind} %%% comment this to remove page number for following
+\addto\captionsenglish{\renewcommand{\contentsname}{Table of contents}}
+\addto\captionsenglish{\renewcommand{\listfigurename}{List of figures}}
+\addto\captionsenglish{\renewcommand{\listtablename}{List of tables}}
+% \addto\captionsenglish{\renewcommand{\chaptername}{Chapter}}
+
+
+
+
+%%reduce spacing for itemize
+\usepackage{enumitem}
+\setlist{nosep}
+
+%%%%%%%%%%% Quote Styles at the top of chapter
+\usepackage{epigraph}
+\setlength{\epigraphwidth}{0.8\columnwidth}
+\newcommand{\chapterquote}[2]{\epigraphhead[60]{\epigraph{\textit{#1}}{\textbf {\textit{--#2}}}}}
+%%%%%%%%%%% Quote for all places except Chapter
+\newcommand{\sectionquote}[2]{{\quote{\textit{``#1''}}{\textbf {\textit{--#2}}}}}
+
+% Insert 22pt white space before roc title. \titlespacing at line 65 changes it by -22 later on.
+\renewcommand*\contentsname{\hspace{0pt}Contents}
+
+
+% Define section, subsection and subsubsection font size and color
+\usepackage{sectsty}
+\definecolor{AllportsColor}{HTML}{A02010}
+\allsectionsfont{\color{AllportsColor}}
+
+\usepackage{titlesec}
+\titleformat{\section}
+{\color{AllportsColor}\LARGE\bfseries}{\thesection.}{1em}{}
+
+\titleformat{\subsection}
+{\color{AllportsColor}\Large\bfseries}{\thesubsection.}{1em}{}
+
+\titleformat{\subsubsection}
+{\color{AllportsColor}\large\bfseries}{\thesubsubsection.}{1em}{}
+
+\titleformat{\paragraph}
+{\color{AllportsColor}\large\bfseries}{\theparagraph}{1em}{}
+
+\titleformat{\subparagraph}
+ {\normalfont\normalsize\bfseries}{\thesubparagraph}{1em}{}
+
+\titleformat{\subsubparagraph}
+ {\normalfont\normalsize\bfseries}{\thesubsubparagraph}{1em}{}
diff --git a/docs/latex_templates/titlepage.tex b/docs/latex_templates/titlepage.tex
new file mode 100644
index 0000000000..768362366f
--- /dev/null
+++ b/docs/latex_templates/titlepage.tex
@@ -0,0 +1,39 @@
+\makeatletter
+\newgeometry{left=0cm,right=0cm,bottom=2cm}
+
+
+\cfoot{www.espressif.com}
+
+\renewcommand{\headrulewidth}{0pt}
+
+{\color{myred}\rule{30pt}{2.1cm}}
+ \hspace{0.2cm}
+ \begin{minipage}[b]{18cm}
+ {\fontsize{36pt}{48pt}\textbf{\idfTarget}}\\
+
+ {\fontsize{28pt}{18pt}\textbf{\color{mygrayy}\@title}}
+ \end{minipage}
+ \hspace{\stretch{1}}
+
+\vspace{48em}
+
+
+\begin{flushright}
+ \setlength\parindent{8em}
+ \begin{minipage}[b]{2cm}
+ \sphinxlogo
+ \end{minipage}
+ \hspace{0.2cm}
+ \rule{3pt}{1.9cm}
+ \hspace{0.2cm}
+ \begin{minipage}[b]{7cm}
+ {\large{\idfReleaseName}}\smallskip\newline
+ {\large{\@author}}\smallskip\newline
+ {\large{\@date}}\smallskip
+ \end{minipage}
+ {\color{myred}\rule{30pt}{1.9cm}}
+\end{flushright}
+
+
+\restoregeometry
+\makeatother
\ No newline at end of file
diff --git a/docs/link-roles.py b/docs/link-roles.py
index e97eb2e6e9..f3bb2a6cb1 100644
--- a/docs/link-roles.py
+++ b/docs/link-roles.py
@@ -6,6 +6,7 @@ import re
import os
from docutils import nodes
from local_util import run_cmd_get_output
+from sphinx.transforms.post_transforms import SphinxPostTransform
def get_github_rev():
@@ -34,17 +35,42 @@ def setup(app):
app.add_role('example_raw', autolink('{}/raw/{}/examples/%s'.format(baseurl, rev)))
# link to the current documentation file in specific language version
- on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
- if on_rtd:
- # provide RTD specific commit identification to be included in the link
- tag_rev = 'latest'
- if (run_cmd_get_output('git rev-parse --short HEAD') != rev):
- tag_rev = rev
- else:
- # if not on the RTD then provide generic identification
- tag_rev = run_cmd_get_output('git describe --always')
+ app.add_role('link_to_translation', link_to_translation)
+ app.add_node(translation_link)
+ app.add_post_transform(TranslationLinkNodeTransform)
- app.add_role('link_to_translation', crosslink('%s../../%s/{}/%s.html'.format(tag_rev)))
+
+class translation_link(nodes.Element):
+ """Node for "link_to_translation" role."""
+
+
+# Linking to translation is done at the "writing" stage to avoid issues with the info being cached between builders
+def link_to_translation(name, rawtext, text, lineno, inliner, options={}, content=[]):
+ node = translation_link()
+ node['expr'] = (rawtext, text, options)
+ return [node], []
+
+
+class TranslationLinkNodeTransform(SphinxPostTransform):
+ # Transform needs to happen early to ensure the new reference node is also transformed
+ default_priority = 0
+
+ def run(self, **kwargs):
+
+ # Only output relative links if building HTML
+ for node in self.document.traverse(translation_link):
+ if 'html' in self.app.builder.name:
+ rawtext, text, options = node['expr']
+ (language, link_text) = text.split(':')
+ env = self.document.settings.env
+ docname = env.docname
+ doc_path = env.doc2path(docname, None, None)
+ return_path = '../' * doc_path.count('/') # path back to the root from 'docname'
+ # then take off 2 more paths for language/release/ and build the new URL
+ url = '{}.html'.format(os.path.join(return_path, '../..', language, env.config.release, docname))
+ node.replace_self(nodes.reference(rawtext, link_text, refuri=url, **options))
+ else:
+ node.replace_self([])
def autolink(pattern):
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 9b8810644d..76f0fde7ba 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -1,16 +1,14 @@
# This is a list of python packages used to generate documentation. This file is used with pip:
# pip install --user -r requirements.txt
#
-sphinx>=1.8.4
-breathe==4.11.1
-sphinx-rtd-theme
-sphinxcontrib-blockdiag>=1.5.5, <2.0.0
-sphinxcontrib-seqdiag>=0.8.5, <2.0.0
-sphinxcontrib-actdiag>=0.8.5, <2.0.0
-sphinxcontrib-nwdiag>=0.9.5, <2.0.0
-blockdiag>=1.5.4, <2.0.0
-seqdiag>=0.9.6, <2.0.0
-actdiag>=0.5.4, <2.0.0
-nwdiag>=1.0.4, <2.0.0
+sphinx==2.3.1
+breathe==4.14.1
+sphinxcontrib-blockdiag==2.0.0
+sphinxcontrib-seqdiag==2.0.0
+sphinxcontrib-actdiag==2.0.0
+sphinxcontrib-nwdiag==2.0.0
+sphinxcontrib-wavedrom==2.0.0
+nwdiag==2.0.0
recommonmark
future>=0.16.0 # for ../tools/gen_esp_err_to_name.py
+sphinx_idf_theme==0.2
diff --git a/docs/sanitize_version.py b/docs/sanitize_version.py
new file mode 100644
index 0000000000..90e9101678
--- /dev/null
+++ b/docs/sanitize_version.py
@@ -0,0 +1,43 @@
+# Tiny Python module to sanitize a Git version into something that can be used in a URL
+#
+# (this is used in multiple places: conf_common.py and in tools/ci/docs_deploy
+#
+# Copyright 2020 Espressif Systems (Shanghai) PTE LTD
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+import os
+
+
+def sanitize_version(original_version):
+ """ Given a version (probably output from 'git describe --always' or similar), return
+ a URL-safe sanitized version. (this is used as 'release' config variable when building
+ the docs.)
+
+ Will override the original version with the Gitlab CI CI_COMMIT_REF_NAME environment variable if
+ this is present.
+
+ Also follows the RTD-ism that master branch is named 'latest'
+
+ """
+
+ try:
+ version = os.environ['CI_COMMIT_REF_NAME']
+ except KeyError:
+ version = original_version
+
+ if version == "master":
+ return "latest"
+
+ version = version.replace('/', '-')
+
+ return version
diff --git a/docs/zh_CN/api-guides/unit-tests-cmake.rst b/docs/zh_CN/api-guides/unit-tests-cmake.rst
index c5f8898b7d..d00eb3a251 100644
--- a/docs/zh_CN/api-guides/unit-tests-cmake.rst
+++ b/docs/zh_CN/api-guides/unit-tests-cmake.rst
@@ -32,7 +32,7 @@ C 文件可以包含多个测试用例。测试文件的名字要以 “test”
来声明主函数的区域， ``unity_platform.c`` 会自动调用
``UNITY_BEGIN()``\ ， 然后运行测试用例，最后调用 ``UNITY_END()``\ 。
-``test`` 子目录需要包含 ：ref：`组件 CMakeLists.txt `，因为他们本身就是一种组件。ESP-IDF 使用了
+``test`` 子目录需要包含 ：ref：`组件 CMakeLists.txt `，因为他们本身就是一种组件。ESP-IDF 使用了
``unity`` 测试框架，需要将其指定为组件的依赖项。通常，组件
：ref：`需要手动指定待编译的源文件 `;但是，对于测试组件来说，这个要求被放宽了，仅仅是建议使用 “COMPONENT_SRCDIRS”。
@@ -103,14 +103,14 @@ DUT 进行写入和运行测试。
DUT1（master）终端：
-.. code:: bash
+.. code::
Waiting for signal: [output high level]!
Please press "Enter" key once any board send this signal.
DUT2（slave）终端：
-.. code:: bash
+.. code::
Send signal: [output high level]!
@@ -179,7 +179,7 @@ DUT2（slave）终端：
当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。
-.. code:: bash
+.. code::
Here's the test menu, pick your combo:
(1) "esp_ota_begin() verifies arguments" [ota]
@@ -226,7 +226,7 @@ DUT2（slave）终端：
一旦选择了多设备测试用例，它会打印一个子菜单：
-.. code:: bash
+.. code::
Running gpio master/slave test example...
gpio master/slave test example
@@ -237,7 +237,7 @@ DUT2（slave）终端：
与多设备测试用例相似，多阶段测试用例也会打印子菜单：
-.. code:: bash
+.. code::
Running reset reason check for deepsleep...
reset reason check for deepsleep
diff --git a/docs/zh_CN/api-guides/unit-tests.rst b/docs/zh_CN/api-guides/unit-tests.rst
index de8e52d3ef..44b78951e7 100644
--- a/docs/zh_CN/api-guides/unit-tests.rst
+++ b/docs/zh_CN/api-guides/unit-tests.rst
@@ -17,7 +17,7 @@ C 文件可以包含多个测试用例。测试文件的名字要以 “test”
测试用例需要通过 C 文件中特定的函数来添加，如下所示：
-.. code:: c
+.. code-block:: c
TEST_CASE("test name", "[module name]"
{
@@ -187,7 +187,7 @@ DUT2 终端::
当单元测试应用程序空闲时，输入回车键，它会打印出测试菜单，其中包含所有的测试项目。
-.. code:: bash
+.. code::
Here's the test menu, pick your combo:
(1) "esp_ota_begin() verifies arguments" [ota]
@@ -234,7 +234,7 @@ DUT2 终端::
一旦选择了多设备测试用例，它会打印一个子菜单：
-.. code:: bash
+.. code::
Running gpio master/slave test example...
gpio master/slave test example
@@ -245,7 +245,7 @@ DUT2 终端::
与多设备测试用例相似，多阶段测试用例也会打印子菜单：
-.. code:: bash
+.. code::
Running reset reason check for deepsleep...
reset reason check for deepsleep
diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py
index 567585ffbd..b9f147546f 100644
--- a/docs/zh_CN/conf.py
+++ b/docs/zh_CN/conf.py
@@ -16,7 +16,7 @@ except ImportError:
# General information about the project.
project = u'ESP-IDF 编程指南'
-copyright = u'2016 - 2020 乐鑫信息科技（上海）股份有限公司'
+copyright = u'2016 - 2021 乐鑫信息科技（上海）股份有限公司'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
diff --git a/docs/zh_CN/get-started-cmake/index.rst b/docs/zh_CN/get-started-cmake/index.rst
index 7e4ac5de65..1192905d05 100644
--- a/docs/zh_CN/get-started-cmake/index.rst
+++ b/docs/zh_CN/get-started-cmake/index.rst
@@ -1,421 +1,421 @@
-********************************
-快速入门 (CMake)
-********************************
-
-:link_to_translation:`en:[英文]`
-
-.. include:: ../cmake-warning.rst
-
-.. include:: ../cmake-pending-features.rst
-
-本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子，说明 ESP-IDF (Espressif IoT Development Framework) 的使用方法，包括配置、编译、下载固件到开发板等步骤。
-
-.. include:: /_build/inc/version-note.inc
-
-概述
-============
-
-ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了高性能的 CPU 内核、超低功耗协处理器和丰富的外设。ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用和不同功耗需求。
-
-乐鑫为用户提供完整的软、硬件资源，支持 ESP32 设备的开发。我们的软件开发环境 ESP-IDF 能够帮助用户快速开发物联网 (IoT) 应用，满足用户对于 Wi-Fi、蓝牙、低功耗等性能的需求。
-
-
-准备工作
-====================
-
-开发 ESP32 应用程序需要准备：
-
-* **电脑**：安装 Windows、Linux 或者 Mac 操作系统
-* **工具链**：用于编译 ESP32 代码
-* **编译工具**：用于编译 ESP32 完整**应用程序**的 CMake 和 Ninja
-* **ESP-IDF**：包含 ESP32 API 和用于操作 **工具链** 的脚本
-* **文本编辑器**：编写 C 语言程序，例如 `Eclipse `_
-* **ESP32 开发板** 和将其连接到 **电脑** 的 **USB 线**
-
-.. figure:: ../../_static/what-you-need-cmake.png
- :align: center
- :alt: Development of applications for ESP32
- :figclass: align-center
-
- 开发应用程序
-
-开发环境的准备工作包括以下两部分：
-
-1. 设置 **工具链**
-2. 从 GitHub 上获取 **ESP-IDF**
-
-开发环境设置完成后，遵循以下步骤创建 ESP-IDF 应用程序：
-
-1. 配置**工程** 并编写代码
-2. 编译**工程** 并链接成一个**应用程序**
-3. 通过 USB/串口连接，烧录（上传）预编译的**应用程序**到 **ESP32**
-4. 通过 USB/串口，监视/调试**应用程序**输出
-
-
-.. The label below is placeholder to link a new section "Installation Step by Step"
-
-.. _get-started-step-by-step-cmake:
-
-开发板指南
-========================
-
-如果你有下列任一 ESP32 开发板，请点击对应的链接进行硬件设置：
-
-.. toctree::
- :maxdepth: 1
-
- ESP32 DevKitC
- ESP-WROVER-KIT
- ESP32-PICO-KIT
-
-如果你使用其它开发板，请查看下面的内容。
-
-
-.. _get-started-setup-toolchain-cmake:
-
-设置工具链
-======================
-
-用 ESP32 进行开发最快的方法是安装预编译的工具链。请根据你的操作系，点击对应的链接，并按照链接中的指导进行安装。
-
-.. toctree::
- :hidden:
-
- Windows
- Linux
- MacOS
-
-+-------------------+-------------------+-------------------+
-| |windows-logo| | |linux-logo| | |macos-logo| |
-+-------------------+-------------------+-------------------+
-| `Windows`_ | `Linux`_ | `Mac OS`_ |
-+-------------------+-------------------+-------------------+
-
-.. |windows-logo| image:: ../../_static/windows-logo.png
- :target: ../get-started-cmake/windows-setup.html
-
-.. |linux-logo| image:: ../../_static/linux-logo.png
- :target: ../get-started-cmake/linux-setup.html
-
-.. |macos-logo| image:: ../../_static/macos-logo.png
- :target: ../get-started-cmake/macos-setup.html
-
-.. _Windows: ../get-started-cmake/windows-setup.html
-.. _Linux: ../get-started-cmake/linux-setup.html
-.. _Mac OS: ../get-started-cmake/macos-setup.html
-
-.. note::
-
- 我们使用用户名主目录下的 ``esp`` 子目录（Linux 和 MacOS 为 ``~/esp``，Windows 为 ``%userprofile%\esp``）来进行一切有关 ESP-IDF 的安装操作。你也可以使用其他目录，但是需要注意调整相应的指令。
-
-你可以安装预编译的工具链或者自定义你的环境，这完全取决于个人经验和偏好。如果你要自定义环境，请参考 :ref:`get-started-customized-setup-cmake`。
-
-工具链设置完成后，继续阅读 :ref:`get-started-get-esp-idf-cmake` 一节。
-
-.. _get-started-get-esp-idf-cmake:
-
-获取 ESP-IDF
-==================
-
-工具链（包括用于编译和构建应用程序的程序）安装完成后，你还需要 ESP32 相关的 API/库。你可在乐鑫提供的 `ESP-IDF 仓库 `_ 中获取 API/库本地副本。打开终端，切换到你要存放 ESP-IDF 的目录，然后使用 ``git clone`` 命令克隆远程仓库。
-
-Linux 和 MacOS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库:
-
-.. include:: /_build/inc/git-clone-bash.inc
-
-ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
-
-有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 :doc:`/versions` 。
-
-Windows Command Prompt
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. include:: /_build/inc/git-clone-windows.inc
-
-ESP-IDF 将会被下载到用户的 ``esp\esp-idf`` 目录下。
-
-有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 :doc:`/versions` 。
-
-.. include:: /_build/inc/git-clone-notes.inc
-
-.. highlight:: bash
-.. note::
-
- 注意这里有个 ``--recursive`` 选项。如果你克隆 ESP-IDF 时没有带这个选项，你还需要运行额外的命令来获取子模块::
-
- cd esp-idf
- git submodule update --init
-
-.. _get-started-setup-path-cmake:
-
-设置环境变量
-===========================
-
-ESP-IDF 的正常运行需要设置两个环境变量：
-
-- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
-- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
-
-你需在你的电脑中设置这两个变量，否则工程将不能编译。
-
-你可以在每次 PC 重启时手动设置，你也可以在用户配置中进行永久设置，具体请参照 :doc:`add-idf_path-to-profile` 小节中的 :ref:`Windows `，:ref:`Linux 和 MacOS ` 相关指导进行操作。
-
-.. _get-started-start-project-cmake:
-
-创建一个工程
-======================
-
-现在可以开始创建 ESP32 应用程序了。为了快速开始，我们这里以 IDF 的 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程为例进行说明。
-
-将 :example:`get-started/hello_world` 拷贝到 ``~/esp`` 目录：
-
-Linux 和 MacOS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: bash
-
- cd ~/esp
- cp -r $IDF_PATH/examples/get-started/hello_world .
-
-Windows Command Prompt
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: batch
-
- cd %userprofile%\esp
- xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
-
-ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照上面的方法进行创建。
-
-你也可以在原有位置创建示例，无需事先拷贝这些示例。
-
-.. important::
-
- esp-idf 构建系统不支持在路径中存在空格。
-
-.. _get-started-connect-cmake:
-
-连接
-=======
-
-还有几个步骤就完成了。在继续后续操作前，先将 ESP32 开发板连接到 PC，然后检查串口号，看看它能否正常通信。如果你不知道如何操作，请查看 :doc:`establish-serial-connection` 中的相关指导。请注意一下端口号，我们在下一步中会用到。
-
-.. _get-started-configure-cmake:
-
-配置
-=========
-
-进入 ``hello_world`` 应用程序副本目录，运行 ``menuconfig`` 工程配置工具：
-
-Linux 和 MacOS
-~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: bash
-
- cd ~/esp/hello_world
- idf.py menuconfig
-
-Windows Command Prompt
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: batch
-
- cd %userprofile%\esp\hello_world
- idf.py menuconfig
-
-.. note:: 如果你收到未发现 ``idf.py`` 的报错信息，查看是否如上 :ref:`get-started-setup-path-cmake` 所述将 ``tools`` 目录添加到你的路径中。如果 ``tools`` 目录中没有 ``idf.py``，查看 :ref:`get-started-get-esp-idf-cmake` 中 CMake 预览所处的分支是否正确。
-
-.. note:: 对于 Windows 用户而言，Python 2.7 安装器会尝试配置 Windows，关联扩展名为 ``.py`` 的 Python 2 文件。如果单独安装的程序（如 Visual Studio Python 工具）关联到其他 Python 版本，``idf.py`` 可能无法运行（而仅是在 Visual Studio 中打开此文件）。你可以每次运行 ``C:\Python27\python idf.py`` 或更改 Windows 中有关``.py`` 文件的关联设置。
-
-.. note:: 对于 Linux 用户而言，如果默认为 Python 3.x 版本，你需要运行 ``python2 idf.py``。
-
-如果之前的步骤都正确，则会显示下面的菜单：
-
-.. figure:: ../../_static/project-configuration.png
- :align: center
- :alt: Project configuration - Home window
- :figclass: align-center
-
- 工程配置 - 主窗口
-
-下面是一些使用 ``menuconfig`` 的小技巧：
-
-* 使用 up & down 组合键在菜单中上下移动
-* 使用 Enter 键进入一个子菜单，Escape 键进入上一层菜单或退出整个菜单
-* 输入 ``?`` 查看帮助信息，Enter 键退出帮助屏幕
-* 使用空格键或 ``Y`` 和 ``N`` 键来使能 (Yes) 和禁止 (No) 带有复选框 "``[*]``" 的配置项
-* 当光标在某个配置项上面高亮时，输入 ``?`` 可以直接查看该项的帮助信息
-* 输入 ``/`` 搜索配置项
-
-.. attention::
-
- 如果 ESP32-DevKitC 板载的是 ESP32-SOLO-1 模组，请务必在烧写示例程序之前在 menuconfig 中使能单核模式（:ref:`CONFIG_FREERTOS_UNICORE`）。
-
-.. _get-started-build-cmake:
-
-创建一个工程
-==========================
-
-.. highlight:: bash
-
-现在可以编译工程了，执行指令::
-
- idf.py build
-
-这条命令会编译应用程序和所有的 ESP-IDF 组件，生成 bootloader、区分表和应用程序 bin 文件。
-
-.. code-block:: none
-
- $ idf.py build
- Running cmake in directory /path/to/hello_world/build
- Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
- Warn about uninitialized values.
- -- Found Git: /usr/bin/git (found version "2.17.0")
- -- Building empty aws_iot component due to configuration
- -- Component names: ...
- -- Component paths: ...
-
- ... (more lines of build system output)
-
- [527/527] Generating hello-world.bin
- esptool.py v2.3.1
-
- Project build complete. To flash, run this command:
- ../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
- or run 'idf.py -p PORT flash'
-
-如果没有任何报错，将会生成 bin 文件，至此编译完成。
-
-.. _get-started-flash-cmake:
-
-烧录到设备
-==========================
-
-现在可以将应用程序烧录到 ESP32 板子上，执行指令::
-
- idf.py -p PORT flash
-
-将端口改为 ESP32 板子的串口名称。Windows 平台的端口名称类似 ``COM1``，而 MacOS 则以 ``/dev/cu.`` 开头，Linux 则是 ``/dev/tty``。详情请参照 :doc:`establish-serial-connection`。
-
-该步骤旨在将此前编译的 bin 文件烧录到 ESP32 板子上。
-
-.. note:: 无需在 ``idf.py flash`` 之前运行 ``idf.py build``，烧录这一步会按照烧录前编写的要求（如有）自动编写工程。
-
-.. code-block:: none
-
- Running esptool.py in directory [...]/esp/hello_world
- Executing "python [...]/esp-idf/components/esptool_py/esptool/esptool.py -b 460800 write_flash @flash_project_args"...
- esptool.py -b 460800 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x1000 bootloader/bootloader.bin 0x8000 partition_table/partition-table.bin 0x10000 hello-world.bin
- esptool.py v2.3.1
- Connecting....
- Detecting chip type... ESP32
- Chip is ESP32D0WDQ6 (revision 1)
- Features: WiFi, BT, Dual Core
- Uploading stub...
- Running stub...
- Stub running...
- Changing baud rate to 460800
- Changed.
- Configuring flash size...
- Auto-detected Flash size: 4MB
- Flash params set to 0x0220
- Compressed 22992 bytes to 13019...
- Wrote 22992 bytes (13019 compressed) at 0x00001000 in 0.3 seconds (effective 558.9 kbit/s)...
- Hash of data verified.
- Compressed 3072 bytes to 82...
- Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 5789.3 kbit/s)...
- Hash of data verified.
- Compressed 136672 bytes to 67544...
- Wrote 136672 bytes (67544 compressed) at 0x00010000 in 1.9 seconds (effective 567.5 kbit/s)...
- Hash of data verified.
-
- Leaving...
- Hard resetting via RTS pin...
-
-如果没有任何问题，在烧录的最后阶段，板子将会复位，应用程序 "hello_world" 开始运行。
-
-.. （目前暂不支持）如果你想使用 Eclipse IDE 而不是运行 ``idf.py``，请参考 :doc:`Eclipse guide `。
-
-
-.. _get-started-build-monitor-cmake:
-
-监视器
-================
-
-如果要查看 "hello_world" 程序是否真的在运行，输入命令 ``idf.py -p PORT monitor``。这个命令会启动 :doc:`IDF Monitor ` 程序::
-
- $ idf.py -p /dev/ttyUSB0 monitor
- Running idf_monitor in directory [...]/esp/hello_world/build
- Executing "python [...]/esp-idf/tools/idf_monitor.py -b 115200 [...]/esp/hello_world/build/hello-world.elf"...
- --- idf_monitor on /dev/ttyUSB0 115200 ---
- --- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
- ets Jun 8 2016 00:22:57
-
- rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
- ets Jun 8 2016 00:22:57
- ...
-
-在启动消息和诊断消息后，你就能看到 "Hello world!" 程序所打印的消息：
-
-.. code-block:: none
-
- ...
- Hello world!
- Restarting in 10 seconds...
- I (211) cpu_start: Starting scheduler on APP CPU.
- Restarting in 9 seconds...
- Restarting in 8 seconds...
- Restarting in 7 seconds...
-
-要退出监视器，请使用快捷键 ``Ctrl+]``。
-
-.. note::
-
- 如果串口打印的不是上面显示的消息而是类似下面的乱码::
-
- e���)(Xn@�y.!��(�PW+)��Hn9a/9�!�t5��P�~�k��e�ea�5�jA
- ~zY��Y(1�,1�� e���)(Xn@�y.!Dr�zY(�jpi�|�+z5Ymvp
-
- 或者监视器程序启动失败，那么可能你的开发板用的是 26 MHz 晶振，而大多数开发板用的是 40 MHz 晶振，并且 ESP-IDF 默认的也是这一数值。请退出监视器，回到 :ref:`menuconfig `，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz，然后再次 :ref:`编写和烧录 ` 程序。请在 ``idf.py menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。
-
-.. note::
-
- 你可以将编写、烧录和监视整合到一步当中，如下所示::
-
- idf.py -p PORT flash monitor
-
-有关监视器使用的快捷键和其他详情，请参阅 :doc:`IDF Monitor `。
-
-有关 ``idf.py`` 的全部命令和选项，请参阅 :ref:`idf.py`。
-
-你已完成 ESP32 的入门！
-
-现在你可以尝试其他的示例工程 :idf:`examples`，或者直接开发自己的应用程序。
-
-
-更新 ESP-IDF
-=============
-
-使用 ESP-IDF 一段时间后，您可能想通过升级来获取新的功能或者修复 bug，最简单的升级方式就是删除已有的 ``esp-idf`` 文件夹然后重新克隆一个，即重复 :ref:`get-started-get-esp-idf` 里的操作。
-
-然后 :doc:`添加 IDF 到工作路径 `，这样工具链脚本就能够知道这一版本的 ESP-IDF 的具体位置。
-
-另外一种方法是只更新有改动的部分。:ref:`更新步骤取决于现在用的ESP-IDF版本 `。
-
-相关文档
-=================
-
-.. toctree::
- :maxdepth: 1
-
- add-idf_path-to-profile
- establish-serial-connection
- eclipse-setup
- idf-monitor
- toolchain-setup-scratch
-
-.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
-.. _Releases page: https://github.com/espressif/esp-idf/releases
+********************************
+快速入门 (CMake)
+********************************
+
+:link_to_translation:`en:[英文]`
+
+.. include:: ../cmake-warning.rst
+
+.. include:: ../cmake-pending-features.rst
+
+本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子，说明 ESP-IDF (Espressif IoT Development Framework) 的使用方法，包括配置、编译、下载固件到开发板等步骤。
+
+.. include:: /_build/inc/version-note.inc
+
+概述
+============
+
+ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了高性能的 CPU 内核、超低功耗协处理器和丰富的外设。ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用和不同功耗需求。
+
+乐鑫为用户提供完整的软、硬件资源，支持 ESP32 设备的开发。我们的软件开发环境 ESP-IDF 能够帮助用户快速开发物联网 (IoT) 应用，满足用户对于 Wi-Fi、蓝牙、低功耗等性能的需求。
+
+
+准备工作
+====================
+
+开发 ESP32 应用程序需要准备：
+
+* **电脑**：安装 Windows、Linux 或者 Mac 操作系统
+* **工具链**：用于编译 ESP32 代码
+* **编译工具**：用于编译 ESP32 完整**应用程序**的 CMake 和 Ninja
+* **ESP-IDF**：包含 ESP32 API 和用于操作 **工具链** 的脚本
+* **文本编辑器**：编写 C 语言程序，例如 `Eclipse `_
+* **ESP32 开发板** 和将其连接到 **电脑** 的 **USB 线**
+
+.. figure:: ../../_static/what-you-need-cmake.png
+ :align: center
+ :alt: Development of applications for ESP32
+ :figclass: align-center
+
+ 开发应用程序
+
+开发环境的准备工作包括以下两部分：
+
+1. 设置 **工具链**
+2. 从 GitHub 上获取 **ESP-IDF**
+
+开发环境设置完成后，遵循以下步骤创建 ESP-IDF 应用程序：
+
+1. 配置**工程** 并编写代码
+2. 编译**工程** 并链接成一个**应用程序**
+3. 通过 USB/串口连接，烧录（上传）预编译的**应用程序**到 **ESP32**
+4. 通过 USB/串口，监视/调试**应用程序**输出
+
+
+.. The label below is placeholder to link a new section "Installation Step by Step"
+
+.. _get-started-step-by-step-cmake:
+
+开发板指南
+========================
+
+如果你有下列任一 ESP32 开发板，请点击对应的链接进行硬件设置：
+
+.. toctree::
+ :maxdepth: 1
+
+ ESP32 DevKitC
+ ESP-WROVER-KIT
+ ESP32-PICO-KIT
+
+如果你使用其它开发板，请查看下面的内容。
+
+
+.. _get-started-setup-toolchain-cmake:
+
+设置工具链
+======================
+
+用 ESP32 进行开发最快的方法是安装预编译的工具链。请根据你的操作系，点击对应的链接，并按照链接中的指导进行安装。
+
+.. toctree::
+ :hidden:
+
+ Windows
+ Linux
+ MacOS
+
++-------------------+-------------------+-------------------+
+| |windows-logo| | |linux-logo| | |macos-logo| |
++-------------------+-------------------+-------------------+
+| `Windows`_ | `Linux`_ | `Mac OS`_ |
++-------------------+-------------------+-------------------+
+
+.. |windows-logo| image:: ../../_static/windows-logo.png
+ :target: ../get-started-cmake/windows-setup.html
+
+.. |linux-logo| image:: ../../_static/linux-logo.png
+ :target: ../get-started-cmake/linux-setup.html
+
+.. |macos-logo| image:: ../../_static/macos-logo.png
+ :target: ../get-started-cmake/macos-setup.html
+
+.. _Windows: ../get-started-cmake/windows-setup.html
+.. _Linux: ../get-started-cmake/linux-setup.html
+.. _Mac OS: ../get-started-cmake/macos-setup.html
+
+.. note::
+
+ 我们使用用户名主目录下的 ``esp`` 子目录（Linux 和 MacOS 为 ``~/esp``，Windows 为 ``%userprofile%\esp``）来进行一切有关 ESP-IDF 的安装操作。你也可以使用其他目录，但是需要注意调整相应的指令。
+
+你可以安装预编译的工具链或者自定义你的环境，这完全取决于个人经验和偏好。如果你要自定义环境，请参考 :ref:`get-started-customized-setup-cmake`。
+
+工具链设置完成后，继续阅读 :ref:`get-started-get-esp-idf-cmake` 一节。
+
+.. _get-started-get-esp-idf-cmake:
+
+获取 ESP-IDF
+==================
+
+工具链（包括用于编译和构建应用程序的程序）安装完成后，你还需要 ESP32 相关的 API/库。你可在乐鑫提供的 `ESP-IDF 仓库 `_ 中获取 API/库本地副本。打开终端，切换到你要存放 ESP-IDF 的目录，然后使用 ``git clone`` 命令克隆远程仓库。
+
+Linux 和 MacOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库:
+
+.. include:: /_build/inc/git-clone-bash.inc
+
+ESP-IDF 将会被下载到 ``~/esp/esp-idf`` 目录下。
+
+有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 :doc:`/versions` 。
+
+Windows Command Prompt
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /_build/inc/git-clone-windows.inc
+
+ESP-IDF 将会被下载到用户的 ``esp\esp-idf`` 目录下。
+
+有关在给定情况下使用哪个 ESP-IDF 版本的信息，请参阅 :doc:`/versions` 。
+
+.. include:: /_build/inc/git-clone-notes.inc
+
+.. highlight:: bash
+.. note::
+
+ 注意这里有个 ``--recursive`` 选项。如果你克隆 ESP-IDF 时没有带这个选项，你还需要运行额外的命令来获取子模块::
+
+ cd esp-idf
+ git submodule update --init
+
+.. _get-started-setup-path-cmake:
+
+设置环境变量
+===========================
+
+ESP-IDF 的正常运行需要设置两个环境变量：
+
+- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
+- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
+
+你需在你的电脑中设置这两个变量，否则工程将不能编译。
+
+你可以在每次 PC 重启时手动设置，你也可以在用户配置中进行永久设置，具体请参照 :doc:`add-idf_path-to-profile` 小节中的 :ref:`Windows `，:ref:`Linux 和 MacOS