网关SDK相关
<p>[TOC]</p>
<h1><center>Z-SDK常见使用问题说明</center></h1>
<h2>1、Z-SDK和常规认知的SDK区别</h2>
<p>常规认知的SDK指的是一个软件开发工具包：
<strong>是一些被软件工程师用于为特定的软件包、软件框架、硬件平台、操作系统等创建应用软件的开发工具的集合，可以实现南向和北向的业务逻辑实现。</strong>
但目前我司提供Z-SDK，仅向下实现南向设备对接，北向对接由客户自行实现软件开发。</p>
<h2>2、Z-SDK部署步骤【基于我司提供RexGatewaySDKDemo】</h2>
<ol>
<li>将RexGatewaySDKDemoApp 同步到/usr目录，并授权可执行；</li>
<li>将librexgatewaysdk.so文件同步到/usr/lib目录；</li>
<li>将RexGatewaySDKDemoApp.Profile配置文件同步到/usr目录。
<strong>注意事项：</strong>
配置文件必须放置在此目录下，否则无法读取到，不用部署其它依赖库文件。</li>
</ol>
<h2>3、Z-SDK初始化说明</h2>
<p>Z-SDK初始化，一般在设备上电时执行或网关应用层人为调用触发。一般在设置执行初始化后之前配置的相应参数会失效并以最新的配置参数执行，生效。</p>
<p>备注：Z-SDK部分功能需要在配置后重新初始化后才生效。</p>
<h2>4、关于网关时间同步问题处理说明</h2>
<p>时间同步涉及两个层面：linux和ZC时间同步：
<strong>a. Linux时间同步：</strong>
网关上电后linux系统驱动会主动和服务端同步下，目前采用的是ntp-timeserver的时间：
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=58a58a1edaa39ecb3d37d7ed5b56230c&amp;file=file.png" alt="" />
<strong>注意事项：</strong>
-需要使用我司默认系统固件，若只是使用我司硬件进行二次开发，客户可以自行设定；
-可以通过date命令来设置linux系统时间：此环境一般可以在局域网环境下操作，如下图：
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=e5bb753a43a95083ac4f85bc19c895af&amp;file=file.png" alt="" />
<strong>b. ZC时间同步：</strong>
目前ZC（ZigBee Coordinator）的时间同步是在Z-SDK启动后，由ZC主动发生时间同步，通过0x03EA时间同步索引实现（Sub=09：时间戳方式），Z-SDK实际日志示意如下:
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=4576871c270519718c6a30fdfb506e86&amp;file=file.png" alt="" />
ZC发起时间同步请求：
Z-SDK完成和linux时间交互并同步到ZC端：od date为当前时间戳，小端模式。
<strong>备注说明：</strong>
针对上述描述，导入一个时间戳的概念：
时间戳：
Unix 时间戳是从1970年1月1日（UTC/GMT的午夜）开始所经过的秒数，不考虑闰秒。
但目前ZC这边采用的时间为相对时间戳：通信协议中的时间均采用相对时间戳，即为相对于2000 年 1 月 1 日 0 时 0 分 0 秒到现在的秒数，和Unix就存在一个30年（946656000s）的时间戳差值的问题。
因此在时间戳处理是遵循如下计算方式：
当前时间戳-相对时间戳=ZC实际时间戳
当前时间戳：1668670200【2022-11-17 15:30:00】
相对时间戳：946656000 【2000-01-01 00:00:00】
ZC实际时间戳：1668670200-946656000=722014200【将时间戳换算为16进制数据】
ZC实际时间戳=722014200（10进制）=2D090FF8（16进制）
将转换的16进制数据按照小端模式（低字节在前）排列：0xF80F092D，在下发到ZC端即可。
<strong>注意：</strong>
关于时间同步在网关正常连接以太网的的时间，客户无需关注相关问题；上述流程可能在局域网环境使用时，终端设备有需要维护时间参数时使用。</p>
<h2>5、初始化时ZigBee模组通信状态判断问题</h2>
<p>a. 首先需要明确Z-SDK其实就是一个软件工具，当主控MCU和ZigBee串口存在数据通信的时候，Z-SDK负责将ZC串口接受到的数据转成Z-SDK约定的数据格式通过API函数调用的方式给到网关应用层；
b. 在Z-SDK初始化的时候会去配置一些串口设置，读取参数，但当主控MCU串口被占用，配置错误的情况下，Z-SDK无法判断具体的异常问题（存在的可能太多，无法兼容）；
c.Z-SDK面向的客户群体较广，每个客户硬件设计串口处理，判断的逻辑都存在差异；
d. 功能定义：Z-SDK只是一个集成软件工具，目前除了本身的功能（数量处理），目前研发不建议把太多的外设功能判断放到Z-SDK上面，存在太多的不确定性。</p>
<h2>6、关于Z-SDK下发函数说明</h2>
<p>关于自定义数据下发函数和透传数据下发函数区别：
自定义数据下发函数（rex_send_self_defining_data）：
自定义数据定义通信协议端是基于我司自行的OD数据（0x0FA0），目前这个接口目前常用的场景是智能锁具产品。
透传数据下发函数（rex_send_forward_data）:
此功能是兼容部分特殊设备，如红外转发，非标准属性设备时使用；另外在使用这个接口是需要将数据处理模式设置为REX_DPM_ALL（基础+透传模式）方可正常使用。</p>
<p><strong>备注：数据处理模式通过数据处理模组函数实现设置：rex_set_mode。</strong></p>
<h2>7、Z-SDK数据处理模式说明</h2>
<p>数据模式是针对Z-SDK增加透传数据处理后，针对透传数据处理增加了下发及上报的函数处理，Z-SDK在使用透传数据处理时，需要设置相应的数据处理模式，因此增加了数据处理模式设置接口。</p>
<p><strong>备注说明：</strong></p>
<ol>
<li>透传数据处理是【2020-02-14 V1.2.9】版本的Z-SDK支持的功能，若低于这个版本的客户在后续更新了新的Z-SDK可能存在初始化时出现：
a. 上报透传数据回调异常；
b. 下发透传数据处理异常。
让客户将数据处理模式设置为REX_DPM_ALL（基础+透传模式）即可解决【需要更新头文件】；</li>
<li>可以在《RexGatewaySDK开发技术说明_扩展功能.pdf》查询。</li>
</ol>
<h2>8、类型参数【command_type，state_type，event_type】更新后差异化问题说明</h2>
<p>可以《RexGatewaySDK重要参数说明.pdf》文档查询。</p>
<ol>
<li>客户在更新Z-SDK后可能会出现同一个设备类型在数据处理的时候出现类型参数差异化，这个是因为在Z-SDK使用过程存在优化增加处理接口或为满足定制化需求，专门为特定客户定制的功能；这样导致出现较大Z-SDK版本更新是，出现一些新的类型参数；</li>
<li>可以明确的是：新增加的类型参数不影响设备的正常使用，即不会对已接入的设备功能实现有影响，若需要使用这些新增的类型参数，我司可以提供相应的文档说明，若不需要可以忽略。
<strong>备注说明：</strong>
正常情况下我司调整相关Z-SDK功能不会主动同步给已对接的客户，若客户要求我司重新提供Z-SDK库是我们会提新的通用文件。</li>
</ol>
<h2>9、配置属性函数使用说明</h2>
<p>配置属性函数是一个可选函数，在初始化的时候不一定必须调用：
出现调用此函数接口的情况：
Z-SDK没有包括网关应用程序需要的某些属性，而这些属性在设备端又是支持的且网关端又需要处理，则要调用此函数对这些属性进行配置，配置成功后Z-SDK即可按照配置的属性参数进行数据解析，网关应用程序即可对这些属性进行读写操作。</p>
<p><strong>备注说明：</strong>
配置属性函数调用后为一次性有效，即配置属性后再次初始化Z-SDK，已配置的属性参数会失效。所以每次初始化时都需要调用配置属性函数，重新完成属性参数配置</p>
<h2>10、设备入网回调设备类型处理机制说明</h2>
<p>Z-SDK在ZigBee设备入网时会根据设备入网是上报的数据对接设备的类型做简单的处理并在映射设备type：如0x1101表示一路普通照明设备，0x1109表示色温灯具等等。
针对Z-SDK识别的设备type不建议作为这个设备在服务端的type识别：
因为ZigBee协议栈在定义产品类型的时候也比较宽泛（0x0101~0x0104都可以表示灯控，开关类设备），这样导致Z-SDK根据设备入网获取的信息进行判断时，就会出现设备type识别不准的情况。一般建议服务端处理是可以选择“设备type+Model ID”的方式作为适配参数。</p>
<h2>11、设备入网回调触发问题【重点】</h2>
<p>Z-SDK入网回调是终端设备加入ZigBee网络后触发join_callback，再由网关应用层向服务端触发注册的必要条件：即若ZigBee终端设备加入ZigBee网络后，Z-SDK层次无法触发join_callback，就会导致设备无法向服务端注册。
此处又引出一个概念：<strong>Z-SDK关于join_callback触发条件。</strong>
目前我司Z-SDK很多数据处理是依赖于我司自己的一套智能家居通信协议（即OD数据），Z-SDK-join_callback的触发是依据0x0000（OD数据：全索引），若ZigBee设备入网无法映射出0x0000数据，就无法触发join_callback。
<strong>无法映射0x0000（OD数据：全索引）的原因：我司ZC默认协议栈处理参数和设备端默认参数处理存在差异：主要涉及Device ID，Zone_Type（传感器品类）。</strong>
针对出现join_callback出现异常问题，目前常规采用如下两种方式兼容：</p>
<ol>
<li>ZC调整兼容：此情况一般出现在兼容其他ZigBee方案设备。
备注说明：不建议，但针对一些已量产客户且无法推动终端设备供应商调整的客户需要配合【根据商务沟通信息为准】。</li>
<li>终端设备调整：需要终端设备供应商配合。
初上述情况外，当出现新品类设备时，我司ZC也会出现调整兼容如：毛巾架，浴霸设备，CW&CCT色温灯控设备（兼容Hue）,此时需要和客户明确在对接这类产品时需要升级ZC版本。
<strong>注意事项：
有和研发讨论Z-SDK一些必要函数触发条件，通过调整ZigBee数据触发条件兼容，但研发考虑Z-SDK底层适配的工作量较大，短时间无法完成优化。另外关于Wireless-SDK占用研发较多时间，Z-SDK优化需求暂时排不上。</strong></li>
</ol>
<h2>12、关于ZC指示灯控制（0x01F7）功能说明</h2>
<p>ZC有单独的网络指示灯表示当前ZC的网络状态，可以通过Z-SDK提供的接口实现ZC网络指示灯的控制。此接口在使用是ZigBee模组关于LED配置的GPIO口需要有配置，或直接基于我司RG4100_V6硬件开发。
<strong>备注说明：
目前我司86式网关RG4520&RG4510因为硬件设计关系，无ZIgBee状态指示灯硬件输出，若想实现，需要通过应用层实现。</strong></p>
<h2>13、网关按键事件（0x03A0）功能说明</h2>
<p>如我司提供技术文档说明：此功能目前仅适用于我司RG系列网关硬件，若仅基于我司ZigBee模组设计（使用ZC固件）且需要使用到此功能，需要在硬件设计的时候预留相关功能。
<strong>备注说明：
目前我司86式网关RG4520&RG4510因为硬件设计关系，硬件端无法实现网关按键事件功能，但系统端开放了硬件资源，可以直接通过应用层调用底层驱动实现类似功能。</strong></p>
<h2>14、标准场景和非标场景功能区别</h2>
<h3>标准场景功能</h3>
<p>设备端基于ZCL标准属性实现，需要预先设置分组，设置场景（Add Scene）,再通过场景执行（Recall Scene）实现场景再现的功能。Z-SDK通过管理场景（0x0121）添加场景命令（0x012F）实现标准场景功能设置，在通过场景触发事件（0x0305）执行场景，
备注说明：添加场景命令（0x012F）可以参《RexGatewaySDK开发技术说明&西门子定制》文档。
优势：标准场景可以在脱离网关和服务端的情况下使用，但需要预先完成标准场景配置；另外标准场景通过一条命令可以控制多个设备且设备品类可以不一样。
不足：标准场景实现有分组和场景的概念，在实现场景功能是需要先完成场景设置功能（标准场景的参数是存在设备端的）；另外针对一些设备（如窗帘电机：开、关、停实现）标准场景不支持的功能，就需要特定处理。</p>
<h3>非标准场景功能：</h3>
<p>设备端通过自定义属性实现：我司通过KeyFob Indicate (0xFE05)实现，设备触发上报的KeyFobValue值（正常情况下："KeyValue"="1-6" ），Z-SDK端通过非标准辅控开关按键事件(0x03A1)实现功能。
优势：使用时更为灵活，无线在设备端进行配置；
不足：非标准场景实现依赖于服务端规则（局域网规则）处理，在脱离网关后无法独立运行；控制时需要多条命令，如控制10个回路（3键主控开关有3个回路）就要发10条命令；场景执行延时较大，延时涉及网络延迟（服务端到网关）以及ZigBee层数数据延时（数据处理延时）。
<strong>备注说明：
非标准场景实现是通过直接给被控制设备发送控制命令实现场景功能，当场景里被控制设备较多时或操作较为频繁，丢包的情况较为严重且数据延迟较大。</strong></p>
<h2>15、如何判断设备是否在网（或在线）</h2>
<p>Z-SDK本身不进行设备在线、离线的逻辑判断，在线、离线更多涉及应用端或服务端处理；在Z-SDK层次可以通过呼叫“0x01F8”实现设备是否在网（在线）判断，此命令的反馈为“应答信息（0x02F1）”
<strong>备注说明：
此命令仅对外接电源设备（非ZED休眠节点）或ZED支持唤醒机制功能时生效。</strong></p>
<h2>16、设备列表处理问题</h2>
<p>Z-SDK不会进行设备列表维护。
因此Z-SDK这边针对已入网的ZigBee设备列表是不维护的，需要客户在网关应用层处理：当设备入网触发join_callback回调时在应用层维护设备列表并和服务端保持同步。这样处理可以最大程度保证App，服务端和网关端设备列表信息一致。至于网关应用层和ZigBee层次的设备列表同步，正常情况下可以依据join_callback和leave_callback来进行维护同步。
<strong>备注说明：join_callback和leave_callback均在正常通信情况下触发。</strong></p>
<h2>17、注销设备(0x010E)和leave_callback关系</h2>
<ol>
<li>注销设备(0x010E)是提供给网关应用层删除网关下ZigBee子设备的命令接口，当网关收到服务端发起的“解绑（注销）”命令时，可以调用注销设备(0x010E)接口实现ZC踢除当前网络里面的ZigBee子设备；</li>
<li>ZigBee子设备正常处理ZC下发踢除命令，会给ZC上报一条0x03F2（网关状态）的命令，可以触发Z-SDK的leave_callbakc回调函数；</li>
<li>ZigBee子设备端触发设备重置（ZigBee执行恢复出厂操作），也可也触发leave_callbakc回调函数。
<strong>备注说明：
注销命令（0x010E）不支持对ZED设备（休眠节点：常见为电池供电设备）执行，但特定的一些ZED产品可以支持0x010E命令，如：智能锁具，烟雾传感器（3s唤醒）等，这边设备是可以定期唤醒的，可以处理无线下发的命令。</strong></li>
</ol>
<h2>18、设置颜色HSL（0x012A）问题</h2>
<p>因为Z-SDK优化，关于HSL参数设置存在差异：
在Z-1.3.2（2020-12-10）之前的版本HSL的参数设置范围如下：
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=7668657f54811bcd7c1a4b618d89546c&amp;file=file.png" alt="" />
在Z-1.3.2（2020-12-10）之后的HUE和Saturation设置区间调整如下：
<img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=43a8926ae8c3948b0e68a9733815b5df&amp;file=file.png" alt="" />
<strong>因此在客户更新Z-SDK时需要查下对接记录，并确认下Z-SDK版本，避免因Z-SDK版本更新导致HSL品类设备控制时颜色出现差异。</strong></p>
<h2>19、设备上线事件（0x0308）和设备join_callback判断关系</h2>
<p>设备上线事件（0x0308）触发也是通过0x0000（0D全索引）数据判断的。
和join_callback判断区别在于：
设备上线事件是设备断电后重新上报或ZED设备重新rejoin时触发，告知网关应用层设备恢复和网关正常通信；设备join_callback判断是ZC处于允许入网模式且触发了0x0000全索引数据上报，这个时候才会触发join_callback回调。
<strong>备注说明：
根据上述描述，当网关处于允许入网模式下，刚好有设备重新上电或ZED设备rejoin进来，也会误触发join_callback回调。</strong></p>
<h2>20、设备type识别差异化问题</h2>
<p>更新Z-SDK库后可能会出现部分设备type出现差异：
如场景面板：之前1.3.2的Z-SDK场景面板设备（1-6键）的type均为0x1313；后面因为Z-SDK优化，1-6路的场景面板设备type分别有了对应的type：0x1313表示一路场景面板，0x1360~0x1364分别表示2-6路场景面板。
<strong>备注说明：
因此当客户更新Z-SDK需要明确客户对type处理是否有特定要求，提前提供新的Z-SDK文档并告知客户相关的优化内容。
</strong></p>