From b22370a2bbc04a3d5edd35fa6e5862e6cced4417 Mon Sep 17 00:00:00 2001
From: Alexandre Abadie <alexandre.abadie@inria.fr>
Date: Fri, 12 Apr 2019 11:01:03 +0200
Subject: [PATCH] examples/lorawan: update README

---
 examples/lorawan/README.md | 58 +++++++++++++++++++++++++-------------
 1 file changed, 38 insertions(+), 20 deletions(-)

diff --git a/examples/lorawan/README.md b/examples/lorawan/README.md
index b5ce4dd5638d..f6e0420cf259 100644
--- a/examples/lorawan/README.md
+++ b/examples/lorawan/README.md
@@ -1,22 +1,39 @@
-LoRaWAN - OTAA
-==============
+## LoRaWAN
 
-Description
------------
+### Description
 
-This application shows a simple use case of LoRaWAN with RIOT.
+This application shows a basic LoRaWAN use-case with RIOT.
 
 By using the real time clock and low-power capabilities of a board, this
-application shows how to program a LoRaWAN Class A device using RIOT.
+application also shows how to program a LoRaWAN Class A device using RIOT.
 
-This application is using the Over-The-Air Activation (OTAA) procedure.
+By default, the application uses the Over-The-Air Activation (OTAA) procedure.
 
-Usage
------
+### Configuration
 
-Simply build and flash the application for a ST B-L072Z-LRWAN1 board:
+To join a LoRaWAN network using OTAA activation, edit the application
+`Makefile` and set your device information:
 
-    make flash term
+    ACTIVATION_MODE ?= otaa
+    DEVEUI ?= 0000000000000000
+    APPEUI ?= 0000000000000000
+    APPKEY ?= 00000000000000000000000000000000
+
+To join a LoRaWAN network using ABP activation, edit the application
+`Makefile` and set your device and LoRaWAN application information:
+
+    ACTIVATION_MODE ?= abp
+    DEVADDR ?= 00000000
+    NWKSKEY ?= 00000000000000000000000000000000
+    APPSKEY ?= 00000000000000000000000000000000
+    RX2_FREQ ?= 869525000
+    RX2_DR ?= 3
+
+Note that rx2 frequency (`RX2_FREQ`) and datarate (`RX2_DR`) variables must be
+set explicitly at compile time when using ABP activation because they are
+supposed to be known in advance by the network and the device. In this example,
+the values used are compatible with TheThingsNetwork provider network.
+They might change depending on the network provider used.
 
 Use the `BOARD`, `DRIVER` and `LORA_REGION` make variables to adapt the application
 to your hardware setup and region of use:
@@ -26,17 +43,18 @@ to your hardware setup and region of use:
 - `LORA_REGION` can be `EU868`, `US915`, etc (see LoRaWAN regional parameters for
   details).
 
-ST Nucleo-64 can be used with mbed LoRa shields: there's one based on
-[the sx1276 radio](https://os.mbed.com/components/SX1276MB1xAS/) and one based
-on the [the sx1272 radio](https://os.mbed.com/components/SX1272MB2xAS/).
+The `SEND_PERIOD_S` variable can also be adapted to change the time period (in
+seconds) between each message sent by the device.
 
-Finally, to join a LoRaWAN network using OTAA activation, use `make menuconfig`
-inside the application and edit the configuration or edit the application
-`Makefile` :
+### Usage
 
-    DEVEUI ?= 0000000000000000
-    APPEUI ?= 0000000000000000
-    APPKEY ?= 00000000000000000000000000000000
+Simply build and flash the application for a ST B-L072Z-LRWAN1 board:
+
+    make flash term
+
+ST Nucleo-64 can be used as-is with mbed LoRa shields: there's one based on
+[the sx1276 radio](https://os.mbed.com/components/SX1276MB1xAS/) and one based
+on the [the sx1272 radio](https://os.mbed.com/components/SX1272MB2xAS/).
 
 ## Automatic test