Welcome to lora-motes-emulator’s documentation!¶

Tutorials¶

Introduction¶

lora-mote-emulator is developed by Python. It can emulate LoRa motes (a.k.a end-devices) and LoRa Gateways to send and receive LoRaWAN packages. It can be mainly utilized to test LoRaWAN servers.

Installation¶

lora-mote-emulator supports Python 3.6+, and is distributed via Pypi. Therefore, we can directly use pip to install this program. Meanwhile, pipenv is recommended to manage virtual environments.

1. Make sure Python > 3.6 is installed on the machine, and pip is upgraded to the latest version. To upgrade pip, use pip install --upgrade pip .

Install pipenv:

pip install pipenv

Create a new virtual environment in an empty directory:

pipenv --python 3

Install lora-mote-emulator:

pipenv install lora-mote-emulator

Now, the emulator is installed successfully.

Usage¶

The emulator includes an executable mote, thus, mote -h can show the help message

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.

Prepare gateway¶

1. At the very beginning, we need to create configuration files. Run mote create [-c config_dir] to generate configuration files at directory config_dir ( ./config in default). The configuration files include device.json, gateway.json, config.json, and abp.json.

Modify the content of each configuration file:

config.json includes the server’s IP address and port number, log level and timeout, etc.
gateway.json includes the gateway’s extended unique identifier (EUI),
device.json includes the detailed parameters of mote, i.e., DevEUI, JoinEUI and two root keys, i.e., AppKey and NwkKey,
abp.json includes required fields if mote is activated via Activation by Personalization (ABP) mode.

3. Before mote sending message, the gateway needs to register the IP address to server via PULL_DATA message. ( Note: Some LoRaWAN servers may require gateways to send PULL_DATA periodically to keep-alive. Therefore, if we get nothing from servers, we can send a PULL_DATA first, then re-try the message. To send a PULL_DATA message, use following command:

mote pull

4. If INFO - PULL ACK - logs, it means a PULL_ACK message is received from server. Since then, mote can send real LoRaWAN messages.

Mote commands¶

All the supported LoRaWAN uplink message types are as follows:

Join Request ,
Confirmed Uplink ,
Unconfirmed Uplink ,
Rejoin Request ,
MACCommand ,

Downlink message types include：

Join Accept ,
Confirmed Downlink ,
Unconfirmed Downlink 。

Activation¶

First of all, the mote needs to be activated before using. There are two modes of activations, i.e., Over-the-air Activation (OTAA), and ABP.

OTAA¶

OTAA stands for the activation by which mote need to negotiate with server to establish session and generate various session keys. To activate mote in OTAA mode, do the following:

Register application and mote EUI (JoinEUI and DevEUI), and the two root keys,
Modify device.json config file,
Run mote pull ,
Run mote join -n , where -n option means to establish brand new session which may override the old one.
When the log shows INFO - Join Accept (MIC verified) , it means that a Join Accept message is received and the message integrity code (MIC) is verified. Now the mote has been activated, and can be used to send application messages.

ABP¶

ABP mode means that the session parameters are preset in both server and mote sides, making them able to communicate directly. The process is shown as follows:

Set the activation mode to be ABP on LoRaWAN server, and set all the session parameters,
Modify abp.json file on all fields,
Run mote abp. If the mote information is printed, the ABP activation succeeds.

Uplink & Downlink Application message¶

After activation, the mode can send and receive application data. Downlink message can only be received after sending an uplink message successfully. To send uplink message, use:

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

where -a option means to set the ACK flag in uplink package, -u option stands for Unconfirmed Uplink message type, and -f fopts means the package include FOpts (MACCommands). msg is the actual string that needs to be sent, and it will be encoded by UTF-8. For example:

mote app -au -f 01 hello_world

means send an Unconfirmed Uplink message, set the ACK flag, and include FOpts 0x01 . The application message is the string hello_world .

According to different implementation of LoRaWAN server, the downlink messages could be quite different. There may also be no reply ( Unconfirmed Uplink ). lora-mote-emulator will wait until timeout.

When a downlink message is received, the command line will display message INFO - Downlink MACPayload (MIC verified), and show some important fields.

Rejoin request¶

Our program supports to send all three types of Rejoin Request (New in LoRaWAN Version 1.1.0), e.g.:

mote rejoin {0,1,2}

If server agrees the request, it will reply with Join Accept message.

MACCommand¶

mote can send MACCommand via FRMPayload field, i.e. FPorts = 0. The command is as follow:

mote mac [-au] [cmd]

where -au act the same as in app , and [cmd] stands for the actual commands (in hex string form) that needs to be sent. For example, to send 0x01 , use:

mote mac 01

Check mote information¶

Use mote info to display the information of current mote.

使用教程¶

简介¶

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

安装¶

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

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

pip install pipenv

pipenv --python 3

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

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 。

修改配置文件的内容，其中：
- config.json 中包含目标服务器的IP地址及端口号，日志层级，超时时间等；
- gateway.json 中包含网关的标识符（Extended Unique Identifier, EUI）；
- device.json 中包含终端的详细信息，包括 DevEUI , JoinEUI 以及两个根密钥 AppKey , NwkKey ;
- abp.json 如果终端采用个性化激活（Activation by Personalization, ABP）模式入网，则需要修改本配置文件，其中包括设备激活所需的所有字段信息，例如各种会话密钥、终端网络地址等；
在开始发送终端消息前，必须先通过网关的 PULL_DATA 注册网关的IP地址到服务器（重要：部分LoRaWAN服务的实现要求网关定期发送 PULL_DATA 保持连通性，因此，当无法收到下行数据时，可以尝试 重新发送 PULL_DATA 消息）。 PULL_DATA 发送命令如下：

mote pull

当产生如下日志时，表明收到了服务器返回的 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是指终端和服务器以协商的方式完成入网，建立会话，并生成各类会话密钥。其过程如下：

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

ABP¶

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

首先需要在LoRaWAN服务器上设置终端激活模式为ABP，并设置好会话字段；
修改 abp.json 配置文件各个对应字段；
运行 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 即可。

Use ChirpStack as LoRa Server¶

Please refer to the official website for more information. https://www.chirpstack.io/guides/docker-compose/

Install docker.
Clone the repo https://github.com/brocaar/chirpstack-docker.git.
docker-compose up.
Open a browser, visit the default application server https://localhost:8080.
Login with default username and password, both are admin.
Setup a network-server. The default is chirpstack-network-server:8000.
Create Service-profiles.
Create Device-profiles.
Register a gateway, and fill in a Gateway EUI.
Create an application, select a service profile.
Click the application name, and create a device belongs to the application.
- Fill in a Device EUI,
- Choose a device profile,
- Optional: uncheck the frame-counter validation for convenient test.
After click the CREATE DEVICE button, NwkKey and AppKey need to be filled (For LoRaWAN 1.0.2, only AppKey is needed), then the configuration of ChirpStack server is completed.
Now, we can use lora-motes-emulator to issue join request in OTAA mode. (This part is also shown in README.rst)
- Prepare the config files.
  - For LoRaWAN 1.0.2, copy the template file config/device102.yml.tpl as config/device.yml, for LoRaWAN 1.1, copy the template file config/device.yml.tpl as config/device.yml.
  - Modify the device.yml file and fill in the information according to the register information at step 8.
  - Copy the config/config.yml.tpl as config/config.yml, fill in the IP and port information of ChirpStack server (Default port number is 1700).
- Start the pipenv environment by pipenv shell.
- Send a PULL_DATA to ChirpStack server by python main.py pull.
- Send a join request message to ChirpStack server by python main.py join.
- If the join accept message is decoded successfully, we can check the device information by python main.py info.
- An Uplink message can be sent by python main.py app -m YOUR_MESSAGE, which can also combine with MAC command by option -f MAC_COMMAND_ID.
Key Points:
- The Uplink data rate index and the Channel index is required to calculate the MIC field (B1 message) in version 1.1.

Welcome to lora-motes-emulator’s documentation!¶

Tutorials¶

Introduction¶

Installation¶

Usage¶

Prepare gateway¶

Mote commands¶

Activation¶

OTAA¶

ABP¶

Uplink & Downlink Application message¶

Rejoin request¶

MACCommand¶

Check mote information¶

使用教程¶

简介¶

安装¶

使用方法¶

网关准备¶

终端命令¶

激活¶

OTAA¶

ABP¶

上下行应用数据¶

重新入网请求¶

MACCommand¶

查看终端信息¶

Use ChirpStack as LoRa Server¶

Indices and tables¶

lora-mote-emulator

Navigation

Related Topics