H3C 绿洲接入第三方LoRa终端链路对接指导手册

    绿洲实现了LoRaWAN，给第三方提供LoRa终端接入能力，只要按照本文档指导实现LoRa终端接入功能就可以接入绿洲，和新华三一起共建LoRa网络生态。

物理信道规划（对接基础）

    LoRaWAN 标准除了定义了MAC层协议，同时定义了各个国家的物理信道规划，在中国，LoRaWAN定义了两个标准，China 779-787MHz ISM 频段和 CN470-510MHz 频段，China 779-787MHz 是最初定义的标准，不是很成熟，目前在中国使用 CN470-510MHz 频段比较普遍

CN470-510MHz

    绿洲目前是基于 LoRaWAN1.0.2版本进行实现的，支持 CN470-510MHz 物理信道规划，第三方终端收发报文须按照 CN470-510MHz 频段规划实现。

对于 CN470-510MHz 频段，信道规划如下图：

    以470.3MHz频点为上行0号信道，间隔0.2MHz，上行共96个信道。下行以500.3MHz 频点为0号信道，同样间隔0.2MHz，共48个行信道。
终端发包可以在上行的96信道中选择一个信道发送，对于ClassA&C的终端，下行接收按照下表定义接收数据。对于Class B终端，打开固定的ping窗口接收下行数据。

工作模式

    绿洲支持Class A/C终端，第三方终端可以按照自己的需求和应用场景决定终端工作在哪种模式，模式固定后，按照 loraWAN1.0.2 标准实现对应模式的终端行为。

终端唯一资源

devEUI

    按照 LoRaWAN 定义，devEUI 用于表示终端全球唯一，是IEEE EUI64地址格式，绿洲开放给第三方终端接入，不同的厂家对于devEUI保障能够唯一，请各终端厂家按照自己的 MAC 地址按照 EUI64 格式进行映射衍生。衍生规则参考下图描述，使用 0xFF 0xEE。

    绿洲平台支持两种 devEUI 定义方式:
    方式一：标准的 EUI64 格式定义，保证全球唯一
    方式二：由 H3C 分配地址，但该地址只保证在 H3C 平台内唯一，不保证全球唯一性。　　

    H3C 内部分配地址规则如下：　　

    厂家 ID：总共 4 字节。绿洲平台开发者中心创建设备型号时会分配厂家 ID。
    时间：总共 2 字节，19 表示 2019 年，2 表示 2 月份，如果是 10 月份，使用字母‘A’，0 预留做扩展使用。
    设备 ID：总共 2 字节，厂家自己定义。同一批次生成的设备保证唯一。
    从跨平台考虑，devEUI 的定义推荐方式一。

APPKey

    按照 LoRaWAN 定义，AppKey 作为根密钥用于终端生成 appSKey 和 nwkSKey，每一个终端保证唯一，第三方终端应该保证 AppKey 每个终端能够唯一，如果没有保证唯一，在批量终端上线时会导致报文被其他终端解析，导致其他终端异常，可以把 AppKey 通过标签打印在每个设备上或其他的方式记录下来。厂家自定义的 AppKey 有可能在平台上和其他厂家的终端 AppKey 一样，导致同时上线时异常，但这个概率比较低。厂家可以自定义绿洲平台唯一的 AppKey，静态 AppKey 规格定义如下：

    厂家 ID：总共 4 字节。绿洲平台开发者中心创建设备型号时会分配厂家 ID。
    如果不采用上述方式，H3C 绿洲提供一种 AppKey 生成的算法，只需要在绿洲平台上配置 PublicKey 就可以。
    AppKey 生成公式如下：
    AppKey = aes128_encrypt(Key, DevEUI | DevNouce | Salt | pad16);
    其中：Key=“H3CLoRaWanPublic”，共 16 字节，转换为十六进制，共 128bit，这也是其在绿洲平台上进行配置的 key，实际后台使用算法生成的 key 对 join-accept 报文进行加解密。对于第三方终端也支持使用该算法进行 AppKey 的生成，第三方终端可以支持修改 AppKey，如果修改默认 Key，那实际使用配置的Key进行加解密。本算法不适应。
    DevEUI: 标识厂家设备唯一标识，要求全球唯一。
    DevNonce：设备随机数，参考协议，绿洲平台支持两种不同的方案用于适配不同的模组的特点，对于可以控制 DevNonce 的模组，可以使用随机数，对于无法控制 DevNonce 的模组可以用全零替换。使用随机数生成可以保证每次入网都不同，更具安全性。
    Salt：厂家密钥 ID，保障不同第三方厂家密钥的安全性，由绿洲平台开发者中心创建型号时指定，第三方终端需要对该 Salt 进行保密。
    Pad16: 用 0x00 进行 16 字节整数倍长度补齐，可以参考 LoRaWAN 协议。
相关算法实现参考下面范例：

    对于上 H3C 绿洲平台的终端，建议使用算法生成 AppKey 的方式，方便后续平台优化简化配置。

APPEUI

    按照 LoRaWAN 定义，APPEUI 是全球唯一的 ID，EUI64 格式，建议第三方终端厂家使用厂家的 MAC地址按照 EUI64 进行衍射生成，保障各个厂家终端的唯一性。如果不按照本建议，第三方厂家需要向绿洲申请平台唯一的 APPEUI，但该申请的 APPEUI 只能保证在绿洲平台唯一。
    AppEUI 总共 8 字节，绿洲平台按照下面格式进行规划：

    厂家 ID：总共 4 字节。绿洲平台开发者中心创建设备型号时会分配厂家 ID。
    厂家产品标识：总共 4 字节，厂家自己定义。按照一款应用设备来分配，比如门锁定义一个，开关定义一个。

DevAddr

    DevAddr 用于终端和 server 数据传输过程唯一标识终端在该网络中的 ID，第三方终端接入绿洲，在绿洲上创建终端后，devAddr 由绿洲统一分配，在终端 join 过程中通过 Join accept 报文告诉终端。对于 ABP模式终端，第三方终端需要接入绿洲，需要按照绿洲分配的地址进行配置修改。

报文字节序

    LoRaWAN 未定义报文传输的字节序，网上的开源 SDK 代码是网络序，绿洲按照 SDK 实现，使用网络序进行报文的通信。

终端上线

    绿洲支持 ABP 和 OTAA 两种上线方式，ABP 模式需要在绿洲上先配置终端获取平台分配的地址（devAddr），再通过本地配置终端，如果第三方终端不支持本地配置地址，建议不要使用 ABP 模式。
    OTAA 是动态协商的方式，终端和 server 通过 join 机制实现。绿洲 Join 机制按照 LoRaWAN1.0.2 实现，上线成功后会和 server 协商出地址以及加密使用的密钥。Join accept 报文中有对终端 RXdelay、RX1DRoffset、RX2 Data rate 和 CFList 的配置，除 CFList 外，要求第三方终端必须支持这些配置。
绿洲定义 Join 过程的相关的参数如下表：

    绿洲目前使用接收窗口 1 来回复 join accept 报文，第三方终端在该窗口进行 join accept 报文处理。第三方终端根据自己的产品定位决定使用某种速率（DR0~DR5）进行入网，但为了保障终端能够顺利上线，建议终端使用低速率（DR0）进行上线，同时配合 ADR 机制，进行后续的调速。如果终端不支持 ADR 机制，为了增加基站的负载能力，优化 lora 空口资源的利用，建议终端固定速率或使用降速时，速率不要低于DR3（SF9，BW125）。
    对于 CN470-510MHz 频段，终端入网时如果在上行 96 个信道随机选择信道入网，那入网速度较慢，终端可以做一定的算法优化，建议把 96 个信道按照 8 个连续信道为一组，共 12 组，轮询在 12 个组间进行信道探测入网。终端一轮探测没有入网，建议对于 Class A 终端，可以适当延长入网探测周期，提高终端的电池寿命。

数据上报

    LoRaWAN1.0.2 定义了数据报文的格式，请按照 LoRaWAN1.0.2 定义的报文头格式组织报文，同时要求第三方终端支持报文头中各个标识位。
ADR – 用于表示终端是否支持 ADR 控制，终端可以根据自己情况选择支持或不支持，为了电量的合理利用，建议终端支持 ADR 功能。
ADRACKReq – 用于表示终端请求 server 响应 ACK，终端需要周期确认 server 下行报文是否可达，如果不可达，需要进行降速处理，请按照 LoRaWAN1.0.2 定义实现降速流程。
ACK – server 用于响应 ADRACKReq，绿洲支持 ACK 响应。
FPending – 如果 server 上有终端的数据缓存，会置位该标识，绿洲支持该标识，终端必须支持，对于 Class A 和 Class B 类型终端在识别有该标识时立刻触发一次上行发包（可以是空报文），拉取缓存的数据。该上行报文使用 FPort 值为 3。

FPort规定

LoRaWAN 规定了 FPort 的使用规范，如下：
 0 ： 表示 FRMPayload 中只有 MAC 命令
 1~223（0x01~0xDF）： 应用数据使用
 224～255 (0xE0～0xFF) ：保留值，后续扩展
对于 1~223 绿洲定义了应用的使用规范，1~127（0x01~0x7F）用于绿洲内部自己使用，目前规定如下：
 3：空报文，可用于 confirm 报文响应、带 ADRACPReq 报文请求响应或带 FPending 触发下一次上行空报文拉取数据。
对于 128~223（0x80~0xDF）开放给第三方，用于第三方自己定义应用数据格式，第三方可以随机使用，自己保证不重复即可。

信道选择

CN470-510MHz

    对于 CN470-510MHz 频段，上行 96 个信道下行 48 个信道，采用全双工的 FDD 机制进行信道划分，一般的基站单个射频最多可以覆盖 8 个上行信道，所以 H3C 基站从实际应用出发，在不违背 LoRaWAN 对于 CN470-510MHz 频段信道规划的规定的前提下，对 96 个上行信道进行信道组划分，把 96 个信道按照 8个连续信道划为一组，共 12 组。

    上行信道组划分如下表：

    终端在实际信道使用时可以按照项目的需要，对项目落地的环境进行测量，选择干净的信道进行通信，信道可以按照 H3C 信道组的规划选择一组信道来实施。
终端也可以实现在 96 个信道中进行探测入网，一旦入网后固定在该信道组内进行收发数据，在确定和server 数据不通时，可以结合 ADR 机制进行降速，最后重新入网探测。

网络管理

    终端的网络管理是通过 MAC Command 实现的，绿洲对于终端的网络管理主要按照 LoRaWAN1.0.2 定义实现，部分配置按照 LoRaWAN1.1 定义实现，会在具体配置中说明。

发送速率DR配置(可选)

    LinkADRReq&LinkADRAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本，可以配置终端报文发送使用的速率 DR 值。第三方终端可以支持该项配置，在覆盖差的环境下，配置高速率可能会导致网络不通，所以该功能可选。

    CN470-510MHz 频段绿洲上功率与配置对应表如下：

注：SDK 的版本不同，对于 TxPower 的定义也不同，绿洲遵守上面的对应关系，需要第三方终端适配对应。

发送信道配置(可选)

    LinkADRReq&LinkADRAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本，可以配置终端报文发送使用的信道集。第三方终端可以根据应用场景固定使用频段进行发包，但这种方式不适合不同区域对于信道规划的差异性，建议第三方终端支持该项配置。不同的频段对于信道组的使用有不同的规则。
CN470-510MHz 频段共 96 个上行信道，不管那一款基站不可能覆盖 96 个上行信道，终端按照 SDK 在96 个信道中进行随机发送，那报文会丢包。绿洲对这 96 个信道进行了分组，8 个连续的信道为一组，共 12组，建议第三方终端选择信道发送报文时以信道组为基础进行探测发包，如果该组网络能收发数据，则在这组中的连续 8 个信道进行随机发包。

发送报文副本数配置(可选)

    LinkADRReq&LinkADRAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本，可以配置unconfirm 报文的发送副本数。绿洲目前支持的配置范围为 1~3。
第三方终端根据自己的业务特点选择是否支持该项配置，如果支持该特性，每个 unconfirm 报文发送都重复发送多个副本。

接收窗口1速率偏移配置

    RXParamSetupReq&RXParamSetupAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本。该配置可以影响 RX1 接收窗口的速率，该配置除了 MAC command 可以配置，join accept 中也会下发。一般上线完成后，使用 MAC command 下发生效。
该功能可以调整终端上下行使用不同的速率，第三方终端必须支持 join accept 配置生效，MAC 命令建议支持。

接收窗口1延迟时间配置

    RXTimingSetupReq&RXTimingSetupAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本。该配置可以影响 RX1 接收窗口时间的开启，该配置除了 MAC command 可以配置，join accept 中也会下发。一般上线完成后，使用 MAC command 下发生效。
绿洲对于 RX1 接收时间建议使用 5s，最小可以配置 3s。
该功能可以调整终端下行接收的时间窗口延迟，可以根据网络延迟动态调整配置，所以第三方终端必须支持 join accept 配置生效，MAC 命令建议支持。

接收窗口2速率 DR 配置

    RXParamSetupReq&RXParamSetupAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本。该配置可以影响 RX2 接收窗口的速率，该配置除了 MAC command 可以配置，join accept 中也会下发。一般上线完成后，使用 MAC command 下发生效。
该功能可以调整终端下行使用固定的速率，第三方终端必须支持 join accept 配置生效，MAC 命令建议支持。

接收窗口2信道配置

    RXParamSetupReq&RXParamSetupAns MAC command 中定义，绿洲支持 LoRaWAN1.0.2 版本。该配置可以影响 RX2 接收窗口使用的信道。
该功能可以调整终端 RX2 下行信道，而不是固定的 505.3MHz，可以对终端信道进行规划操作，所以建议终端支持该功能。

高级功能

ADR 功能

    速率自适应是 LoRaWAN 定义的高级功能，支持 ADR 可以实现速率的自动调速，在网络信号比较好的时候，可以自动提速，优化网络带宽，提速网关的负载量。但 LoRa 是开放频段，网络的干扰不确定因素比较多，可能会出现提速后某一段时间干扰比较严重导致丢包。ADR 有降速的机制，但该机制默认没有那么敏感，降速会比较慢。所以本功能可以配合保活检测链路的连通性并异常重启机制进行，能达到快速恢复覆盖。
对于一些保障覆盖的终端，可以使用固定速率的方式，不支持 ADR 功能，所以本功能可选。

信道探测扫描

    第三方终端入网要求使用 SF12 速率入网，入网能够支持信道组探测功能，在每个信道组里至少发送 3 个报文，如果都未入网，则切换到下一个信道组进行入网。在遍历所有信道组后还未进行入网，终端可以自己定义后续的行为。
终端入网成功后，能够记录入网成功的信道组，在下一次重启入网时能优先从该信道组进行入网尝试，达到快速入网。如果优先的信道组未能入网，则尝试下一组信道组，直到所有信道组都轮询结束。

应用层功能

注册认证（可选）

    终端根据应用需要，可以实现应用平台的设备注册认证功能，注册报文可以携带版本号，设备型号，设备 ID 等信息。本功能可根据需要进行设计，功能可选。

保活

    LoRaWAN 定义了终端上线的方式，未定义离开的方式，绿洲通过监控终端的保活判断终端是否离线，所以第三方终端必须实现保活功能，保活报文中可以携带版本号、电量、低电量标记等信息。如果注册报文携带版本号信息，则版本号可以不用携带。
保活报文需要设计成请求和应答的模式，在 3 次保活未应答的情况下可以进行重启来尝试恢复。

重启

    设备需具备自动重启的基础功能，在某些场景设备与平台失联，如：
 平台由于自身原因升级后，原始终端运行数据丢失，重新配置终端设备信息后，无法直接与终端设备通信，终端设备在感知三个周保活周期未与平台通信成功，需自动重启。
 终端设备由于自身原因出现无法与平台通信，需要在三个保活周期后自动重启。

低功耗

    对于第三方终端，如果业务场景使用电池供电，按照业务使用的场景不同对于设备使用时间的要求也不同，例如对于门锁类可以要求至少 6 个月的供电，对于地磁井盖类设备，则可以要求 3-5 年的供电。具体由方案进行要求。

版本升级

    第三方终端应该提供版本升级的功能，可以通过本地或无线对其进行版本升级，并提供配套的版本升级工具。

其他功能

终端覆盖

    第三方终端对于覆盖的要求应该满足终端使用场景要求，具体可以根据业务需要进行定义。