From d1d10c4c6cf3b5980f10a22a84b7934988a2bba1 Mon Sep 17 00:00:00 2001 From: Oleg Kalachev Date: Wed, 30 Apr 2025 00:05:52 +0300 Subject: [PATCH] Updates to readme and documentation --- README.md | 37 +++++++++++++++++++++---------------- docs/firmware.md | 2 ++ docs/img/buck-boost.jpg | Bin 0 -> 33507 bytes 3 files changed, 23 insertions(+), 16 deletions(-) create mode 100644 docs/img/buck-boost.jpg diff --git a/README.md b/README.md index b4108f8..2937b8f 100644 --- a/README.md +++ b/README.md @@ -15,18 +15,15 @@ ## Features -* Simple and clean Arduino based source code. -* Acro and Stabilized flight using remote control. -* Precise simulation using Gazebo. -* [In-RAM logging](docs/log.md). -* Command line interface through USB port. -* Wi-Fi support. -* MAVLink support. -* Control using mobile phone (with QGroundControl app). -* Completely 3D-printed frame. -* Textbook for students on writing a flight controller ([in development](https://quadcopter.dev)). -* *Position control and autonomous flights using external camera¹*. -* [Building and running instructions](docs/build.md). +* Dedicated for education and research. +* Made from general-purpose components. +* Simple and clean source code in Arduino. +* Control using remote control or smartphone. +* Precise simulation with Gazebo. +* Wi-Fi and MAVLink support. +* Wireless command line interface and analyzing. +* Textbook on flight control theory and practice ([in development](https://quadcopter.dev)). +* *Position control (using external camera) and autonomous flights¹*. *¹ — planned.* @@ -42,7 +39,7 @@ Version 0 demo video: https://youtu.be/8GzzIQ3C6DQ. See the [user builds gallery](docs/user.md). - + ## Simulation @@ -50,14 +47,22 @@ The simulator is implemented using Gazebo and runs the original Arduino code: Flix simulator -See [instructions on running the simulation](docs/build.md). +## Articles -## Components (version 1) +* [Assembly instructions](docs/assembly.md). +* [Building and running the code](docs/build.md). +* [Troubleshooting](docs/troubleshooting.md). +* [Firmware architecture overview](docs/firmware.md). +* [Log analysis](docs/log.md). +* [User builds gallery](docs/user.md). + +## Components |Type|Part|Image|Quantity| |-|-|:-:|:-:| |Microcontroller board|ESP32 Mini||1| |IMU (and barometer²) board|GY‑91, MPU-9265 (or other MPU‑9250/MPU‑6500 board), ICM‑20948³||1| +|(Recommended) Buck-boost converter|To be determined, output 5V or 3.3V, see [user-contributed schematics](https://miro.com/app/board/uXjVN-dTjoo=/?moveToWidget=3458764612179508274&cot=14)||1| |Motor|8520 3.7V brushed motor (shaft 0.8mm).
Motor with exact 3.7V voltage is needed, not ranged working voltage (3.7V — 6V).||4| |Propeller|Hubsan 55 mm||4| |MOSFET (transistor)|100N03A or [analog](https://t.me/opensourcequadcopter/33)||4| @@ -90,7 +95,7 @@ Tools required for assembly: Feel free to modify the design and or code, and create your own improved versions of Flix! Send your results to the [official Telegram chat](https://t.me/opensourcequadcopterchat), or directly to the author ([E-mail](mailto:okalachev@gmail.com), [Telegram](https://t.me/okalachev)). -## Schematics (version 1) +## Schematics ### Simplified connection diagram diff --git a/docs/firmware.md b/docs/firmware.md index 3b9b45a..3871009 100644 --- a/docs/firmware.md +++ b/docs/firmware.md @@ -1,5 +1,7 @@ # Firmware overview +The firmware is a regular Arduino sketch, and follows the classic Arduino one-threaded design. The initialization code is in the `setup()` function, and the main loop is in the `loop()` function. The sketch includes multiple files, each responsible for a specific part of the system. + ## Dataflow Firmware dataflow diagram diff --git a/docs/img/buck-boost.jpg b/docs/img/buck-boost.jpg new file mode 100644 index 0000000000000000000000000000000000000000..5188517d5355dc6b776e56e9ab554a86f49ee295 GIT binary patch literal 33507 zcmcG#Wmp_d*Dl)3;O-U(?h+)pdvJFN?m9@&2oQq1dvJGmcL@;OAvnQ;1PI{_dE|Zf zcg~M}U1#r}>FT>zty)&q)wQO39v2=r08BY)S!nly8Ux}!vEQ> z=boekzzoZitpCvew-A=Og{v9VKouyrsky6}0~FT*0BoC?GsF!5;GLm#syA-VPdFZm zaUoCxp}6P?Tm6OGp0Md(_{$$24K)cU&o=--L^UyiSOEa~8I(@$VP*xDgMkUfY>wtO zj!-NL#lj8_PUcYj9*XIqJW!n&Px5(9|4WY5e_<07(|=`}m{|Rb|MCUe5~^6z#?{&0 z#Ou$=|H;C^-W?jRKN}siM74&zQiC3Gp>g|W=Oq7xQK9&!qp6ZI6k`Jb2-XJb-QO7B z+WnO#6hrwz^k%LS&{zWaP%P+buP*yHUCrD?QXYy)pma+|d!?tof8z1Cw2^+|fyNJ% zY~v=Y0mXz+Tx8)YrT#Zh7sN^JAH8#y5DBrr>H8)SDEdq9Z+AP*CpuI<7~9%H_HX%M zR&Q$!Z73ZXN|*Go(Ncn9bSPGGwNrnx2WkV@z}s5liT;NN;;#1O3pJDuv2c_ThhnH- z;6zJ^^iv$3_)8pIq3BN>z+KihvQKTHF#%7zS!=w4VrZ4LU}WpuXxbDccV#Vzb*p6HZN ztl{dR{!d#EH;Bd)9cm|Rkh7c0Qw*VY!lv4q$f-av)E?L>Kmm{dBmr{39lDzWPJk_7 zGjZH_3_bg+Mj9{yAb=HM0kHf{`KN{UpBhJKsSbDp-vLJ`kL$nf#Q)S<03J~K!~dW@ z(QN*u{UwhDu>8})B;@0gwmmq37;UYyoZaj|E!5Hz>vC-}8SgGJ(o8gZf|( z-Jk0Jzv=%_|HCN;je)}7ZQcLTNRIJOdw3~$N%&Xr((nwh#IVA!0M}NiD0vhxGiVrL;R3;a!IIIvOkXOaJZDza9Yp>7l>*kl2twNCZftNc8`+B|0NI z*FXOLiS>U+@-JIW|Bd%Q7W}{U|EIqKTnioqcY}w)ZQw?L9NYHxN12sS+&<1n^1HdTo z1(*evp`&L9I0DXqYv3LR1_l8J4F(5>2!;%X28IcS1BMqy7)A<40Y(i*7seRI3dRw} z9mW?X045A37A6(uGfXi|HB2*1H_R~16wD&bCd>iM1NL2EZs_d@u!=1N;aNo>bdQXMOouFltbuHc z`~f)`xdOQ#c?J0g3JMA(3LlCpiVezplw_1Dlp&N&lv`A6R7O+@R0C9Z)JW7q)GpLT z)E{VQXtZdeXnJUFXpv~eXuW7_Xg|?$&{@%C(aq7{p{JoYpiiTpU?5@8V2EKDVR&OC zV$@4VbWqsV47gQ#Z1F&#+=8z!otB~$5O^}zzWAI!5YTe$40=W#g@W0#}35K z#qP!4#sT9{;Yi?^;RN91;q>F|;KJk5;mYFL;)dat<4)k7;bG&w#M8p_#7o0#$J@XM zS5+&tV6?h5V$ z9%>$Ao^+mhUR+)k-f-R_J~%#czIS|We7F4E{BHa;{HFpe0(Jr=0{en=f);{#g4;rr zLMB3=g*JrAg^h)?g*QYfL`+0-M7Bh!M9oDDMEArP#B9aN#7@N7#3ADK;x`if5`Ge0 zl3+<0$xz7&DQqcCsZ^;oX-a7;=~C%487>(gnXXrGujF6FyqcFKl{J$smOYc>k@J)5 zlSh?Tmrs@7QeaeoD6}Yo6y+4-6jzjJlpK{Bl>ud0Lu#e8sZvJ8q1pWn(mrCS{PaeTE$v7+LGF_+8a7Abo_Kib%}Ltber@L z^tAK}^se-!^b_=V47dz}4CV~!3_T5pjfjoxjoM#hyf%4VYYbJp%uK>8$?V8n)I8q&z(U9()?&|6$THS)-%7|T&g#Hg#5&RX*ha!8)#lvxm2H;o zjh(Vxq1~gswtb}oqJyzRvm>^nonxQVb0<%yDQ70T(6z}8 z7rM|NbEkLz=)UP8?2+d2^NrS>dJGoKz`3f~XDn|@+` zpWni~HGSLjj_O_DyPfwk?~6Vlf3W*7?$72Q>wg)b9nca;8u&hN`=iXq(jfF8NYMNz zflpb%u)#LL6Cs=-DIvc@%|l1R*uoOSeubNbk3_IXBu6|(T1HMpaYtoF!$&(t&&7zu z6vbl2ddF_ZDaJL#lgEd~Unaax7*2edn3aT_`N>n__Sd*QRp=Y|~GoWxxCT#ww{JgvOJeBS)x0^)+Of`>xK z!i^%eqP}9D;^GpLlBiNpse9=`nL*i?a>??h3YLn`mH3rmRX~+{)nT=9^<0g7O;0Uv zZABeTU3xuEeP{zrgIB{@qjlp(lWx;gvs`mei$F_#D{E_E8%0}MJ6?NK2XaSX$782= z=T(<;*KxO1_jb?gp52zOcV& zzj(gnv2?%ueg$qNbQNdE0FJ=$q@eUps-jXuFAf zWP8Q?9Q$nt(g$A-^$&NBoR990gT7;ZPd}kQsXG-t9Xr!G+c}4vKVF3YAo@{w`SP;o zO66+p+Tr^CCiExK&!Su2+rc~SyS@82zYu;UKQKJB{FeW{^62pR=xhQp`Lh-PLrajQ zB>-F$0sxvW0N{Lqt{?RO$`Ai={K=UAM$mNX5Blr)U-+*a@=qN%08~KN^s2|u)y+Hr zROJBxEmS^+0RX6=0e}V{0OI8QcmG@5UwP-#2|P5f$X0nUbuj(A>VG->m6JkA|JeOM zk5F$oIbS}t`CpEY%RnFi{s=Gdvs| zyk}&@M8ssYl$5k=ENsHU8ZiHV1w8fuScovNFri==EC7TB1IB`R?1L`4pk9Oj3FedO z04y9l0wN3uj06LKz|d9HAL3sHl=@WrxCEd=+kh~^(0Bn?Ps!Q;_69RS8w_O@jhU1F zP~`XwnrWd1i2|Z%VAOp8Foyo%u}J(LwTcY@-v1HF1}_TD>JUo68CQ^t_PIQ=YC z5iLRwZ)^IyX~V>FF;CHQI~jkAUb}q}(HrhVtq2iH3!0 z^cF0PC=ILQa=`3pA^;Pp{f=ka*rV#A0U`AzcV3Qpyq~n~(ctZP;_6%o=h;kg;8kO@ zQFA&gw_V(u2W0h@nZ)s01hDa0Uf&46H01TrqxF?&m)CF;g?>=6p zRH=m3!QHJO=|rQ{HUDTC#Gi)~JUM zMbO|*`|*w^-9&p-TNPrwoAHsgwPiA5ts~s#s}W>lt>}x8B8j;YEq8_)UWN1QtBb@}CrW_lPGB1&Cs5do=(!>MR!h*g{J(unsp zJDR43C-LK8)`%dd@(g@eHH6`}m?u)UQV+E*<^=E5+k?!V@1P~F0ATGkdtOKFk%YTTq*YW3|Spy`J( z%>kV~=*I=QPlWA5Dt(B{(vMO#+O4$Ax#)CGib1wsfop8!X}I0`x-mtzv=$^*$eVM= zrcU}xlC}E&tC0N(HP7H=Y+MwDTom(*d+pwt+*97>GFIg2z|JI26go~s(bA0C>SfDq zNB;J=Id6n2j-jEHqThOX0nvkFa_JD(l=E(HPM#EnJv2()y@E%H*=z|Ki0}ZVoTp6{ z?RKbr0#Qn+R7rG!jbb4?46>W}-djafH`jtnyMW*Tkhp7YCm=*0B?^P=xBkqkpW zqsS7gZ}V*(TH}|(fe5X9f$U}`Be2U0{@KE%@wo_XuVt}5`dX3jmZQ24Ew}rjx7*H* z$X*yy3(GKwC5L9J+5Tt?M|o~%r>!|8CzSExQ|s*QU7V;ILRPZx$J(g_n$dcfm}k3M zt;M8IQ*ogAkHXq(>LY%WL-lH%y=JA;^lr2*p4#ah-87lmUQHMD+Hn%W#@qJp zyI;mqpLrddRel+?b(6+86gx<|st_i*!)Sp$PVAC&7=v|H_krf)o(x>+_$Je04N9lJ z_(NNr+dS!AJy}!bt5~GUeB54!R6aGom()E$T#1!tm-tD;euCdWGyf=j+q*lL7ICz8 z>v3KoFVJih=A+D43!Ru$m^0r>OzvN0B*bcVvHwWCn3Q%Ap0?Q4UTmBxW@P1etqLx_ z_&6}plQ{PN#h$RM%Stp2ns97MPh)Ex_5g$0&H4!e+oeJv$ge;b?A^ zC2&P`BgPR{;#6>(ANb?<>Xp%SiQL_7W{l74zZAEvK_~{9G%LSoiU;duk``tat@ugU zM7u3V(6v*$X9w>fA=2JunlZz9G-gpu4OsnX;;q&2dncRrPFiGf#u+tu4Cxh)L<%W+ z=1))8b{zxUU5mZlrWeOXhM8Y<&NVZgznv$so@#R1XCdlL=Py-cJgWjw;owI1C?}j~ zj@~KN8ww8KJ5FkTI0xhKN%zcY2ajqs`18G%m zu++v$#md!3$<_@1%w^fjs6Lj8Wl-z#rV-i9N0myWKx)cV*+aV^#?{qU2} zDtf&xbaYAKPj*!ZPBJcqC-b+UG&^yv|zh!v>(j!l1gZlO=g9PF3cswuRWZrKIrv!u=-ijq@?X!@Vd@`h#@} zVUa5j7KP|Ypq)1I>&5oyab5$?*yz-a1NtYKbnxF4XP79|)phG!yRhsx9X@q{UfOga$VXD5{W0%>L zc~;?564%P?selphap;#-$!QJW#XV0C3!TPLwU6>s1s_!N+kvCs=_88Kps38m(1o=sJsGfTD04q6oiiJfqUoFI|cPtLscUhD;cS=`qML?P&^ zShT2dzRdP1hUl_<4C8KA>wM&8iV~Wv*sy$Khi9dW_70yS7bnME4fDHmtBIDs$~PK9 z*1xD)cG)O;fS6E}P|lcX2-jRbZ%OB9k2ubz_Q|VHIu)zHQ7^N{nG@(T|EOC#X|R6} zohxkmt^H_QK;k5yOF|jwxieYZb5lEs@hD{TL0DB~-?tKGmKVNhCR^@=R9*W^r#BAoS#swrfuMKHQDRea>_f)ls}94wWSzHhySKH=Lf z9~dNE7xE@5Q5;~Msec%0qH(*6hUN-I#Rkv5+_`r;sq^EmI(tgyRxbXmP9&pD|1OqU z?4<4P?bl=wtIndRmUt=E?5?0NJ6HCcVbaKA4~vDR^`_>=Tf41H72*!6Q4AxZQLsr( z`c4ue%q3hgug-RMCT%o7{r2$c)LhRP0%wirZL7UIa^Q~N^`!Q=mL)LY~Q zwCL~}uLTK_^jSga7Z2@?XzfLQvO-DDX%9!iYKlQR2pJn(6+(K7S_LC(b9$SN%3}M^ z;JeZYb6Tv5ZJn1!=MgbPn6$q6Wqwq)Dzs_XMuk&M=x;gy)hs1pN5EtvCveh}M!M%{Fac*)Fedb-&#e657_k2;J z_-T53EE#VLT;T9`cd;Vmh}-QdCeDYE5{0LdoS6vByjsegvV8!65dJ$Gl_3RDG9g&? z!vPM(m~JvGm>w1JD+eD z2FCgRq)7i4ia(hlCIABqf&sz8J(UPhEg%?Z_6NXYVdLQ9Q?Mi8kyCPDQgMn=za*gH z5*1fbH8yd9W`>B+j1dMA<`I}hI+NNK_`c^?c3PitUE4ADW@+MHcMbIv{!QA%53g0! z6ZAI-{Db^)(0zt~Mj#;Li@}k?3A%fvJFPn{BxS@(&59wt@HhJSj?IpSfD-SH1Hm%> z?BvldYXwbM^A9?|3#s06?@uF{kckc=WTa%k+BrlzH<+p zyEl)(j5-Sm%{ghWhLXmV2m|Lr#PU&!yQ}JpnqLtEOIVbAdy6SJZdt7I3Mg|C0S8zV zI;*lttbDyIyFwItp4=c-7jB%_{oG*XcWjkP=zSJP0dGrB`dfyDW0cMBoWedO@hVj~ zKLYhVQrkjJ{fC;vicKox#H>Hq@JI>#w7GgPUaVBS(Plc9gB{4DJ-p@HK=UaL-ejOO zr`AQd;rt%hkzy+7pWM=!XooE*R7+iB(FZ9Qu8%(oyggreBM@a4F-q_Zmp1EA%&9}}S>p!uH5si@bZaQ&k(zr(%rpyM}u*?o1;Bc*wX zczECvIV<-!*IB^yGKoMzZYXWp{> zqLo%Zim-{I$C&6@291zvo zoPF==t4pCpr+zf*kdwqGf!O9$=8P%XE2%nK^nns5xW)|hTN7kN5ibUHX$j6(jFn9= zxPtw6w<~UR8VS}t#3p<2O^RWnOj*TO^zs>8R^{-L*$I2Cye2(Q%B=&t5BYT3D{F~T zvtb2{cjn#Ru|6@e=wH7?VGJ#sUH%@O&Vw#uZyFI}DES0i(Z=$!lx2BqqncgR!zEr4 z{!)JTk^6j}P|{pU-CQX)AU#k_sz7;xORum1F2~a^Gnk^O0beb@7c3(#c%853E}mKG ziIjI~(^GLh8D6ZsE^L(8rX45>Y?k^Zy(Y|@{p1{81i3egmzv{iH{9R9#E0HC zPBW_yp$|RpG;N#s$|<9^vXquj>>`q{m+>_2+ewtN%vh@wG_kP0rJFxf)1Nx|DzIGq zIgQ^LT(vD)5%kqVx5Y23O8VhYqG#<^Jams}@)1C>awjHCID; zGW;Zq^p8M;!XUdk%K7WrN-b>?VH_Af$)QNdA-BKejGPHguXktJ)u={M+LqLK!b3%> zne+vj-e>MC&kZ@=Ea$$~a;Y7?7~WlyPecvn+I-lxzJ_k!GQu@2rmgL_n7O|R$yGr}lh?Oo!l6bAF{72yPnuVcRlG+@b zyis;No;Kk*AVhLLm)5T9g<7&97ZQ=+$^MF{UO)2#Jd9Ji)^*%jd zB@T0Ry%#^jqO(U6fB2=`?Svz~a^m~!5Ea@MW5bfC^AocsyRpIsUwnr1G{lG$nPx*@ zR70xrIS!F^ig319Lj0+IOX>Hn_!(ZZP(Oj0iqLE>&b_PeRMY5li=Po>k6K@1y#f86 zj8`y<-@er7Jv7kR7HLzq-=4>bR}eGUo+oIYL?j!bZ>6i%EyMm5bi)-wg+Gh-mW46D z%wP`|cRtV-rfHFtzHSJyw0QbU_6Xkoy;-6B_X<4(b}vQx*cu5BhvSGjow2u)c5VmZ zMV;u^XqK@A`peRTWyj7wbXL0W1P?MwmsyV&m!w&^dIuFNd|RBRiL{EiQ5hS5nO**p zpuq-__Q*$x74N=eyuCYq<+Q5Nj-wNRG;p~vKGkGt8eG&Qyg0$&l1AE}XJ=vYdGSPH zKD9LX8j)oys*;b%GUNHz)S*P@JqiyzZ$B69^c(W=^k}#QLtT~n`~E>{9C#rCs-Sz9 zRY56LBejGG-8vnzmas3j5I(TqeM_0F?J{f>UIni;Vtu<(7yrkD$7(T%MhNb1Q0!Nc; z4`CTkJ6!d0JRG-y?xX2^Zvsq5vqmhFsAAEZHLNN}sUxhFviSYO%s7nFJnbo2egd2y zxZ~}f7G+=W1Y5o0+VMC}qu|iqNq=hEh~&b|l+gq+pngEmiIkI>-^S$!$gmKGq~+X2 z1!quND@IUZ)iROOklsb6+g)T2ddP&;$M())`JlhGi+D%AV?oa!(PUR98Vz2lo5jOP z^x%#ZDvd}Co^c$G{)miYizsV_6_j#<-%nI@BCTTeQ~&NQ)r&R4uMBFP!3SlM8pHb> zsa72dFJAC`yrneu*}4b|n;9^ieFa(XgVh>N)VKfiqNp|JIM_i;CrQFlTayRzzWJ-* z)<#ZgK$^c_gk@fE>eZ%s(e8~L`k*F%M=Fu5+BVDts%QAdn^gjAIg&2dXNjioT>(QyESUYw(H^(Csx^C^Gg6%cFe&rT@n^zj~j()eW zN`KrPGbQDkPCzK`Y@7RRT|u^?vW@?T*0)E%1CLxTj8JM6U{DQ4F;nN!!L$0A26fJ5 zMQWV#C8D+(jfj<|x{I8HP_2sQ5w1dS1i?chTcFCh&~1PJcKAYSwXW*D#T#Sf+)U%f zlcx7P0>Bw>L!(H8uA)1)M#X6V>4dv6!3oB*q*|g9%3Ir0uKn>>$wjAq4Y~5!f&TR? zv5bZOVw01%CwAb*VV!XSf4Wug{ZG{@| z7ByKFY!t66PQKGz4tlxjTEA`!T4d)nd*2Y|_9}gIkveeSu(~_Si5#qy&`&LHz1#T+ z#P7);+&ivmXSc5Y)qRy~4Dr#2IrF{I7A9!d3D4K^=0*!;(X<4&XL4BuZnxfDJpu;!E*V-+5_cBVdo(rO z60-_gOfZ^fZ3=E*R@8Zbu(`i)PZpx*CvWIRUHA7=#9F2|^64Or6X$Bwof$dihUoamxxsGWG+oc^f$!F#5zZ{sqk>T07 zvWj4y8NR-SFX z;R{jPYi2Sc0r;L<|5_^J+UgQ|oaah|HaVdqL@qH5$5^{xowkO;Oda^Mw+d9=t)>ig zcFsg~a%0?o9h)Zz)oGqjzhf0+O+MZJ(-$bEP4v|%4up|KNG<2ba}^>g3$ zf0aBe2=1YTqCA|^ES)r@>Zq857IusZT-1);yoFS9BS8)bLO^WoXS3Bt2S zV0XZVzPQK$-&W{k`JpmxxzAfb=~(qy&4O}g%_09KsmU#S?r%?0$s+oV3eEh zM3$ZSg7==~LsfG{RN77D)(LY?!rK$-bHmnoyua7ZW`^MxDY$JnBN0@oy?MUZr;t!JqEN4j4_t;lC1>e7^*H#}%2C7R`cWfa?V<*`Gllu% zuyDdLzLBiIi-|X6Zkj2-Kr6fZrV+tE?co36RR*OPf%D$lax3mu8d)X-HpWt@PH<>P z2jUTxKz>$RdqKXrLL-Q8&xtob zxxFIo42&>Pz?$w4ER2kZO##t*Oy1S`k4X6S+x-kU`1x_tjico1j?*pm5r{2cMvq>0 z%rk5o7Al3V#O7Y?HoaY-F3oK2DPX*4-tP#TnL5bKS~!1TWxR8Va9M%czhJ}p>LrW# z9{r*Ch=Q!vbkt<4Lm~aq21h{8yIUTI!4kuoqa8R|Odwl)i-8A}g zb3-a8am9vW4y2T{yh-{(LGBjmIGTEEUS7m0K|w)p(IyjK%eTYQlR-8NU;I2HL}yHv z;r?SwB}8R6GjA=WD*9j<&Q8ujsjg*yk$wk%Yb1BKd;~4aGAFHKD2lXl66ey|I|7G) zEUd1eL|U#{hOY=m&#U)mR3(Y4x%<(6tmq2u3kE~b;iBVJuhEQu`3=q|^P>p~n=s4l@bVl6$Q{*k*Sinb zp%wI_`x*vlH*_o%{zNh4zl-D>PEa_!W!^J+y@Y&+KW;N&cYUIqv=EDzXZJ;^otT}z zMg3?dGtolYw@)&4FCV@?XB5JvvBTkVJ5qpaho_hr-yQA4`~2El z1Dwe1#?RBb!kcg;lvOPuym(c17kv+ete>!)`O|+zct>bo!fk&X$hQ?5#G}wVq-2cb zbNWnPftJmCgHA_glgpr82T{rzZM4G2Akc{8@}!X-8boYu??V^l-T z=y3`ul}`xdtD1?Jx2Z7ON#xKQ6TT>VqTwN>0%nnk+x=FVt+ELU-0jaWSPkU34kmDj zyEw$C6@}YVkT3oDoXCTRR`gJa7+@VbNCrys-g@xdzAeKJ%PA7u=RIKHm1|apDMfOq z+g?X@I}RXW;wG@u_8I%hKIA+X(z-ZcSwH`b7wWj&CAS zGIxcY+h6XdUp*wQqkN$#BU~SwPU*%n7lPyoJ#vVB^Evt5b|jHR?;{r zwUvmV7!Y@+3^(Q##pvQsps-!$B!0y|wHZk4+YYsGk1v_`3D>t*KTe3%e^yGjOI^tN z#>cC^Qru1C#cZ64v+T3iQV!46=w#)Y)?GpXQJ;oOu`e&RlT`W#k=mEd!lzy~azh;L zNs{kHCe|biKiT$0VNESdl7O9;_Hhd8V<|QYW*ykl>9E14BidL44?@^EA|7_KPw8)c z_2`4=tj24ytvN$GNKP8u>&l-x*1c4v;a07u#T*K8=yTJ(mDV33Vh!yF(}OApxRs~5 zO2;w8e=YV8Sj7#zuUx=kEutGspG@JKJu+ndu*v~i`mScyU-$vO)u^)mbFH+&TDnR3 zhp*&ugh_#=MM<_d4p~1BP3sDiUVervR6Kz1EsuTwTPG{;tw8T+@v>bpL9CIc>wICn z<(`c_oLa-ORXnnSSAcKa%GqSvgy5!N4`T;WWg)wj>BG*Erb_KG=4uF1LmHM06#|i; zXsW3IYvSCdGnAIkSMG3<`d;X@W{-jps3eM9Gc>PXQV+uS-VqMo$doMLB( zPWEt`CR5L|PVB^nl5@=Q!}Aan!!TfDrDBv&r}{H9;4*FvKSZkNH`bU?G%PZTd>FZZ_%^`Q(n=lkqQ8%2$B69WC z=KjswC21AnBLqy58lO@>5q(C86u#LAy_|ER!qb#dWJNav6QMy zg=DgZl&RE z@DZ(OA+dj=k#r|9KCPV0R5w|`LSpwo3y3oiiZgLtA8W-}jbp7S^lzlZdABpT_r@Om zR?&S{Vzx5DO-vcfVz{B{t1FL8Py*FmOTc<^Z-Bi8@n9dOJ*%{eXhyBhD=?fo0zpeX z1Xe?j5j{J(IOI4>{NCb6dB6iY_`3`?iPwHbG)@+WQ)Q*F`4Z*cxR{7Ydi{VQ559Sx zS6w*LiOb;KtHp)>@RZH7+`UiRR2`zAnTe6`x4Go2aXs`OLY@61Szj2@$8ObUlpPm% zs0+x3PI%PT2a_@eGFeHvVpXP%w^W!G9WlCx)YX%p52fJKg}C-KOk?nlJwIg#f#>7- zvdKLY0ha!5;p>klk|@51-@@k_J`Kpq1iW^@oWWT>fMhhv7i)d^*q3d=`HjVDD0MQr zI*Z&)SaiV4FVn^Snqbv^H^FuEdyaGFYdgV?b-tZlkxtfu{`q8si*E`Sm%fG&ZZC)M zixqq5SJ6G{bacwEc2wouJ(wv|>tk4nxWPp_Dyb64D#6$)VZ$oH?sk%?yMH!^m9-Q} zU9c46?jrx)b!vvU=^@u>rfRu@p<27^i2K4sGco_g{3AdIeHTp{`osYYeZvd^9t;N$ z`}D*C`i>bEm;x4?9fwj(6_Z@e#N|UQ9EW(!=WeR%DO?G4NE{odsejHUJaxdisEUTM znd{l#Pau#)pidyiNkE=TNZo>Tup8-ENZq`Y!AgjM;zHs${`5IfDv!XXGM;LW7o6em z1dZEjZTI^`nzgJOomi3K-$$78Ila_y2EP8q%sDV#_4!(4R{w4DmJDS9T31%m8HacJCsy|LtZ?qR6{xJH2u-l%!vXWP3i7%2| zri3%xZ(4P{lW@_VD}UHtF6x=^-B%z&CWr%xL)qV%sC|BTMBIXM=A`5HHHp|(iu~b6 za$7;9mVs%)IOFM=yYe`6GIdwZ9NdEsJe_cQ=`h@5CAAN7`64B*Z;OxbN+K@eAGnTO zj|4eBSGjDIAauB+q~6r{wGfika>f@C9T13~?($05X zj-<_dIWzV~@?7e@8Z}qhjc+1xxmEydeXaZZicPs}*GBXYreTLQNV)8AMMB|=(Yvi_ z#;oXXc1tvkL5q@;5qH9}73_2oNj;J&yA>Vu1}*J5&2Atw|L3xK&#z#JZoG+Q7thXg zY?qXq+!SeM3UN{GDIZozLbvITzD{EWdn(f`V>e$423<%iuw_w`CN~8OBYk4(4M;9z zTBg*7m^~Lkln6XxC|}72r^1yFzpT5Um%`S6K|9T*^h=GU%Xj8N!!8d`_2bV^mR_!w z52N1s;s&SK>U+l(a^rrWqK8d*$KoN+)ktAPo09s_o!O18))o+=QIr&H5ro7!rc@iY`eYMKg?{)wiGJa~9lp!`uTC?ki&J zAW`<#D+BdsRU4ia@|qqk7=?M()LxX=AsOp!JsSk96|vf^h2}Yg2m*8p-LP(^Is?Kc zZCd4+_rinH?C?eAaVH$fCm?IUjXZ56_WQ;3F;Ksl1 zxLRVMXAUd1MxkHzLk_P;jQvEXfP%!?w0fc1MOrNIIFa>D)P5mTcye{kcuXn*5r2hs zm%niFhF8g)PD|>MMKG(-`L+I8!0%_7+@e>U<}XJb){;;A^RAmR&rz@^)Q8?_Dmu9#gi*$G}YhkL4DqX`&A23 zDjL-y?02+VZ_O?xa4uih<%Zn74Y~T&C1RmEu#STn)ag&wG{0MdY(?P~!_RC+a>L06 zQ+*qM`1-5$ec_kirE+~=oNfy*jHYr01B~8|lG3%r+(X~Ecm(7hW=gSr-s@W#aeZ`Tuq2-;;fp()UOi5qk1$WfO3QWEh)i!rmz|!efav7IlKUbO2i(Wii zgTc2V%;r=KGA;Sy?)>X}*$gE@PqW)cjp}eaW0+HAE~EGS1Ijo0^#L^F!CA1H-1fTa zR3DzLF&02(&<}Q-bMI>lS}3Kikn`mt-6qULSObuES+>&0+V9q5iyRS|BP=YT4Fw6f z785G^vtsG!tE4{9+SX^sfqu=xYrE4EHdQZfT`j)ol5!gahzY3)29p~Zd`oV;}^C^k|E?RPb z1L~tW+ZSeiN-#AhI+*$z2QeKb}i@No0n`PpICDyP(^!p>I;Jju$% zy0y=8NT$98tm8p;x7NvE2Z&plglB$;-&4IUEQx0eX@m4c&c zS%g+P!P)%p)U0pXS>Ia42>idN6j*d;*NwHZ%#qKT8LIYI9hbe}w4djk8e?!_c4&fK zj+Dz2OQswew$rN*ipKedR}iEwiawch99em8P)s1IA+HA;Yr=UJ)rUyoF{l+eRar2% zoV**c)P<2G#c??4JTYAR>9FeRJ!RLvupXV28zv9rXeO`X681RfH;UT62AMLK1Z;%E z)Ho&#yw*NC)(XfcIH2DWeS57esIFs(la@AXD=C7w_xHX$m}bCInQKYMMXBgnz57IQ zO}V{fs1u;$ni**gukxM~GyIm~Wp9@!=tf#k>C``8*K+yhKp#fgI9_BBRe2LT=1^4C)Mcq}EG|%#E(Hy#Yj{}|JxPOmD0pqCQx#Q9% zJ`oiIe>N3W?u$hPB^j6LRZ-6zzb=ugVyzTGovoQm&2u~iI>BZu-8ho6HRwN^V!oJk zUsI?T8u4aKSAmBgf#a&NJgYT2o+*CA)IBAnQ?r`1y6*XAGp4(d{`sr;tv$XTSx%-Z z{_MDVcmJYm%x?4RJ8{=6xi_i!-pUS^b<=*Mo&7>;q_xpH3U>V__84vRXy3-_SI+}n z`qc*tzsgQYXMrPREgC8^dA`$gC4EY&0ir2;lJ6yp)oJC#tW z5Nyat$*&QP_{h2XlNzR8IV7OG=LVF>iAXnkpq>V5qHPP=HA!Z+x9Y}Q1izX{;ML!8 zeJa%Ey8gKMiYg+`_XU%YJc{-jL8Q&cD45p5Zcyu8R-a*J=EyO6<+&|gB3dw*LDRN= zo}z2L+bH*Nb;Wmzb_40~pw8{{Iqu$`Zxe?@TEAL}#QU+~8=sTU-QzL4#Rnmtk%mg6 z@o1~=7kY;!i8bY-9Ia819Kx}gga$Yh$Q-K8cyi`@S<%SPiWmj9RhT{_U0)o>BU$*| zH0Wo02eDi(bmX{F4EN5Tj}0R9%&z+nc=kR^^#>z^CrVIXuqt z>x;-b-lB%Bx17y$s@y96&H-<(=SzxffP!4DSH^VkLae+D8QwCf7T9eNyLpEv8x2o#X+Gxt&wx2U}=eU0RS=d=zhI`zg8Nv457|!s-UBvl9Cp3S1)os6e z)>hR`o^;A=%3RdSF2BFP9Uh;fL2Ky>8Pz1>Fp?EAa6+_!c#EgeKCz{)x0__`_yO>+ z$0>=5wJz!rCJ*GXHS1QjH0H^`wy?q}L&NtXSt@3aV)=?_7&AL#d!<;(B?|A8Kp!N)-2=;TnK=kAb%-nHJ zSRAb0{FD^~;5m)SXx=b3v#>R>=BEx$G<=~h&>OwJ8zFyr5*A_lZp)9zEOau7g)>4u zsb*;ECKN{5USpYC1BT-vHAUuc=+fY{t(V^KIMFPU>M0lLs`fAHv*Ga|T$}C_eQRc+ z5rf|->tw6B^GCf3L@1(-Qc-xGopPlSTCk%ycdB7fj9=X*N6fKLw0ff7+(Dz7@Mg(i zS*YO);gCPxj(J(97MAt_B( zk}rNVjVkmwvLdQb?cFGfU*FfbZvh5_TA|}4BzUyEYHu%3P)ghu6(hlHo*c^5+x592 zi^EL;i0YRG)0c(nh3O;}UzBO|0!Vw$X@sjp9xO#(-o;Haeb)Au%EP)Xv)~gPDPl7C ze*)b+BEtaC>5^3woNK(9Q`V_G_|&qwJQPcd92-2~FJWM@Z*l(ipx*E+{u9D57C`?1 z^e^~(4jGmN9X^ZMlxRB8_Ubyc-0ZwU=h4h2V)pL4h&Ii|Q^)(Zh(p>kDcem@4rJJt zi3;IiCD><&voV-1{{XVYRi;3JqrQb=aaHOGiLmkHpG-8hw(trkPF%^-c@{S zTn@S0f1;~ewHh{Pc2o9Loms`_Bpjd)2)kzH3XIKi0VGG!U8hdvRg}Oi_l~-!jHctg zVrL3Nwrow9?^4c75F?Zz<9$lkA%)0wPrB#+YZA=lPF_DHUnt^8Sb+9k3vV#7wA%L= zYg{!w$->4oRasJ9lp1hgpy1$m{$V?GJ*HMAqDLaJ!|J`D&-E3Jqq8R%~96Ewyf@6qr;$a9g(DK8WZvily_+Wo|up7gHRB=zN@h<|4a{f!$ z=Br@7?R0_8Kv9|60i#DCyGfa{IfPt@*OHvA5d%mFs%>}%9_JWT8NIiMkt)cxj^ zc&-dCT)MhvA!p8e?aM_l;lT~e#nSglzk;Q-EOB!jCdsq41bE76_w!4PnN**)q5H_O z?pkm_80M+9F``pK4NYV!g_NCD%>}$4B{OM*uHhBI%qNoec&oO`cB1)5^D4r2Y_!ZO zp#T8)o^%TxK){%StK}@vWjo5H$HGTabxwFQ&0nUrCt@3wgfh@MS$jgHfF-&g$yLSH z4G{BAo@n_5Txu5_`L&+)&42Oz)W||u+ctivSO^FvL!2S-jPGa)9|@JqtJ^MB8tl5l z^XLn9mGj2}fsXY~Bpl8G2~Ep7j)s$T$5}nwO4VG~Q;Ps5=qI~m*Jf)t0(hs?G#KpJ zX3ad;wFqd@yFz};KGd6+8J|9fhSYhMl66%;FL(pH#u3^9Oc!x#qd~9O@Ms-Yf#uK@ zo0+=!tVSGWX~<+ksZF_tvLK@0#Cb1+#buBN)Q;a20V735jVfe}yE|y9Ir3s7LCqWK z;nIE*ppm4gm~!RS?GT$2-mN_#ImV-RdxB_aH-(5lvQ!2sO}j;*~Df6yi zOBYq`I=4aeLfcmUXc!bJ!nK4V0R4&cY3Ldh4)EPE`mf#3fLqKtVBdnpI+%+>#ng4Q zo@%9ow1dZqL>%LC$cRGbeaA+6AK0rEh6kO`yYniE23O$nhiCZ^nIsMc;Kkd37;h$;_dDxUpU z`^A3Ix2VFylv^oTwlle(-j4NUTa4UI(Ij_1KFN%88K5K;hooUrr@>I9XH(4pBY-wh zJf?cl@>xAAC!rSlR!>67=|Y#G3VwyM^evyE7J3n<=tYD4h|}~TPtb)wLKLI<6Dax< zX?hT+=t7tD(52{2rRYMRp)!}DQ={lqsd@sZNBUt?q5UwaQ2v^wN6@KJ^eR++0aByr zRA~AYIv>+i==u{Ve@#)Kf9a|;JqnEhnOGxqyNMJDi8qx0s;a8 z0R#dA0RRI4000315g{=_QDJd`Ad#W55b(j#@!>E~VE@_x2mt{A0Y4D`0PQT_WB6bC zbN-zF0JHpG{WvpD zm~I4gm_cQe$ODxc!h3(9u`6W%en>f-|304)- zFEYF6yHc-8gm*V6?3!nRYW4gIlge=ME3=^2O*xGlg8En@JTdytS#VRRrqS$l=;PA^ z(<9PLE*D3MeR7b-#YA$KRIo4h;0@vL1hHiRg11mERT}Uue35t9LUq}ICU9OPEVjU+ z~nuN}?n9QgO=t9MfGf4}@?O>q_$!`7O z8wp50tSj6O#ZyZaxigz7QnyVTp!EUh1*6DCDg;-&$;OdNY*I7z z!3GdxZ%9vM9JZfM-vY`DgbWH;(TA2m9Sug(7jRq2?cmMFe&_L~@}Ldjsc4FYnu)gy z+SSDhxeNdz64^>reGZ{c;e6TpLV^ww zRvk=lQK(`B9H>AVg6xJ?C5Gdtl)ePA;3=?X04E|kZ^uXwYNK!bOc*29U%S+CS`Lzz z?aDNuU`Po{0&`>zP>HV$!Z{mh{t>*qoYbT?E`5UNBRfYZmaT6Ry(JmZ$>G2rlgmm~V<_DE()U$Vk zxp=-)H7{3A6IQMR8cHd#C3{P@U+WB`?*9PtMNB2buy;!qoyZo&WeEFns;M=I&I5wl zC}tO^T)m~UpP4jaG4N?%{lQ`RSLBb4b*qhjmHz;$VOddn{_~K_hy61I0;wlVU0kb) zYD0no$!yM7f#&fsvRFw`X%v4QMu-j}CvacW{6LX~_<%U82+F|ZD+0!zh-pmV68Bk` zUM=K5aFk2u3ixA(;&S>d6ak$4chJh5(BhsjE75Y3skf31(VJ$@kqn!NkHX=D{gLJS z650}~g=2>^go^mjnzjf#H4bkjgDi@m&OO+{8)~a&pL|QeUkcRw65Ixs!#{Wd^oG;g z+z%Ra+OaGwfLCN@E%rOvk~2wUS)Gl-ID~zuEX+R$ej;6#W$}iB1)DjjzerJqwpc=v z_{_dUR}1FzxL4C@qY7nD1ELA&N@FP6o;E^ec9q-$bYP5FKa%kszF5_<9vdy|P08Sy zqfs*}DBIz_qfI7BEviRQ?Y@DZj`|oJvS?C?R({a3Hgb)y)n8y-8%#n1DWi>_Fqh^* zst$$fdk&?)Ns6Lf+5V_EUN&t9?|RvfYCkA*N+h9J13+$^tHNzk||3UYb?WT^APAyEw0yex`nI+|Gp3 zr70D^W9W3pxSUY2ZFoESu#SQ)9fwV3B>@$}@)Vc7Y(*GfP&PFnqy-v@grIQ(14|*R zUSj!X0~u;`Slh}}0^K74FwmRBaVykO#XDr}HmY~65Tc+2yWXPPmgJlnWs3q6TOgNg ztca!{G>k!$m9QzU0KayBYV!dsRG@A;{1U{mhd^3ebYt!WEN@$@4g^Yk+ThxbBIZ;S zwt~c*o)6Gl%(089gd)c!6M|euBmk7MUH(f^-}N!{I$}D07)B8Y=BhOdURau{tFw%r zVS=;5%nSgnMa+g+jr6H%;!~1TC?_`%(1aq*i+%OLJVRxqMIDyz4d}YW#tWn?<$C0Y zG)HX%^$b-;ph?FG${9Hgz#euR4*vjjOUiiAOG`2qNJ5-2pK+LBh*`-|z7h8j zv%`E-9kWDFCZTF~T3r+RKE8)gs_F+g0ci{}$8Z1#wSc+yVVXJ_|zPRp)fKM1;5g^FhP1uAFnzgqRb-KP_z-G&~e^=Mg!i@1wL(|HQ1ggkR1bZ^QcHXI-44nq2(PWv{X!yRe{q;A(f!Aem#z zqXk{J4N6w<#1%O(2@T`2kYAZW5M?i=j&<5xn`#JFO`=$;N@2^vU>i=H#x1Be+c;dq zKf_<3F@O-W4iXxNs6&=*3VF<0%}lFl2iiYyQDqbc-Yd2RmNpE(mQlkR!Jg$>{wPxw zGK^>+(2g;C?ZJUi)ITUB9Rp&zIfCozgfot43u6vi0lzU4fD{he5GdY`52)T-Wm)}i zUqhxZbU<3-SX^r*Jcz8jO47!`Ix<%1UCF_sfpM1rP%NBCv(iQ*;-P6=B1 zfShLIwBh|B9#yP-%Y-JI3`HOd7XJV#hxGCEI$?S|Qlnf3ItC3ZIXETAq0+!0Cg3^k zp2T7WBM>ub0WO(MlQRYf?Vux zVg|%3T(H0a-HYUe7qKu#V+sfDn2cAT{6R&Nh~pVF%Pt+wQw}cagRi-g zo#Ef_`-_Xch?@nE>w5YfFs(KZm`*Kl7M%HmI+nt35Tq0fjn449y{_1-EVm=cTo zk&-amOYEsgL<^XOi>(C2=8BZjvvH1A6BQRMM4A_#A5erVIDdkQ;*f|Soz+-v|G$=$=S)>mEpp9ihG;szi5D7$a6cErZuE->qx?T8t;$`QDsISt7eWjJ* zhK+heMYDig#6CM5nx_O5J$}ET(*VT5YH-VfZ=X6-NmdhgDmrR--w~6T)-Xg^yOwS} z%m8^c2ZSPFH)zoY5|Q-?9V2ya-_)VxmI#fN8_X$ri!|G|&_p(xqfiJLX0}d%dkbTo z@N;&yLZ1j(sT?o>SR5auqFe{kE;d^mc&eCaDbQ47KMxCR0xS7Ka2G$fqVCbC=7bYG zL;D^Xj*Z8OBM!hLJz;?^NiYT} zFppw0O)W)+p>5X}sI_v{hGUSVRx?W}ZZ=-f0F16v?4|@Z>-)29!Tom(E}!3+*1i7# z*D)6CH%ad;B=2S-Vku@}0?~wUAiV43C1B)rW>BG0DNei( zcV!{D`T*?go2HPIdb`T5bqO~I+i>Betn2thR88@){PH!EvpTY&l~F_!Yyr^v7-ntq zDlcm_5G-c6Qs)MR_F>zU3kzj-%bO)=OTvhfh@{hID{YWas36oM$U`(qM6mG``P26Tv%@MzBfKgYBbpDqt&v#)z$a01WFUiG(>-b!`Ia>MfD8P8(*QGL zs)F{qxc>kMps^oS3#GcWRnjX6eIG2s{DeSvRF8I}G5KlAJmy=Dg6umMh_{sEN@FE2 zPAKtXQSHMSV|JK=+gVXB0l=U(3wj%k0FD0u&LkHAF5Al#6V^I5XepREq$UMg93Dwn zNK|5R#B|D4kKkRDhpUW0IO?0<|T15Hg4X8ANKSLt$q%2q2c^ zmkv@aCHQkN?4np*284dKsYyvOH7VaX?Fx&AxDztW!c(bH!`^FjBUUprW`(ry=>@Ob zg?SHUuMT5a3?kYI)FEnX$tudt1-cI9EkkLb%pKsB>xcrS+A9s^y|m0iDRg$;BUsNw ziK8hl=k?uv8$C=m)BA|F1cyTott^B*081SRL0u7)MQTFaL2~C=g}*B@jXXuli~}bK zEsUrTj-bY`Sfy|A1Btw~{{RqxX{CR`12sovzXdVMqR25$Zl*lNf5Q@*uD!9LvIYrl zZ#@QpMZ>81ig%SIrN)-VqBWbl;qpF6J16cQ#13Ha9bF;aumgc@V2}8+=LPbPi=vA} z)}@OKiB-f6Y3MpPVBx6krVziJ#HBTaL*-J4IOSH}12VNv7(my6n5RNqnPZxNWGcxS zW`R&ZjNebTU{xg3F7Yz03RLC)05uYrT2))OP5iKIvj_3tL#8JQee)3Vq~lb}3%KH% z)~T2NCK=JtB{SwgI|>-r4Zdt`4i479Vs{x#tY7}+xT|u2!Qes+{gw-nY$M=+D$G_d zjKD&lls6_*W!G`?k3DaToUU0#Etw5vg9nk8@?BP80IID7TS#otz0A>-n<$D{7I%6} z`L@-kW2or=01C|OV=CNWP!*Mf!y8dcm6!~x_$mQrL>>@Oqvkkn?W6{39!W8_hzO;% zx%PtL#%<|%X0*Y?`$MT!Pluh17!X0wM^=?DOSk}p1#&RlfUsZ&aZ~VLM$c3Fv^b1f zX`1Q)1#ZAND-g~j6cHmT(G*{hC11jpYhBXAA_uT>wiXGATnh9@slmX+Ic9@~C!JJj z7Vi_WOH@>a&>)%Lzx$&E$FeNi)vz6X$CsV1=D`kVC>Y|R(DNG-hFTCO4tXRs`?GOaTZJ!dCft2E@2a}SmA;h5@2`XV{VYY1Agt?R!iWGu^I}b9p zfQCh|_fg})P#)zBuBO&JA^}l}vVl$ZC5bf!hubLZWhE!#eiP`~>Sv&-tBPQ z09Wz2$507NV}$K92kHeS1=@bHp~GGDB6mpt8HbrE32yf?joKj{2rL@Q!yegY#teLLt@z#PJIX2A%zjG z1#|?i(sy8ns(fFv4uJHV5Tw!e1!ZelL4B5>t4Fvl&Z*J0j;cB|v*3@SXN;x%+AARs zVc~)&+jPZ*Q%7r<&8sjni(DB{z`dhVN!Ml3y?TUr=)5Sa@FSRHO;pJgx2W2(Y`#yE z9aVtP=e)x-?%>t4@eiYCsAn;s+y>ny%7CLboZofS%>}^%*+MN>&oDRSH&2K%%e6A= zN=D1<P&apT)|@^te<2gdl1}pj%P8ktZqDIbVU|Yz>DP)64RFE`OQgj&+!H-8I;bjWmhsb#ZQl}rP1#P;3B_* zB94DzC3XTSVheuBL`B=vs7f^)F90MKNcQX^U0Onaw8m(BNV;%kJa z*m;ied;Ptz5Mb=MdW~CvX4yByWX#X}(dUE50zeR{3iXU&D6W!Virb7ISx4RG40jLC)?ve##u*5uJY_nIcYt zK+P{m-H*4MJ9~r2@bT46?Sb9K%kH%Etp0e$?beh=N z&%$7VFnE6&Lognr(|s%o1Ec={)Bgbf!~ixC00IF51p)*G0|EvE00000009C65d;tt zAu$sm6f!|k1tL;maU(NRG-4z$LPL?EP+)TZ+5iXv0s#R(0RI5WIV5XFvstXxg(d!F z(k_dx`=aR7jY!muOS0w5qf#!5qU-#RiB+jh{IArfhs4x`WU94s;qeRo=6GyR@}3(L z{H%@_62ILgLlgX@saK~Px~y2LsS&MSQEhOK7gyYlBCOq$xmLYuR@8Xe`->M-l6cA6 zlq&d{d0E!Q$96**QTdTPM9Ot4)OJ#_(XafB=~wS^og2 z=+^qqm48X2rC;hpoa1E4)|3_5xSjSRIHso~`?R~{2@Af=I=O-Ah3*s)g8pN++ z_>ZvsSEiEK&#`P-I=G5bikswIcKlu0ugQk}h<*lzos3GgF_b@MMAqgWs-;m}_=ge8 zh?Hn+cOwNIk)f4oD_+FYRxpm!8@^U7Sg?kRWi39YE^1Oq5u-YsE0ieIrB*G+VJdD~ zy-056VHN94lrAF0ixx4<=cV~#;dVX`i}H#J)S>?X%FSnq-VAHyMj2jk{Ms_aJGA3_tAE)NkuV_Vm$qIIV;PuPO9A#H?{ zWr?D@DHO=(tFl~{E2c@i*u%x>8Y_P5G{;GVNlo@LD5*)!EzEM$Dkxko--)Zueo8HL z%grO(y2#jds|<&hui*!y+n?iH>)zNehnOiFu>>DgNAl86jlTDtSaf{HVEnnh{n> zNY@{7bBaXgshkvQD80y4OpJvjYDLj>T^B@^$!v;~ZIs(`A;6hadWCu`n3z4L#4g-h zy?P?;_=??rN-p%{_{}l0_bPdEjJ7#78qH&p48K*Hds&J7`atX@zMHOq+ z63LC&lW46b(LoDjCvz!PdC&wS9=e(P_yGh1*r6 zRg`RajWJ0TF$z$(sYa}tNwQon%3ell+)WxptW-i`9|d14DgMPmlD$E0tSqiNl;gQa%!aO!q_L!nv}`zu zG{uypAsm%_r9bKBQ2oL?I}t22A)?!4*5;jx>d`4Z$h*a4-s2+nHKEI66zww$D+*}V zV&1(!VQ{-~Toj~5readlu}jR4Oqht}r!A~W7PfV~r9bKA`DPz!ihGJfpWISR<1L2J ztV()OUl88NqrjU{Db;gB5q4@srE;>oh-ph^gvn20tJqvF+*breI}Tcvh$X0Z$+2yc zOhklOsm67@r7!8_`4pON#AewUzjIS5w|tQ#Sd<&}B~9Cr;qJ)8PRIILN661p6H(Ho zDKA7*_{~Ust|^b>5nRBZ##8dZr&-sd88yjXtw_{%XNkmpY6wl)GU;d zEUd&wc88|K(>EZAEB0FC{#tVUk)tWyqBwb>K!rPsor?(;&7{Xo4HAr+WhgkOm&7*1 zNQ=841LYVW=pc+-lB~^WZ)4$7YOMbN0^_$4>|k$lq0(_(&|u>MLZ>Ux`Q4Q6Z~>2VXDFW(P+X=LkkrB zj6$hWysZ{^dj9}Kzum7;~i-jkp{WQr#Cbu62-?)i8hB^RuUwPPSp%20xV-ccAw#kh1)k|Qd+9Jj*@b@2**h2 zV?-aJQkKrd8&a^51Y0(?D&0+*gzinEGLlxmCKjA;a_b}_#fGv)i49$r%4n?xBMTcv zzzfw4B?{mYnJTqd$$#8giePk)hJh7`2gl?oNwBmK?o+bxg zpVWAW3lmG+oMQfBRHD_$s!eG~uLT#CI*trji;EIct*TZQZ5CO{64=yTl942uFuS=d ztTmc3Kh@Lj#y{1E)I;!}(e~#8;C;GAckdl;B zS>HPRA|=a;>`9{5ie#G{nFmr_4mFY`boU!YI+0GybBac^Lv}}u+PbizV#u*AiM3`& zlI2IevY?Y!L)gA|8yRzhFQ>fI4&g+vOrnWD6di7@L7{;F?VF7 zY7;dy&1{8Pd$X@EbHq#Co+4i7h@ZLQXYM>irRq|5sEl3I$_m(a*@SKDC+B2LG+Mp# zMT-_5#v)1Lsn}hQhGStTHD$voVyjbD(Q)HyO5dc#jH;6TCV0xf!p|93){{JRzloEq z>PL$f-!02Z{1%yM8e}a+I`fXq@hjM^QdKxUV$$|LZ(`5b(pt-b>c0og?90p9pEuIa zo9SYU_7Z8QW2;J{`MD=vDmr3{Gp9{5q?4P{MYYNyiG@Ef@suaU$YSY1r0zU@6!>HK zg&%1iK997C|>)Day%@37_iR%fBHHy`p%5Lzxp~d`p%2@L!*CF z!~Xzr;r{@*@c#hZMvk9mbWzbqK^+uyQP4+09SEHWod}%-bP>=(qZE#eJ&ue$j*LBr zMS581ea@5mj+DNmqZ6S4P>MP}>~tXg5b&`U9Vf~j9t`l%JTwmt3kwNn%Kre5{iFZH z06!4`0RsX90t*KN0tE#C0000100IL95d{(<5HS-J6(BM}QBqTJkp?0&LPKG4G=ZTO zBqK0jVv;2_M1sNp+5iXv0|5a)0RI3}K^S;9Me($em2i>wR|_9?aIyDS3m|OB%13F_~@FY@%jJzEQCPKBF^4!3TILD02P9lHdB**v_xYatn^mLI)e(M~W320);g#O-~FSGq-zg zsU>`vg!Z^?h*(I=i@WWaT@lTv=)0Xu{{Y1E@4L+%hjO`BRo3E?{v|#ju;~8)v#V$t zmZM27zT>?UV0K^tH(0z*G1J^`Vhp;aj0xht?BO%2%G#l`7PlCG5CNmn zy##@(I=J39r&dJ4y;tHT?aC9JUP&ckY|l~}si848%F5eD!Vpigu7)|7TIU9*Qe>*& z^IQTIAYh0Fh4QRUn3-Po_UypFUOy6tIu3*R)Z5RJaQBKE3J5B{(@FT1l~M~+N93}s zs>;i$VwMw&_AJfqPmnYdbt8+7&desFI%PCpm-f&MMEpyV%sR9$i}y@Y|4mML};;W@=DtS zpt9g!*inuBg*;h7OzD{;f#?gB9`ylCCrwZ;?Mx@NT=uNa?L`4{oJb@pi?xK^Wo(ZP zbFzchp<`pIb6V`cb*gHS2-k9szA0Mw4b9%AkVzw)Hxh}^tOx$!e-eS)Wp#BC0gvZE zY=30qa#n~Ct`)WgZ?d+V0oi3_VTknvV2irc>UdAc7B@o3Lu6pEJJuS&Y3jcPM@Z_K zax~bcVH2{)FioOx-i0QJQxVpMI^Y7}0&D{5^s(=~Mez=|V6v3f=pnOmV7 z)d0Nejkbs)G%8leUficZsvPD^W(`PKgoY|E4p&|7I&*G{!v6qU59Q9r+*;U=`<5#q zFhTbTkw-NQZ9QRB(io_i!T@${>X!;`MwcIY_doyu>>FFSqT;g^aj+}xzN;H)eJz5Z z1+>$H-B@0g7hfYvvbN1OTWMIM-I3v8n$DmZV`x$vMo(Z*t$SXDSm8^^xhl4rrnbeg ze)mTQu0J64T#sGhk5x1>K=Q|n5UJ@Vsw76+*>Wv+hK>teZ-%h!Dy}-H+~!y`-<^$s zL|5%tjI{5GfsVVH6qVM37BR-{-m7sIR8ujaoa1_;t(V-4pO`4k#@44HuxznIU<(!a z1I<$W3Xdg1Z7ON^8|AmDSfR4$0zgM{#dT>|c9S0^N=b-aP4J)OpR0-;A?BhU<9wBs zipB@`uU^iZK3~~6YPTMCJblR1D5|CRn;VGjT$@+nl_ebTw(em8QiH}L^Gp^B`fLWs z>a2i81F&o>6>t!MscpsTe+7qv`K%K<4f5t$TWB^4>lA^e2N0-qn5sFOkOffiA#!o| zie>W+6a=}0ODiX67A!-m-c|`5tdO_^Vi4S{o;ld-z1V`m>fbAjE*5ADC<_?_i66)+ zP)$sKkY6erw!3BYM4_;3D;6K&0;vt@>VFl3qt4!m#|o zaJsG>1SZV5KsS&V3f}NWSlS6CVwLZhr*x%CgD-ENGln%>+Vji`odYVlowlw$w0wBVgXK){ZLDd)(|^LmQzW4eBR@ zO&8)2Dy(Lwc>69c89Yu0QgRR)wK&8{VRO=*x}Y6H32*eKM=3?RWB`o*#{F- zADVAP4ckveTbM#_+TMs?_|*#m(X#o4eacvybk=|n+^nt52(i6jAlT7sI~8+iBL_LN z$TnWgR2O0_Y22Sx0}ihXj??$Ys*a*5H#jVIp`#O(VUJ;^Dl&iVh$yQ8zqdw^&VzQn*@=eO5o$jK90(v29+Jl|iocFj`l6lzn z_2*(R_*Acr%?CGH zf}!x#HSOPZ1kZaKUDg7+E?Aq%td{-dgH+7+?gczJD&`xdvg zwN$s@&Ggk%5GrGF>L`$P2yME$x(3Lb?Y_#{8Z;?@IvFpz%MW`f-0{@njbuZu37G9r zkR9LTzNRR&aZRqKC!_-98Zdq+RgR^_OYI>BAV@u_zU+g|KrIt|mG)wTEo7gPz&A_# zAXU)kR6Mq5+tfi+hlIqOU9P1|M8j6eBk14W9f-r4c^cl;z(~zVO{<-nPP-bIz$OY^-yf8=>BymN+pN7dU0P z)l%Y3WmJuEyBt+jQ-xdI8??HHq|V*?^@PcQh{tW{!x=X%Qou5tp+Mrv+2#;F=-5z0 za(1e`<*Jj-XICXXW*`yTuqs$*bdP?egjgoW8Q##05QC#a%HE;=Nn=RdvNy0U3O?vn z^zDd;4z*DOWEqBpFK4ZJhuCcht0JNrbFoZ5YS+cVxC>tB`#C83p$}(f@j^b&Oir?d z+ybSY8A2E>U^>bZaJsf0m~wn_MC`A!bR&gpz}$6Qr${s}0dlP;h!-i*pQslp(fEN3 zN|60Poruzb@dedHG-alDYjr&>JE3f`+zaZWj)1+ffLuz%Ama0ujmYm*m6K7tzB9ji zW;;91peS)d_KSrLZwT-$&L?Zdmm|?D+5Vj0w$aRscQ|b% z1*XoWix(zFI-Q^seaa{r_S~UL&eUmIddg%l8b-25D!5uH zL{Vx9R5aBT(*WjN9<__bBkGHQ(5F+%HOi?dr>u~*gK};GQqg?vOv9&-OMy-OP>JYw2e zG>~*QQM~FiUdrJ%C&qN$Gca#>3p;zkTy;1s zR!H3|Lv3(1QxX8|zN-m+8?%^OXINjIr#=yIN_M*nI|9b1jj@Q!ZsXRC)DHKG%&?7G z^wj9%cJL5rZsD=P5Tt}l8<=-lNbHUyu&Drf2XP&0$G%iDJ%;(zHE)hk;^IPzp^|`F z@KKQo0y4F5p&1&TD;O?HZ@ctDHl5GqH~@e;NxZmOD78x&j@pNCp?!DPN~N1 zK1k+JnC7 zlD&sVAz3*2%H!1?^~b6^<#Fnc`CNLVzMoYzg3fU%j`zo!#T;8G`-MlP4MUa``@T=W zr#s##JXns^fYQ$c>e9v6CAI4GK8!7~}DOh0B;{Ff+Ec=7)L$#KeK_2czW)x#r881}o%og`69(_nX+ z;#7VMeHRj>@LT8?6Q=N)=(wdnhR;RCDf~8iE-6dkv(a%{Uj?3viqm*3^jub#!Dpi4 zl)ei+7Zs)OS?IW(FNDuU#OZt{dM+nR;WyE7I$sICi;2?sP4rw&m%?wN;#9s9Jr@$C z@R{hil`n$NMCuAheJ1)LLr6Z8Jr@$B@LA}%oiBvXMa1cRCVDO>OW`xo8aiJIo{NZ5 zAEw_$$@E=twH!K!z-r{mF9oZT=zJEgOQG;uxhjLfYUHX90jS|L9t&3`Q20S|T^EEG qB~Tsl1<6=