============
使用教程
============

-----------
简介
-----------
本程序基于Python语言开发，能够模拟LoRa终端及网关收发LoRaWAN数据包的功能，用于LoRa服务器的正确性测试。

-----------
安装
-----------
本程序支持Python 3.6+版本，跨平台。建议采用 ``pipenv`` 管理依赖环境。

1. 确保机器中已安装Python > 3.6，且pip已升级至最新版本。（升级pip：``pip install --upgrade pip``）

2. 建议安装 ``pipenv``：

::

    pip install pipenv

3. 在一个空目录下创建新的虚拟环境：

::

    pipenv --python 3

4. 修改 ``Pipfile`` 文件，将 ``pypi`` 源改为国内镜像以提高访问速度，例如，清华源 ``https://pypi.tuna.tsinghua.edu.cn/simple``。

5. 安装本程序：

::

    pipenv install lora-mote-emulator

至此，本程序已正确安装至虚拟环境中。

------------
使用方法
------------

本程序包含一个可执行脚本 ``mote`` ，可以通过 ``mote -h`` 查看完整帮助信息

::

    usage: mote [-h] [-v version] [-c CONFIG] [--model MODEL]
        {join,app,pull,mac,rejoin,info,abp,create} ...

    Tool to emulate LoRa mote (a.k.a end-device) and Gateway, supported command
    list: ['join', 'app', 'pull', 'mac', 'rejoin', 'info', 'abp', 'create']

    optional arguments:
        -h, --help              show this help message and exit
        -v version, --version version
                                Choose LoRaWAN version, 1.0.2 or 1.1(default)
        -c CONFIG, --config CONFIG
                                Specify the directory of config files, default './config'
        --model MODEL         Specify the directory to save the model file, default './models'

    Supported commands:
        {join,app,pull,mac,rejoin,info,abp,create}
        join                Send join request.
        app                 Send application data.
        pull                Send PULL_DATA.
        mac                 Send MACCommand.
        rejoin              Send rejoin request.
        info                Show information of current mote.
        abp                 Initialize mote in ABP mode.
        create              Handle configurations.

+++++++++++++
网关准备
+++++++++++++

1. 在初次使用程序时，需要运行 ``mote create [-c config_dir]`` 来创建默认配置文件，
包括 ``device.json`` , ``gateway.json``, ``config.json``, ``abp.json``。 ``-c`` 为可选参数，
用于指定配置文件生成的目录，默认为 ``./config`` 。

2. 修改配置文件的内容，其中：

    -  ``config.json`` 中包含目标服务器的IP地址及端口号，日志层级，超时时间等；
    -  ``gateway.json`` 中包含网关的标识符（Extended Unique Identifier, EUI）；
    -  ``device.json`` 中包含终端的详细信息，包括 ``DevEUI`` , ``JoinEUI`` 以及两个根密钥 ``AppKey`` , ``NwkKey`` ;
    -  ``abp.json`` 如果终端采用个性化激活（Activation by Personalization, ABP）模式入网，则需要修改本配置文件，其中包括设备激活所需的所有字段信息，例如各种会话密钥、终端网络地址等；

3. 在开始发送终端消息前，必须先通过网关的 ``PULL_DATA`` 注册网关的IP地址到服务器（ **重要** ： 部分LoRaWAN服务的实现要求网关定期发送 ``PULL_DATA`` 保持连通性，因此，当无法收到下行数据时，可以尝试 **重新发送** ``PULL_DATA`` 消息）。 ``PULL_DATA`` 发送命令如下：

::

    mote pull

4. 当产生如下日志时，表明收到了服务器返回的 ``PULL_ACK`` 消息，后续可以进行终端的相关操作。

::

    INFO - PULL ACK -

++++++++++++++
终端命令
++++++++++++++

本程序支持的LoRaWAN上行消息包括：

- *Join Request* ,

- *Confirmed Uplink* ,

- *Unconfirmed Uplink* ,

- *Rejoin Request* ,

- *MACCommand* ,

下行消息包括：

- *Join Accept* ,

- *Confirmed Downlink* ,

- *Unconfirmed Downlink* 。

%%%%%%%%%%%%%%%
激活
%%%%%%%%%%%%%%%

首先，终端需要入网后才能继续使用，入网有两种模式，即**空口入网（Over-the-air Activation, OTAA）** 和**ABP**模式。

**************
OTAA
**************

OTAA是指终端和服务器以协商的方式完成入网，建立会话，并生成各类会话密钥。其过程如下：

1. 首先需要在LoRaWAN服务器上注册应用及终端EUI，以及两个根密钥；
2. 修改 ``device.json`` 文件对应字段；
3. 运行 ``mote pull`` ；
4. 运行 ``mote join -n`` ，其中可选参数 ``-n`` 表示建立全新的会话，覆盖以前的终端；
5. 当返回日志中显示 ``INFO - Join Accept (MIC verified)`` 表示收到了 *Join Accept* 消息且经过了消息完整性码（Message Integrity Code, MIC）校验。此时终端入网成功，可以正常发送上行应用数据。

**************
ABP
**************

ABP是指直接在服务器和终端侧将会话字段预设，然后直接进行通信对方式。其过程如下：

1. 首先需要在LoRaWAN服务器上设置终端激活模式为ABP，并设置好会话字段；
2. 修改 ``abp.json`` 配置文件各个对应字段；
3. 运行 ``mote abp`` ，将打印出终端信息，表示已设置成功，可以进行应用数据发送；

%%%%%%%%%%%%%%%
上下行应用数据
%%%%%%%%%%%%%%%

终端激活成功后，可以实现上下行数据发送接收。下行数据只能在发送 **上行数据之后** 才能接收到。上行应用数据命令如下：

::

    mote app [-au] [-f fopts] [msg]

其中，可选参数 ``-a`` 表示将上行数据的 **ACK** 比特位置位， ``-u`` 表示发送 *Unconfirmed Uplink* ， ``-f fopts`` 表示应用数据中包含 *FOpts* （MACCommands）， ``msg`` 为实际需要发送的字符串，将由 ``UTF-8`` 编码，例如：

::

    mote app -au -f 01 hello_world

表示发送 *Unconfirmed Uplink* 消息， **ACK** 比特位置位，包含 *FOpts*  ``0x01`` ，应用消息为字符串 ``hello_world`` 。

根据不同的LoRaWAN服务器实现，终端可能收到不同的下行消息，也可能收不到回复（ *Unconfirmed Uplink* ）。本程序将等待一定时间（ ``config.json`` 中 ``timeout`` 字段）后超时停止。

当收到下行消息时，命令行将显示 ``INFO - Downlink MACPayload (MIC verified)``，并显示该消息中的关键字段。

%%%%%%%%%%%%%%%%%
重新入网请求
%%%%%%%%%%%%%%%%%

本程序支持发送三类 *Rejoin Request* 请求（LoRaWAN Version 1.1.0新增），请求格式如下：

::

    mote rejoin {0,1,2}

服务器若同意请求，则返回 *Join Accept* 消息。

%%%%%%%%%%%%%%%%%
MACCommand
%%%%%%%%%%%%%%%%%

本程序支持通过 *FRMPayload* 发送 *MACCommand* 命令，即 *FPorts = 0* ，请求格式如下：

::

    mote mac [-au] [cmd]

其中，可选参数 ``-au`` 作用和应用消息一致； ``[cmd]`` 表示实际发送的MACCommand指令的十六进制字符串形式。例如，发送 ``0x01`` ，则采用如下命令：

::

    mote mac 01

%%%%%%%%%%%%%%%%%
查看终端信息
%%%%%%%%%%%%%%%%%

查看终端信息采用 ``mote info`` 即可。