From 599b535ca7ca44a381324ee7d6c5be54e5106a8d Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Thu, 8 Feb 2024 18:36:26 +0100 Subject: [PATCH] Thread: make HA first Thread network (#31317) * Thread: make HA first Thread network * Fix terminology * Update screenshot to show HA-only Thread network * Add step result * Rephrase * Rephrase --- source/_integrations/thread.markdown | 48 +++++++++++++----- .../thread-preferred-network-ha-only.png | Bin 0 -> 22038 bytes 2 files changed, 34 insertions(+), 14 deletions(-) create mode 100644 source/images/integrations/thread/thread-preferred-network-ha-only.png diff --git a/source/_integrations/thread.markdown b/source/_integrations/thread.markdown index 49cc52c4bd1..76662a05295 100644 --- a/source/_integrations/thread.markdown +++ b/source/_integrations/thread.markdown @@ -82,8 +82,7 @@ These border routers may require an iPhone or Android phone for onboarding. What The Thread support on these devices is in experimental state. Out of the box, they run Zigbee, not Thread. -- [Home Assistant Yellow](/yellow/). Follow this procedure to [enable Thread on Yellow](https://yellow.home-assistant.io/procedures/enable-thread/). -- [Home Assistant SkyConnect](/skyconnect/) USB stick. Follow this procedure to [enable Thread on SkyConnect](https://skyconnect.home-assistant.io/procedures/enable-thread/). +- If you have a Home Assistant Yellow or SkyConnect, you can use their Thread radio. Follow these steps to [turn Home Assistant into a Thread border router](#turning-home-assistant-into-a-thread-border-router). #### Google @@ -99,6 +98,39 @@ The Thread support on these devices is in experimental state. Out of the box, th There are also other companies that provide devices with border router capability, such as Nanoleaf or Amazon. +## Turning Home Assistant into a Thread border router + +Follow these steps if you want to turn Home Assistant into a Thread border router using the Thread radio of Yellow, SkyConnect, or another compatible radio. + +Find out if you already have Thread networks: + +- Go to {% my integrations title="**Settings** > **Devices & Services**" %}. +- If you do not see a **Thread** integration, add it. +- Then, select **Configure** and check if you see any Thread networks on the overview page. +- If you do not have any Thread networks yet, follow [Make Home Assistant your first Thread network](#to-make-home-assistant-your-first-thread-network) + +### To make Home Assistant your first Thread network + +Currently this use case requires an Android phone. If you want to add Matter devices via an iOS phone, this use case is not supported yet. + +1. To enable Thread support on your Home Assistant Yellow or SkyConnect, you need to install the **OpenThread Border Router** add-on. Follow the corresponding procedure: + - [Enable Thread on Home Assistant Yellow](https://yellow.home-assistant.io/procedures/enable-thread/). + - [Enable Thread on Home Assistant SkyConnect](https://skyconnect.home-assistant.io/procedures/enable-thread/). + +2. Make sure the Home Assistant Thread network is defined as preferred network. + - This should happen automatically, but check to be sure. + - Go to {% my integrations title="**Settings** > **Devices & Services**" %}, select the **Thread** integration. + - Then, select **Configure**. + - You should see the Home Assistant logo under **Preferred network**. + + ![image](/images/integrations/thread/thread-preferred-network-ha-only.png) + +3. To add Matter-based Thread devices, your phone needs to know the credentials of your newly created Thread network. + - To share the credentials with your Android phone, open the Home Assistant Companion app. + - In the Companion app, go to **Settings** > **Companion app** > **Troubleshooting**, then select **Sync Thread credentials**. + - Follow the instructions on screen. + - **Result**: You will see a confirmation stating that Thread credentials from Home Assistant have been added to this device. + ## Understanding the Thread configuration page This section explains why you might see multiple networks on the Thread configuration page and what this means for your network. @@ -140,19 +172,7 @@ You can only set a Thread network as preferred if the credentials are known. - Importing the credentials allows a Google- or Apple-created Thread network to be the preferred network of Home Assistant. -#### Using Home Assistant as a TBR without setting up another vendor's TBR first -This scenario currently only works in one particular case, under the following conditions: - -- Make sure there are no other Thread networks set up: - - For example: Make sure you do not have any Google TBRs set up yet (otherwise the Google TBR will be the preferred Thread network, and Android APIs do not allow to change that currently). -- You have the OpenThread Border Router add-on installed. If you have the experimental Silicon Labs Multiprotocol add-on installed, we recommend migrating to the pure Thread firmware, as especially Thread traffic appears to cause stability issues. For instructions on how to enable/migrate to a dedicated Thread setup on SkyConnect or Yellow, refer to the following guides: - - [Enabling Thread on SkyConnect](https://skyconnect.home-assistant.io/procedures/enable-thread/) - - [Enabling Thread on Yellow](https://yellow.home-assistant.io/procedures/enable-thread/) -- You have an Android phone and the Home Assistant Companion App. (Note: this does not work with the iOS Companion App). -- The devices you want to add to the network support {% term Matter %}. For instructions on how to add Thread-based {% term Matter %} devices, refer to the section [Adding a Matter device to Home Assistant](/integrations/matter/#adding-a-matter-device-to-home-assistant) - -Which TBRs are supported mostly depends on (access to) the Thread credentials. And Thread credentials are required during on-boarding/commissioning, which is part of the smart home protocol. ### Combining Thread networks diff --git a/source/images/integrations/thread/thread-preferred-network-ha-only.png b/source/images/integrations/thread/thread-preferred-network-ha-only.png new file mode 100644 index 0000000000000000000000000000000000000000..f34e838311e705bb00eefc947b2e80771f8698cc GIT binary patch literal 22038 zcmbTe1ymeC*ETq~OK>NI;O-8=gF|q4cXvr}cL?q_1PDI3ySux4aEBe<|NFnQ-|n8X zXO}tMJ>AnY)m69Z*7H2~7U7EWk|>A-hyVZpMe4iQ4*&qt9sq!VgNFt0WBuamz=t49 zQBg%HQPIy1PWEP&Hl_dob-Zu9!1tbSM1A_o^+hT~r@7m4dAyqF*p9QbSa~9)*jld4 zO*csC>|YreV}4n8b;b4p10!oIQ7eCaet_6M-7Gx(Lh;5#Qx|r*2_n5X7dT&s5GfdC zFSjO|yaA?3_x8!UsUo+Ed_yO@F;Fy1VWEcq3}F8aE11_?m4R zqDis-IeYyNLFRop`5)@?-h*CaO5M1J_>+hc`%ENMBz`udV&&`JPe#>~UD9y1`DLFJ zK1r&|mH3eD)C_w@)~Z!j&kH;v_3-$brk${d#&>>6`79jti$I#XAOf#~mj>rY9qIi) zG#g63D(wVt_s z0n@XpSFqgN&=N>VZReNg2Iltf*_OBWP}iYOE`)HirC>wB8p%kCfsf$7N6{94@B!aN zT*F1w-qzOC&IKUqWNPSQYVz6L(#7Jlq?DYZ`cG6`0N^t~N=#VAWBGK=Uqj^}>)$(< zlDQ4nUu`5g%)vx+RLcp2$iU}KihQBrx29 zeGadn7=f(%JHaPgVOxN0CkTQvSxPpz68W)v>j$cqx~TYMH|} zSHZ&S3o1W%HjKa*S5nO9@(eW{$WX)zJ{@i*8`q(i2tG`Dp){qL$~dpXQ4efCXA%+; z`UbZL*V==MHP4=*7mEb12zmY+he{vyYVWf?YFq8L(WpdO@<|!!&o&~!$bCs_)ZMFH z2|M^uE}6O?S~lXBl2T`TBy@q(fLf*x&tR%3+M|<4pWkC~Mek22I7O_Y`}gw7*DF@* zH?L0t9nn{|yrFa%H;ZDYsMIdV#ULXzN@MyRsNq3Wk6*bz$#x5)2NLu`3TiNX{dgg~ z1S(l-C+Pz5K?3PE3m&j7((v$qYquO=%xcrNx3~3ftCsV(=lwKC(mV9F%e*g)RyHad z^gMNCm9T6$wJ%~E!G#X7{Rjkk+sVV9$|cX+MLl=CZ$ovSm{&Fsc{T(joJkR_B&fIt z_`{krD4v+eOnW8F<0>j~S@vbCBs3&_=l$}PxXI9$a3Mb~(5H<1<3)zOfbE$XhvRNd zSJ`&5UR=j&=N5A!Uj_Pcp|2TZt$r90Z&fht{NuQ$065dyqrST*6@`hhQ@CySDBSKs z=PK)K9##jEe_Gjiqr`R>V3$jbIC)|Ut#O$!MU5`h#zIv7qJ-tVhR$~xpKUpunN1e+ zg5|IeiJrRDVvppx6U_x!=HFPc>Qmi6*s(JO^=y5KJ8o9+(iua=;j|xz>0kl03O2dx zn}9nkBH->~W5W-UegjDC{B&b^-f|%r?wA0$4~menbV1cr($cf|ZKqVYtwjjpj-C^8FhTR>G2qC0Q${t+cm>x)3;QaxQ*! zb!7akr}UeBIj0HkX3-{8KoaAvi&`Eoh6TwHqK~j29lv&!P5HQ8y)Kjo!kt&kB^U*ieBc_=m~b;+VrtkkE_!{l%t@apbw|)Ma7`k znv&%t8xv!ukiXx7QKswf?9rV2os!^+oF>|(gx+lBY}7X66=fQ3Bvlyv!lLsVJr$4r zO|66mqLVp&fb~LUvWwVsy!NT2(38>(4%O~weOmdC*Y`fxIkHrAfqS7jP5FmG&#Y`) z>6VGZ7QMY1TyN(<5x8W`=qw|L~FG;}VIcHsV8TvatCxGO#yGdv=qoBiEgE^;#T@6IRHyW(93k-@2yI9RH4 zEC%_l5lhCYIRYUv(Jz^YZumTGEiTMlx&oYM-4Wo-DTD1&XMq{~y~X{Dp?3ErL#HfSS$ zm78EXB7{>%i1>*V^dF6iDPg5Z(vA(YBqSt22AFyxP#rU-v(X_!3sHE#;t;T!z=MrT z9nt-8xx?p*U>oVj&0~R1e7R(vb2+Q5;J7;&Z!NFwPn^fj?WoLd=ioH?*=t@n5WVqF z7sW2Gl97A-kHc=fmdHH{c`Rkf2qQ6;fdXm?*~>InDS!5AiHXE7+fj&*2$a(dh^9w4 zrxY3IhpA?(LtjHN6M7IHrLnj7xj^;$di(2v9IM`cLq>=}5sX3t**8Ak89OI@!O_)e zXDP8?tFQg}$4)&!G5>b5N4i^{8Fbgqwn9nmoK!{aeVXRR z8m#7M!M13A%iY2i`p0imxNZ#LUTtk4WN&Oe@}x2`{I#gE#Kaq;yaD&G)d7oqdyX)} zY=sR&c>~ezYZUv1PnoqltN)u%CiaE06VBbKCR(PEt-R_Q7OrN?^~BeT4XL4}%Cc5+ z$rumvO7@1BqwmHodGPMI1lT=KjZd8^>m*yfV@Ejge%w=M?Jrj{=WX}v^Bq4rUhlNa z$fitB-C7!}>j}1kKznOnM7{@NPHzT*yKiAvIA1DJ5n{N52tg)#V`Z0I7<@-%@YzvF zsy5K7^t4ZJWmAU-g^%^-h|_%8`^KZOVloBc>gxy}b2rarbmm}Pv-xodm$x6&x2`V} zwE+j>?7r)jRAHWiEz$y2wz^8|SH~C=E=Ac+1^hE|ONRDXP2G7uD0#Kci!8!0IJADi^mPndf?AA(}RF=Qg@; zB!$O%z$seiA`BA1!`my){bfEJ{pk=jUx9xB37hh7hbmWWcIvebJHPTGgZHJ|$d;g| zP+C|iLXd*y4)I;XTm%8Zloje8?ll1r$mx0P;jL6^cJ!H2EV^(OA;p6Hlfs4J!|=}N zV~>;?i9mn9!g@&V(Yg~WeKg@;)bcs$+37D!8EpYKJqSlQpZ<44B9NiT-w-jZ&p7Ol z;{W>ftI(_$rM#>x&;R|+RuWWeJ|S(4soTG>km~=kLn;@-aTMBeQrU7iQxZFyboj%z zJzRnyBQ6jY{44O54%>GY4#^96_VV=5!}%P<%W(#tpee(A=rhH@PXR6nn;QROoS!Mk!IYeseavT9kiK2K|4w zdZ{QO=dg;!jLHYE4m=^Mu|XC%BkGou5Nkj9or6rXppG^)u%-*JQzQJ);en z(HY4CpkrjHqA+y6&D}`_j69S6xIFf_8~ah(@sHn53Zkk~52f>OU5{J@a*D5?jO|8y zmU4-_rx0Oumba~CVvN2gUfy9TkMlmW%_4KQ$9A~2{0eACodE2Yug1NnoLj{ISFit% zu^M0xZnCilquMTKq*hLUY)x-2?=93l?os|7%HJH7``0?P)Q;lti;b|QEn!&hHa7HM zs}aKj!c+$B5Zrc+0CC&YQ80CiOG+wt(OpqjJrkuPX`(p_6|Z5A`L{_tqXLFau8^SK zB%B#4u>oddCuRhkiKfY0$Lb_|Kce?8QGDJ-1*><|uf!esD^dehaRn;>WqVX>hrpPZ zorXW~;!3ST`JwC}Z?ySM2i?7P(E~nqUvJz49=E=HYQ*qIVr@6WeEfo;=`IciQ6*k? z!`xQC)=&;mf7O=-_UKMgjx+h341>b_{9nC3)XrX&dt+5MnN|+lUpB)9ppQdpyr7d* z)gawy&*XyGJa>JK?M zvrMf+PJ;8xsYywN_{gwh2Fw=u#%dK>b6b{#jn&p}FPt$p0Py^9J<}aBu=)J(@b7l8 zWlu=GuB?Z+0}Wfx##u++LI~0|yGotM0(70p?da=1QNOa;{xGn|IqyHq?8Rw9NJ&XKP=@xEok*n%kp|R_&iv6jO{22CG+MfD z9PAE8sG>fFJqY;U`aXnpmGgH3I0pK$Z%)35Q}PE+bZdV_~m)k4$k{WJtLhgco+ zNjhhc8{z7!KmWvDISP-~qav}dj}PzcX3(KaAZEUH><{}?a``D|4oe5OmQ|O}&GU2R z>MMd400l|AjdtInVzE^JED^d3%SrZ%J~0uO5p^Is*w?XhlNEL$SUUXI9P)oY6;O{% zycdBd+b9L^Amri6yo>^z_rOr<)2B~jVq)k(U@1_#sr(uVQC+nmX`}UES3ybjj=Q<| z4+Ex(*#W58Qf@?PPSG-4WHlXmJf}c1*6HR@NnWc$Berd@An*&|cQH^bs60qQEbajE zG&=wfjN^d7E0>f5)W1u$=E_h>?X6+NMcF?JL{vq3Br!f!=7%U)-b|b$wGkcouWG+H5m!#aAgZrVr&OeL52XNSB0G3BmtEieT zr%ZD;PL0He0)d0R&LS?+cM7Z^Cq+1cgV)mQTPm}+Ncu?Pa})>TSdDO$()R)1x*<$8 zI$GL?z`2MYxbT0}%DGyAtOS=;`m(Mt=hYoMlSTqSUYPP*lSIG|p&UAM&On^3&Qgy9 z@YqKDxO#M)$}-hrSEog?s5GafQK2?3R@S=5iJ|e{8Iev)>tk-T#+L|gW@&Rj5sA73 zO+h8#u#6gAAEpZAM#I&J@Rml!0D`(|j8?_r8K0u$o?-p@4WoPC_hjI%!rz&oW)NX{Xxu2A|J;Gvy z)XKW+A!o{$hzja7`Q!CqV*Hi7M7Hx{=zaz4X^T!xLvpx4)dmg5u-M8uayyfxjzQcdavdS}UFpbR|9uYA?3tQxdTfI_e>*ev<7PiF= zYW4B@;IRwM?{htM(BV}3^Euz!QO;Xg-#@qK&95K?GOs}AgYkM^9eGxGGCS>$azD21 z7$gS?@w}Q5wGw1;mi0`AMte~uqbi;>IzChiFJ-FXF)^hiHA&kD7Pm@zGCOj8zekFQ zeD=pQeorT+!OhHMG0Al1bcQ5$FN>;zub7cbVN+N`mE9?^3%Vpr7RJ#CDA(9_JvQtZ z_{0jY&Mq?yh~Z798lw^z*C*YEX1rzvA|@_G(J~WjNnt~!1`WN6OAo@WF&Ok_n8ky5 z!^@tazqRz3wL@V%yr`13aF2E};XS3)V*R}{tzoAgY}Jo}+6*&=)KNJsB3ezL9i28W zY;mOr{r3}pFzEif#2;Hwzhq-#W>({RqW1Q>@!sZ*bMDqs-{8k9!hu((94$zQ9HLh8 zeA@$SJD#J3`fhQFZaerZ_E^vth>vX5Gw6I_0ox-6_Jy`{)PbDN{xf?%Go_i;uz~Z^ zm+4&wlkL;&XXP96v&hD51QI^C+G7U4myMp>i_4dLI^GtaAEz%$xU#CEZG9IFCI#DO zrHOs6y~mg>taLTmR_JBIR^~*}1PXPVUCPGZv+lMfBz-UYa4Y)%+MNWB$T1s9F`dlY zhx8Ar#*FpDf7VhOw7b4Vc(P6@vp2^OS8}LhX+^}t&G$f4z!oRlXh$(U)G4JAQNj}0 zCkeQkqn0l8sfgs0aB^ae<-hu#vBRX_zS@JPq|IU`3R9bTL>&Qh7G$bk>Op;Hw2e;jYbeD+=v$%xvb}5?69#L4d7)$zMlC}8{4ZL7CcrRL{m6O2g z-_gIn7?<84+10OJR;k6Yl}&qx9U~*!)s21un=q>Qd(B8DG73_`A3I%w_t~nAu-uY# zWF~zf0uhYrB~+PmT=yu)oqor|Niq>pQG7uk?!LZ0B0je${r9H@FhlgdXghfAII=oh zADXPv7h2*I2_w0y^k9)Th4{+WN!nxNo z>!he+Xy<&@e z%pc7C<_pQ0kw!5+CUpVj7?DHYO=Q0S93_H%J_~h;>9}Rz<1hyV{r(i1C3Lg~>Ddq=+%jFHxDF<`f^wurYiD#lX6jEdJr7RvG%PW{xhcqc2NRFn5L zShLB`X8kY0sVi4z$Y}2Nk_7G^?<==be5j_v%P!)f*naR58-XNL_1YwabvDrm%&gb&hkE>Xdxkpji zEX1I5!O;@mACfwbXUt}AksO84wBCV)IktY!fyZz}obK;wBB|G)EOA3QLFXs^;|t$S zO^!xEk@Cva%T`u2={8L-G4ZCFuV)$H`xRT>sh>{3Skbt1?vao8jneb@gildI0 zQkK^>t7RaAEl?7!E>uo1Dz0!}P*GF+p_vdV_`NF`>~(6RFy$m1%)tCwQEHUad#9;& zL>UX_3UkO-&F=Ad3and1Sd(>4I;2W!^0p8euzQ}LE@IEH8#JhrMyHLL3BJEv@CoK0krmv1j!;g9Jr?YID6g>bz#YX)k(7QP|LnKf>s1n*($CiJlrZ zq2(9W>WE;dy!;#87Y9uKFTq`0e{J`krzcz1kTdFu1EzLDHVEL00Q9!c70yT zI8>vO&or0=s&biXa=B3T=riexTjkRwMSCCw~z`kxYYAyRmP%~ykD%<+}pE= zD`}xv*`na)*G|vOfSC+3SYA7;VO?oX+zOFr)u98`Q?BB=z5gNGC`0o(r%OM5B+0G# zOxY#pk{pbLdsits>qQ~z0>-Zs9dLDer#If`M)wmpN%J}sCmACze+FH3M}}nOT4<6J zJ7;WB*WNB9{kw8FFqlV(U8>d zYKo%RM{DHE3bvI!v*k)+Gh!wTQTfS}%$joqSntjLR@Zm^yqNMeH{y)S`lr@B3IE7a zZMHI$)Ctn24MZB%#J38}QVLfY2*nZcfXLLJwDSj9)H`iV@eq~0|_I2(>C2xJST(-K;W%cPf-jwy2E0p=d|uhcbdY3y=6XKpfQU@-BA zspBO90t&W{w{i_^)>J0_{nMpdWIX18x7TO)*KkO(pu^ndWv%fXq1chV?NFf?!P`eQG5fCyOc?(cC-oKl!GD9I{|Ssfyjd6_<$XRP*;nrmA8!Zt@m+H8WFMd=2$~DL zHQFWD-&l&wDLN5x85-UZmmb&YRYQSc=ID502(_5{$;$fRQXXyS?c2iIp@Ry=&zQ-T{mq_9uU*(s2Pc@t3r;2Ft*0VqUS(Sm12Y^3$G)FsSsEP zscTX*+kl>bK$3zABfkh3AW`8UQdPz0ary+fmI%oYkwC}(6akd*h(UKwx#|{%JKts) z%@#ldNOt{DQKhgF!2$wnidOdo#E@d)B~fAx#6Mv%M0{rd0?EOiNuxasLA3>xei)?g zR!yEP#a_Qn=lUV8DvFQ)N%}C6PfPbcU;I;$q}*qpUG{x}GtGt>Z|V%?MtMv{)#Q@e z)6GHSyVIh83^3i;f$Ubr*7o(3Ay*V7MD_1c#r9s?P|BmV@_;7q5mlOVxNu6hH#UyU zSNURQE>(`TZDwL8hdOyR?|{dR0m}_|`KuM{jV2&8Dc9%a!~)P%2xT=5&1x)RB5%53 zRtB0UTqeLcT>fLTcO13qL+eZn<=y>criBK9&VB8BCy#ao9eW=T_o$&Cc?lcx7dQ5w zmMj23u9^(FU=*@4|4%p>qWo4Apd&7We^Xd7XX^kXcVMFH`9`jqg3~F}L*_H<{Bn*- zXXpih13ocpRG64hmmWj2va$kx+lPRqvsRO-+M5b1$g+Nf2g8z(Z@&V5d45ts^POs0 zFQUuG!>ETn2}RPf*-3A{U1nj(B+A}3k%+33CbN@p@IH}BZajYD{4L@550egJz53^R zM??!Yg#d_yk!cWDu*wZmbrv8~B5Oe~3Q@H5Qav;g$9rL_ zS0lUUyixta_yo;_1=8r(@{#mJZPS0uP2VL)5vH}dlvXT(K+;<4k4P=x)__nuF|v#o zS^cxgd5dD5DA?ElT18KL;bhXhS;&rKzB^xAI!bnh!uP&!faewug;R=nDB9b~AJc9UuSU~bap-J4 za&tr}sL@>N7%}hFijWSE<^5a?h#1Zy*6J7Y|J_*BO7?Y$KTA!tM4@EA4VNH9eTlc} z&hXG7alwK^I&zs-RH1Nu%$Nx)kzfbzY3o6)t#5?ta|0t;2G4vdZnpg)ADw{9(@S1h3NU}Fd*x@CMg53 zYgQ2!7S0s#ZgB28BYl5>dw-dDr?001^S`ItlZB?ueHY#$aA5*^+EN-BU2-$K5N#r1 z*;N&lY)#{G@Q&IE;HUe)SLHv|K(Nc&AC8d>U!OIlOSDr8n`q-9Bq^Xib<*+XEy!0~ z3U}I(Mchy7R_j;Ecc}qWL#kN8C+ZJsSOx?(`?7I~E7@ga9Sla5=-lCB2GEdRE(-_qu4~` z$8E%+CE!^Lv!s8Ys9!*#6IGHmVTuLsU3)Tn2gLI6e5u>VUu5u)UK>$?>SB}jKKUg7=^L?-?;#|7{rz$Ea@8An)Cd1EG~wED^!n-)D!J= zIL~3XhlSCRe3QN5n3^qa3^(8|h4o@zt-` zj2W-aT~MIJGQBuj6=iw!HM>I+A9*=*BWD^c9SZ7kD6t`@FInNk26jE)1C_u+Azr?( ztJF-LbB+~kpzw9l=A-xJoARy9JTh!x!+W_*da>p5tT3!?SI)R)x|=*39`f=)w(8_Q zzs+R7na4g@l?0X*;8=if+wge-b53Rpd%qbc-+g2j3sJN7Bh6zzXM*{yY031iT&vsK zs2?cH+p+26_bbZjcT>N}mgD-#>#EoT4daTzPwdqw8OA5M^L{zs`mi0jY+cpnCOTrl z5VGdsK$x-h`f^!CIuFb6piHOiclrv~q2`d$)M2>l5-9w9rheNcXA6&O52nA$8#cfH zsf3u})#ZvW9jvES;#0oOw`BJJG&L&kI@5_Ho>KevG?OX(A6m?|kb`4!yr`O9T#szW z28UnA)iDj8%n|HtectX??CV2Gyh=v`wKo_QV02wWfe7)VW3DWAFL*CEw*vQWSf-!@ zh4+DK>=NCDFT)YTxusa*n$s4CiU1=yL<&DcSrQg>byEsZh<6FR-5GR1zM|s2d()Y& z#r5V?uqMLKxUDFBqM)`>7;^re9R?bV(a@qiqmyncxVm+x7S~yzq$kwwC9!OBvtJ42RR5+rb}PpNkk_qM#s&Xx4r`pDp&^0mAQ2faz%&wZKq6>R3WY|Oj#f7d*>0j8 zwaC(j_R=JXVr84T&sI1f5zCG#CuCzE??l7TK3@h@cXjL2X-aB1HKpYSMbp z`+ca=!@d*=o&;X}#1V45#>VWlylc;Ci|g^0(mcRT;cDRha&1xm4`un3L&jJLDz`ym zC*?Uk4-ZdJNQjpZm%M|tj7(W&rP=9XbsGifXN3#tBSQS|(dyAL8Y+4lgYqp~{im-I zp?E_VDgj8HW_0;3p2!hKCT+ItRC>f{Pb^qA3SayG7=&-gJ9c?>-|PXR{BNOUU{_dZ zC4Qhnvy?^Oul-?cVCkHLINZ=+|INUUx#F4Q785aY@VKbH5s< ztNMt)_}!N4Unb_f6v_-&R8%B?IO*3qoYmd+A7s6@QXfA3fBW_S>C^ukbN)}S>Ei1^ zx0Di)Pc3F|_0r7?7h!a+!t)qTxm}~H3(_>DmX12r1>;rSoB%^-9_I3T_3NfEPQq~A zb58`zrAo00=h+&%pE_91M3e04!7Xu3l_GKhp`0o ztLCiML2(E~5v;OEJDAN!0Qapv5EI+87dfZzcpFjT*|S@{)sefl=1K!ENx`Q9Ghi;1 z?l}A8WQ)rf4GGGPg=+;(TbxCvKe%4w?ilkqfLSl+RC2M9Vs{sNbCo}^MglB@e0OL; z&30f%|JyR$>COxY?7HrE&7z`KgY0?foS0zqO(WDvHa#3DVln<}u5s;7f=ql0mt4f` z!Ja#idPib#4(*bZoXlcwdor-2&6c{T!6*K3?Nv~Q zgF0sz6ZI2F5P}jq7Yldg(d{JiLL@tEbuiV_lhV0k*xPSc-0#lq)$vmi{I$a;bv`&i zQK3l--th?~i!UFe_9rTv4AWR7$Iv*cOGGj+0Z)u7up0UwX7NAR#eZA+e@ypbD-0kM z-Yc|uKTl1o=G4C$^wbg4+Xu1!F9j+whpNqI>(k`~(65*L>H9Q-f*_%?_m-Sl53~|$ z>5Ls4&J2~f!+5*pwxTg8!p`#K)bG#v4Us7ZRLeHKM8y7U@0}<@l*1{KUfFE!Syz~{ z6)B_{2}@lV(qSVmdd@(X$Pyi86XbC_8*0vsioRHMCk^S5PBnYuJ&Kg&RW2RBLYA1! zZNvy?PJ_Ba{SBdu7B&q%lO8j^slAmd!t9taGjaxpmIH`1U3FH@jA+czdxMyDm$M<_ zmhVg_K5JlhRe^o~UR^u~{>_mCMzvJ~*aN)kzvoN>oEkrnV$tET2M zxF4J$5kG~ahL*nhR3iN|f7$$L6ESWkI&Niv(86Y@y=_)Q*BFn2td^Ne*z=b%*2#V0 zHvI920iUp8ep=>S-ywv#54{b%1p(x3?!t-VUU6M%Y+Z@O=E5J;b)RcF!IyucBtHLy zhxUU^>^6^#TP`LaDSx7D?&Tc+yS(gbtU|-|JDf3DEgqIB)H8?0P15(LKK>$f82%&# zK}`fm2EBH|AbeoU1VPCXZ>4#2O# zKuwSd>ryiM=^s8$db%(4psi^1F5xH2C1u69m>%rxy|c8_g?&RyVQJ=Md3aQ$;y-p< zcL4^ICyq^8l}hHv){mL0(+zkDo5DCg$pCYy9si_cT>g3w*GZsf6H@8LvX zC{F#-YYib7n)Zr6wDiuGhB_i#JyJjPClbOcQJ@jK_xocN9Y`R#uO0L~iV{iQz;#|E zDk9zocH2St^7tE8pIBMBp9Vf zJhXIN_6IFhBButyc=QjfqPg7pc?UADUyL1CU%B6XTBy)`eE382>$RTuT6H|b6|C%X zF;^5IGr(hhc@`y05#*qGa>IXr6G)U8!)6zKs6dc^HuLTqz8%`mVm}503oG3h zrst}$d~asIxb?nsqZ=mh3c^O}oxa=P*I-8v~)2W0jUr)TF?I30*<4mp<{DGepg~ zWml$?3}f%#IZ6HE0CSkg#DqoXQ)I;vAOoM2ZtL&F0ahv9%m}LSObS~^j1?pxVDP)P z?D3NTK;_kw>N*j}`N_yv^Lk0yX}&hs&*Ab$IANda@&Kqc&!{IUVWkzxI$vz|m)4f$ zLY;d^R%U0+HBvidH&FY#v~&>=C)0oYGn+9sIK@d?2G@Ppux!ZW_zk8BoH0h~M`Rv9(RnpNRCC+4yIZXFkl$M=@K-Q=Ff zx}!fJJnjYk0{d9SE9Lu&L*Hy3+gjz3<8xP`YtOZOR-?4uXy!OuZ9+=lf72KdDygS7HoYSJ zC}+5+g+uOH&HL84(cMww9xb|U z+SR>7T+@<~@!pWp9&X8v=iDwH{=ReNK)f>6SoOSxWln#`rNGkce_1~z|g znN(`^uFq@~z?QyVWR2?A{gj%L@OkzVoql;le&{o~Xl*w~`ktOM+#&Z0bAx2|9?{1z zY+(i1XibL9G?XcjZ|SOU%I=wrWH|UPHEr#2Y$A<+DGR*9Q4$d!n{&cplZ#LYX z+%Zj`?Lghdx7SDpp=Zr66C-lDWUc)6b|I>?d;PSX(LO(U-!$yMx&Wt})AFE~;|95+ zD@erbuW%QKo^Ngf)*+{q*|_;NALy?;Sd0c++e}CSam$oJxC)b`Vvg|)ghlLM@v!&r<{@NH@Bv9wEE|xX44mL0H zd4-xfk^9>5jxpue*tK4BVK7{Z%l$KLmYgpfB@WhSXIK;SmRehAfyHV^ik1EcIk*_R zh261{oHBbN)1}G%@T9=$%zApQCu;4S(9SaZf1#$LQ|<=~|3^Ur z^H~VBDfzpX5s3@tiK)o7tn|Rod&s!vzN|v}O=DDAkpJe3S?+PgfoEQwU8XVGj0!f# zjb)7u%%3!YpJD$LXD3UB964xvEXnOh_>0BG(Mf<91SG<gSgf4StA)uO~yRY}&K zcmU^t6D;3V!FeQR2OJ|bXE3K4?9ruR4kBQ=H;lS?Y(*q{Y>pq>L@p@;7*b1Jm6?gH zfQkL-_)%vwE#E>38VJOw&kvaXQzRRCm4shk+$tp%lP^H;>jn8ARadcFQr_?`f_^y5 zb~dXZNkHagq1x|>XxN&!5$Slrz8i-yW}04Y)UFxzx&dp`!g@buw#^m^Qw3YqH>e&P zV23Km1+S{Alr!EP9{H=;6|X73uJ4NuOk|j%>MRZ4-^S8F`fOBHCDD@Vk|pV88&8|G z1x2B}E%G#GZyN6it(A1^iviB1+TX-^Ui1D+dMmCJVAHSS3~BqKDrQRZ1Tdl-8`Q?1 z_t0m(k_=~N5efKVoD41eb6HNRH5H*gj+6Ar<4@RajCFb`Oimm?i)Wb{N->wn3lWl2 zTWho&+!h6=j;#An*8WqexD)V!-Ca2HoMnKV0?H>uH@k*`ar{)u&=o-n^i~$eS1jg$_z6P z$p12O|Ihb|1C>}Pe9kLjrz1nb;PM9vaXz@^lS1mI#>1Z0-RPcbW}vRyV6zu-9kj28^>SPBdc?OfDOZ=0MXq7?u?jgD9|(6!(B*;v$x|M`s`!F%i( z0d;WwMx};YQTN%r3_LzpDTlN858>8bXhW9z<;5&m`prfF-kd9Q{w4%YcMHklf@BJ>s-h=+f z5^m$j)=q1N0j8)k(E%+DV0&Ojm zt%dbikj?IB%s1kzulBPViypnhmyPBaU(A1kTk+9ruIJ z8F{JoO7^rZQ%S_3^#-ybpRi{=)s)Xi#9=wD4%mta-@H}fkd(9O47eBep>n zYN!`)_Im-}VEiM>=EZBy53PxtS5y&@exk`Ms`^0k8S2J~+yykl8Bkv*O2*%=3eQ)L z{W|8zoJ^C_RZD$Ak=yU9=Hb7dzy5=NODE`Gju>?<6=SJl`O~c1r}4^j3;`9lDa_86 zlsAG~2O`%1_2lKOZ-18jGzz6twK;@lrr~Ndj_8ZNPtJnTudhEooHC2ort>;v*cvFg z?B~D7c}awvnqQFK1sMpLdnRL%UsO;`mr1+_B4)Kcj?T=PkAa>SX%3Y1!+Dpl2#ngO zGE_kYAre!kdVz$4>M55kDr~&>hS`Ly2}|C?gjr@ThD;hgbq?6ByI&BG=P4|nB<7>9 zf+KJ}zFK|aSx{u0AIfb~%OPTCOAMum1|^p(iZ4=WFIUhzD^;A28fXl!^yF<&C1n>W5l zw5i-rE;*^pLqef48b-njrMM1Nkgs8D*b(^h6bExEV7a$Qs`q927N=Iy>l|5Cl>GN! zYP1a=`|F`0w4<7F%FonpR8$o?4h|1iFLd%;M;apV!4%_|2K{s0;I?r{so z|G^pGufV+-3;@1*f}=3t@XRhaJ`BF_|L=0M;zlLy;czk?c+C+>>PX*x$Gh*-{e=QJ z_4H_^kqNwd<;ToNDWC$2^!~k()Ut|-zC9<$t!|hbFM*HLB;Ti-rgJCz!@isJVkL0Q z2Mhz74zj%u7pihjX+EAS%GDJiMnLl5cIn)`;U{nfr(3*THDI1Le89j%29 ze}5fD^?ScQ(5M!8v`ZU@r({?u*K&{*8%LRDaKn%DN*<9kIP6NkhCMnY?1ek5KeA8QeJ} zm+Gx?g`Srt9)=YBx@$~F99q_T2L=*TQwKsx{RT(V*qR)+AZci5_#ZX{UtSJ`4%|DQ zb*om!+iS|jCq`Fl!W&2T0HXK;bx}~_9K^qe#w#_DWFlVh1bCyM;G~O4g3-589l)48 zKR+L^*y7G4^m?SAon?18nTJfwo0OD<1rU6DFedRnWl3Ss?gytrG<}%I^W*{d7UBo} z2~ADY)FT{5Kp@bH3(y>=X=2J?lH2ZQgloF89WFzcOECFJhm1VEQ>SiJ?gsUStgz8@ zk{Gz6X+V)ib4272P%w%RP|KY4@Bo-ZGd~ZZ!aK~GkM{MZ-`5mZIq^Y2{?~I3i#Q(e8Jx%1mi)~dkx3zpHgyRkFW!#3$5+&C@J+65Z+Y0J(wJHcgpn^Rc} z>H!u5g9tD#O>1jwW4`0*jQMwTIh2h)7)n!N>pQzXpJ(mG7fvq(@hCIjsq!eAr~#J% zwFU5S?mgRCtTyJqTQvSK-swh1$6O;ebp&Lsw)#wbEuz9ZVo{dKa^p_KV}d{8mAqD0^U6E{f(qrCOF8t8xkakJD(amuk1N z$EcjjX$gGfbm6SZHs{Jceq;Y<)sbM|TW#BXt4ZWzv9rb!tr)>%7Bz4*FP--_tJ#*X zsIAuHC#U(i(OH&q1vZz`$0vrze9K&83nR?Z&$lJ1TJw*Rk@cY{;E>^OVB6zZ{mB71 z+w|tNfDEZlD9hSA3&og?{esr7R$sf`AcoVtD`R;eRqK4gz1aKiWHCyaq5svg3w_K$ zF(c~PLU>J3>qV*jWu;oK*4G;gCYYL183kW6NJm4Y9 z&{p$VJ8&HtIc~W?au3Q!nLBIFq_!PHQO4grDMx!PEEkY_JZz@4sR|ZC@eL)bf>9 zTF&R}y8P$}4qjoahG6J@w{%)(9Qyj0I0vlnctvRrOiy*xKAL5e69?w7e1gKl=l zH`@J^_=wacj+k_86-qvYk;z~JQ`iZfHVEDQ_s&2p6th8R0B4D1`9a0{gx?(-AR;o- zyN~m}*?OI5=~82#B$v{G=;Z#CjG^>0)dyjOoT_>)BMq9_&lP9Kd$74hCmWf@;l;{n zns=H(+n+#9a`BHqYj$n3RLtRM6uFI|aP6P+M7koyV@;&W`?D(Vb0c^Iefbcg?)gOnG7C%-;%DToiiF0g*ZcExgnbwdW|>7-UTC-Z$CT^=ZT)n zlC4W?#IH0KW9pR@ETzBv!7nW3_)|8?bR)zJm2|ZS=hrvPA+kpOVP@*}O~cec8@Jcx zO^V&6l)5II;BYe%|3-rM%km*9!g*%x>gYM!`lM42S!c9O)anC&RFF|9rvDJ>w7$FKxGlFHmO_&2!+!; zZV#Sn$Cb2CSB%+&I5!}oxml1aG_C8&q(ydaiJqymC35Xug;`wb zgSe$#N|pms*M%Pf&Y_rD?t=5bP2mRnjdAcYAkB6k9`FQgJX@-?Zke9L*yeRh`+Rq{ z^LUVRu-z9~SX_Lyo2YP?ZhPn0vZiHj{`7QG<+=G2uCVU|c;!nzg3r_V+!_5JNA#Ef zGeN%Wb9HQGd!HYDIsxOOk0t5tsB&}@{{d{hwmaYj3p-iv>rEAnO6#`Zu?0pXLtuM> z{r>yL`YRll@Bh)ubwxGVbZd&h4+#h&5I&>`2#PcT=|waGQU#PAq)Q12y@jqIHHdUW zQE8%p)P&vw#E2LHL3(eYhJc15_{YzSb9dIcIyZaG>{;*3nwfX)+0UN+%v|uLs80?6 zZYL!z!w=)U1(}U=hkh9mmghXEd8hq$n?8e2F*^7#aX+tu=LO>s<1c}V@0AiE?5yvt zlUOHcF)7MZ%#Y-j+-_)vp?BpL?8IB~%u;ua^I2Mi-2PEfvVBqe^BHu1fL)Ciy1waK zt|l7MS+sj{GW30Qg|K#Vs(*2oN)!VBmEZ-V|Ec_6RjYb0tiIF!GdHkn?82f4< zw$G{ja`=)2kvv&r1)Sc##?LD(Ec}KPRPmn}eE>I#Gfk#zU`AZ8u5#o#*XO%jc6Th=G)dlz919v z9327?omVp8)%mr||BVp}4d&4l+kqSu`Fs& zqo+G8TJ4ni8M%|S1O2xoZmz%L;oxY_l4@)G)SiR0L69tI66u>PU<)AzoC`0r8WaNL z?MSjx?P?Wr^mw5ivMO5`J#-yXVB0?LX!Ay`f^MDcq*fT8MH^=0byZBsyJc@4d=9`w z>Ii3vKB&+{7QOtO_RO7mtTtkiNI#1WPC?oztlp?-WzA`QbBQ?8!&7HIzrrnTB=4ID-7hwSneh!BqZ1|J$dp((iRQX8Q9Q-Q^*)ZGR`B?TY7`*%wL$Z*L#4+(khRfYmM4iOTWZ-)#omO3QHY^AD zBs(T*Mje&x{Kd0?noO5gT`e70n2^vj#XyLX?Kg1}NlATl9HxkJB_OVy5l=6oB$MC% zcIwb{OeZ+VHL(JLpWQ=~`+7b^oq7f4CwycLFfc;FP8?EBA~ip!MFqP0w2p^x+b5)& zg+X&W5nA#l?@We?fez!4bCY+TVlPk9OK-)~!!5~TP)%(~?g5R-_HkD67*g-PRX&(S zSd%IKx}Fn~n)u|5B?TCt*njlG`6zNC`x5$upQ@pJr=*nsxm{9i%itK!MjuQH3m4#^ z%VNyxs7};Gehut0D0RdJ3PnbIGP=~|`rtysI#1r8sj15q4#uHfahj{*MeLK(!J2@< zTGMR)liYrad{To{n2z_b!EO+ zfqYpzG_R9K9!T8&y4mX}FAHU}>o688z9k)gG`{KUqyz-oUTI_!ZuT*^N*VPW)X)dq za4steSZr?0blP`05qF3CEXqpeRGZ|t8$bCp$vDl%7w<3QE5x^J;KbU%ql_8v4|+J`eVVuqO+e-ccw>PO*3EMA3HW6cF<66qpPbcMR$h!M+U36 zr9So_DK6C_#G&!~lhRqGB{UuOENklzG?5-p? z4l0EWJF<0M$>dl9Z}rsmo!>2~QqotLG{Np zacWE8dX5Xc4|Iyb2&E?kqdV@3joJ5C;KkyqvZu#mxbe9WlZI{P&)PhS!Ge4?i1job z;_d|D)1A==$HKRgz;qTz{*7#4ga;%7glWwKJy)LZ*-`1s;6DWypB^-f)rLuE8_Uc< zbesEPT^CJ{{1{HA(D(bnbK~uzN|+%&exb>^J5&AUAzP!(4(hK%urTC-E^)$4=W!Lk zCB?=DQ4B8DXz-r9RdLj__LW#`8sUDkHSK^iRfp(3b*pF~2ID2XP|9Mx4KG%jBz(Ck z54s9aGT#I^&NQVzx#yU;IY?<~!s{w`m^>i|jhQ1@to zsJ_q0^ZWXWn4j#aJLP4hjqTs0XIl9iYj_+$rtQ^SuCVZaSDX6UHW|QCwvPz4Rvj3W zl#+#zkEw=4i>>^y(|4rd@=kfJX%K74p+Rz9XNSjHZ(gm9!M(t{3AL-kG(4Lkv01ER z?<=h>jIW)567EQh>3+6LQQ_^Bz5SpuL*!xHMQm@v;9c5}(0;=t>%r?U0WuA;gU73C zgFIORPZk^5(@f%?JUkPrlv{g8g!&AbHO0-G{mA4(`8Srv-=p2*ym1wgQU~C}{$eiW zs$~1x+8JN*nPYFEMr|U5`bv^WL@&$rw@pog0~ThEvj&eO8T!my6)qb~7WTBfjwQ+) zrgZ2fElTM1ic`MmLv)!|o#dNe%kSUahFn1xrE(_IR>;Ooa*z8xMZO#coLc?_aq%>o z+SDcugLC!hB-~EKZ@XmUa5pch_??T!K0BX*cRBot=^RAzt5M-M?xF5F7`$41b{1(L zbs9+1@uLb(Wm+nbgEUS<7W2{Do&U7E`OqJFn$B`jFEp#eIlVN4w`V@N)&FvaX1;L7 zLfh}H^=6GW*4A&izT1Y;ZC@5nXWt%#T^ikfumxMGz<*8GG(ZU5vXnGdA4Yy(5kb4j zn`Fm?o^qoz_5)j9Dr%zh-u;Z&j+28R2`gfof6z!_a=H`s_n{w@Yk@y0N-|I5!OUon6!s zGVsn!_5)=}#;bfxWg@uXFke9R`me+HWdKPFfe*GO>ht}aK#t@%56aPh3iVAQouEIz zKZovp{aT1(G1jr~-y{#KBxlf-ml+Lsj?dH=)n)5T&^K4CKeYYzAg*1RZ!)oWskh~& zZ!^WrYHe+AF_DzFQBvBRtS4#sxIU+>+^Hz_j9d;10iW?RE{~BiowYQ}(fO5Ue^k$WW@cs-RyiHp;T_|0T)XxW>=00)JFCVEd1grl&W;*^=X;XjmQ3pbTBtC1r0uNJ+ORAS)7W)Rt44AWzIwdzjcV*QZh3ggoUxpC z;j3^?wT5x392|Mg-QC*MNS0!;>sr8Mz~k_gwb|2UQ?!S9IrFTc+g^K-;{bSl@=QDa zH|QnA=LvvEu>n|e_+HEIDJEc{a*Ev)#L1Bt1;crar~u$vky_aO+94FWU40(F5Y2oh z&ahT)EruE-pWj73|CBo+$D?#CRY`SBbhJF=;CHB}Y?YheWB_@N1zyyRL~&2owb@y8 zS+dAzoZrb2Of%m%R?S(J9{FYO3F|?9RIf)+U{rviLcKp&ng z-WU^q?pfH_jH*Dh(r(f`BT3hQd|1DzekPS(P(KM?ZKVbv>w>mz0-q*K*99~Zjf}Fa z^C_!)<$a;KM)hgt)()o{q0q)U8vgaLDZ~qh;v!3?A9n&ofQ+YyPd4nR zp6>8=NF%YWm0)YHIIzdXa8au5`E`uV{?TE0_J@NqP*Hc*xw*sq#G*)*A_mTZGxCz} z+4A-}%%K5z68>e?^2pwJwU?KLK@;|`lY zdo$%b88DmL_HZ^M_?{1{!6hbf1MvY;UF=RPzQxc0Vvv;0TNe~4Zwtq;l_lXL`e=gZb2m2*Yo2%$6v$>F3Bc#!{yaYjf-6|-pMGM; z7gEnGX1{P5`ApSseF{{-D+TWvo=Ug)7vQF3ZhH0_gTXMBeb{o9|J8v<`Fi`5v0oJ^ zk{cdkQFD40E+C<5vV>U6+t~?tpX9f&!-MxNj8wvY1sMiw_e?h>li`)GTyFS8sdRQ8 z3O$aGS%8IoQU4fkqyxM7ei^0Svcr#V-(wrq3So~fjn8VO<+i<%Exnvl8%tQDKe{sA z8SoSnuM-WzA*pvuTR<7uDFKkaSEc<<@LKtCy0)tQRAQ7Uy|YNlY#`Ecey7#4ehS6d=cad-91i_0J#3$gq zm*|d9cPa`Ixgz(mELC&QPAJ7 z0EUWj-ZbDDhRe*0Q)K4JGFIz+0&8BKdJ9R0j2PQnc+X1)a|;eWe#=!TOC)Q()6A24 z;6=vwoh_Mn2i}c;YfAM#dpyw;#&EvMigCzteDsE4UlAh2ZKSx;9t{#Z7U%SK)g>vM zkKDCJ!+zAj9F-8UrgFfc_QyPMX?q-n4>P>3sLcP1r$t84jE}hbElJLft` zG(k)rby`yXz?$?U5BqRT1r-H-+^w^9TK+eb;AZk~NMSkXJRHC+IZu7mVMBx3Z92gn z3Qb`Ea8Hkuf^hu7q#<3w3JewOfHjL<wcYXT76uv*tiQc