Skip to content

Commit 5da8d50

Browse files
author
Amanda Butler
authored
Merge pull request #414 from hasnainvirk/lorwan_docs
Adding LoRaWAN docs for Mbed-OS 5.8
2 parents e20370c + 358148d commit 5da8d50

File tree

7 files changed

+315
-0
lines changed

7 files changed

+315
-0
lines changed

‎docs.json

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -386,6 +386,30 @@
386386
}
387387
]
388388
},
389+
{
390+
"title": "LoRaWAN",
391+
"intro": {
392+
"type": "markdown",
393+
"url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawan.md"
394+
},
395+
"sources": [{
396+
"type": "markdown",
397+
"url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawanconfig.md"
398+
},
399+
{
400+
"type": "markdown",
401+
"url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawanevents.md"
402+
},
403+
{
404+
"type": "markdown",
405+
"url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/errorcodes.md"
406+
},
407+
{
408+
"type": "markdown",
409+
"url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/loraradio.md"
410+
}
411+
]
412+
},
389413
{
390414
"title": "Security",
391415
"intro": {

‎docs/reference/api/api.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ The [APIs](/docs/development/introduction/glossary.html) in this document are or
66
- [Drivers](/docs/development/reference/drivers.html): analog and digital input and outputs and digital interfaces.
77
- [RTOS](/docs/development/reference/rtos.html): handling tasks and events in Mbed OS.
88
- [Network Socket](/docs/development/reference/network-socket.html): network sockets, Ethernet, Wi-Fi, cellular and mesh networking.
9+
- [LoRaWAN](/docs/development/reference/lorawan.html): low power wide area network.
910
- [Bluetooth](/docs/development/reference/bluetooth.html): bluetooth low energy.
1011
- [Security](/docs/development/reference/security.html): working with Arm Mbed uVisor and Arm Mbed TLS in the context of Mbed OS.
1112
- [Storage](/docs/development/reference/storage.html): working with the file system.

‎docs/reference/api/connectivity/lorawan/errorcodes.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
<h2 id="lorawan-error-codes">Mbed LoRaWAN Stack error codes</h2>
2+
3+
All operations on `LoRaWANInterface` return an error code `lorawan_status_t` that reflects success or failure of the operation.
4+
5+
Here is the list of error codes and their description.
6+
7+
| Error code | Value | Description |
8+
| --------------- | ------------- | ----------|
9+
| `LORAWAN_STATUS_OK`| 0 | Service done successfully |
10+
| `LORAWAN_STATUS_BUSY`| -1000| Stack busy |
11+
|`LORAWAN_STATUS_WOULD_BLOCK`| -1001 | Stack cannot send at the moment or have nothing to read |
12+
| `LORAWAN_STATUS_SERVICE_UNKNOWN`| -1002 | Unknown service request |
13+
| `LORAWAN_STATUS_PARAMETER_INVALID`| -1003 | Invalid parameter |
14+
| `LORAWAN_STATUS_FREQUENCY_INVALID`| -1004| Invalid frequency |
15+
| `LORAWAN_STATUS_DATARATE_INVALID` | -1005| Invalid frequency and datarate |
16+
| `LORAWAN_STATUS_FREQ_AND_DR_INVALID`| -1006| When stack was unable to send packet in TX window |
17+
|`LORAWAN_STATUS_NO_NETWORK_JOINED`| -1009 | Device is not part of a network yet (Applicable only for OTAA) |
18+
|`LORAWAN_STATUS_LENGTH_ERROR`| -1010 | Payload lenght error |
19+
| `LORAWAN_STATUS_DEVICE_OFF`| -1011 | The device is off, in other words, disconnected state |
20+
| `LORAWAN_STATUS_NOT_INITIALIZED`| -1012| Stack not initialized |
21+
| `LORAWAN_STATUS_UNSUPPORTED`| -1013| Unsupported service |
22+
| `LORAWAN_STATUS_CRYPTO_FAIL`| -1014| Crypto failure |
23+
|`LORAWAN_STATUS_PORT_INVALID`| -1015 | Invalid port |
24+
|`LORAWAN_STATUS_CONNECT_IN_PROGRESS`| -1016 | Connection in progress (application should wait for CONNECT event) |
25+
|`LORAWAN_STATUS_NO_ACTIVE_SESSIONS`| -1017 | No active session in progress |
26+
|`LORAWAN_STATUS_IDLE`| -1018 | Stack idle at the moment |

‎docs/reference/api/connectivity/lorawan/loraradio.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<h2 id="loraradio-api">LoRaRadio</h2>
2+
3+
`LoRaRadio` is a pure virtual class that defines APIs for a LoRa radio driver.
4+
5+
An implementation of this class is passed to the Arm Mbed LoRaWAN stack. Please see existing [Mbed OS supported drivers](https://github.com/ARMmbed/mbed-semtech-lora-rf-drivers) for more information.
6+
7+
### LoRaRadio class reference
8+
9+
[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_lo_ra_radio.html)
10+
11+
### LoRaRadio example
12+
13+
[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/file/dc95ac6d6d4e/main.cpp)

‎docs/reference/api/connectivity/lorawan/lorawan.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<h2 id="lorawan-api">LoRaWAN</h2>
2+
3+
LoRaWAN is a technology designed for low-power battery powered devices. These devices operate in an unlicensed spectrum, creating high desnity wide-area networks.
4+
5+
Arm Mbed OS provides a native network stack for LoRaWAN, which can run on any Mbed Enabled device with a LoRa radio onboard.
6+
7+
The [LoRaWANInterface](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_lo_ra_w_a_n_interface.html) provides a C++ API for connecting to the internet over a LoRa network.
8+
9+
## LoRaWANInterface class reference
10+
11+
[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_lo_ra_w_a_n_interface.html)
12+
13+
## Usage
14+
15+
To bring up the Mbed LoRaWAN stack, consider the following progression:
16+
17+
1) An [EventQueue](https://os.mbed.com/docs/v5.8/reference/eventqueue.html) object:
18+
19+
```cpp
20+
// construct an event queue
21+
EventQueue ev_queue(NUM_EVENTS * EVENTS_EVENT_SIZE);
22+
```
23+
24+
2) A [LoRaRadio](https://os.mbed.com/docs/v5.8/reference/loraradio.html) object:
25+
26+
```CPP
27+
// construct a LoRadio object
28+
SX1272_LoRaRadio radio(PIN_NAMES ... );
29+
```
30+
31+
3) Instantiate `LoRaWANInterface`, and pass `LoRaRadio` object:
32+
33+
```CPP
34+
LoRaWANInterface lorawan(radio) ;
35+
```
36+
37+
4) Initialize mac layer and pass `EventQueue` object:
38+
39+
```CPP
40+
lorawan.initialize(&ev_queue);
41+
```
42+
43+
5) Set up the event callback:
44+
45+
```cpp
46+
lorawan_app_callbacks_t callbacks
47+
callbacks.events = mbed::callback(YOUR_EVENT_HANDLER);
48+
lorawan.add_app_callbacks(&callbacks);
49+
```
50+
51+
6) Add network credentials (security keys) and any configurations:
52+
53+
```CPP
54+
lorawan_connect_t connection;
55+
56+
connection.connect_type = LORAWAN_CONNECTION_OTAA;
57+
connection.connection_u.otaa.app_eui = YOUR_APP_EUI_KEY;
58+
connection.connection_u.otaa.dev_eui = YOUR_DEV_EUI_KEY;
59+
connection.connection_u.otaa.app_key = YOUR_APP_KEY;
60+
connection.connection_u.otaa.nb_trials = MBED_CONF_LORA_NB_TRIALS;
61+
62+
lorawan.connect(connection);
63+
```
64+
65+
### LoRaWAN example
66+
67+
Please visit our Arm Mbed Online Compiler example, and follow the instructions in the `README.md`.
68+
69+
[![View code](https://www.mbed.com/embed/?url=https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan)](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-lorawan/file/dc95ac6d6d4e/main.cpp)
70+
71+
### Related content
72+
73+
- End-to-end [LoRa on Arm Mbed tutorial](https://docs.mbed.com/docs/lora-with-mbed/en/latest/).

‎docs/reference/api/connectivity/lorawan/lorawanconfig.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
<h2 id="lorawan-configuration">Configuring Mbed LoRaWAN Stack</h2>
2+
3+
Various parameters for Mbed LoRaWAN stack can be configured via either C++ APIs or by using Mbed configuration system.
4+
5+
### Using Mbed Configuration system
6+
7+
Here are the parameters that can be configured using Mbed configuration system:
8+
9+
```json
10+
{
11+
"name": "lora",
12+
"config": {
13+
"phy": {
14+
"help": "LoRa PHY region. 0 = EU868 (default), 1 = AS923, 2 = AU915, 3 = CN470, 4 = CN779, 5 = EU433, 6 = IN865, 7 = KR920, 8 = US915, 9 = US915_HYBRID",
15+
"value": "0"
16+
},
17+
"over-the-air-activation": {
18+
"help": "When set to 1 the application uses the Over-the-Air activation procedure, default: true",
19+
"value": true
20+
},
21+
"nb-trials": {
22+
"help": "Indicates how many times join can be tried, default: 12",
23+
"value": 12
24+
},
25+
"device-eui": {
26+
"help": "Mote device IEEE EUI",
27+
"value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
28+
},
29+
"application-eui": {
30+
"help": "Application IEEE EUI",
31+
"value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
32+
},
33+
"application-key": {
34+
"help": "AES encryption/decryption cipher application key",
35+
"value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
36+
},
37+
"device-address": {
38+
"help": "Device address on the network",
39+
"value": "0x00000000"
40+
},
41+
"nwkskey": {
42+
"help": "AES encryption/decryption cipher network session key",
43+
"value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
44+
},
45+
"appskey": {
46+
"help": "AES encryption/decryption cipher application session key",
47+
"value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
48+
},
49+
"app-port": {
50+
"help": "LoRaWAN application port, default: 15",
51+
"value": 15
52+
},
53+
"tx-max-size": {
54+
"help": "User application data buffer maximum size, default: 64, MAX: 255",
55+
"value": 64
56+
},
57+
"adr-on": {
58+
"help": "LoRaWAN Adaptive Data Rate, default: 1",
59+
"value": 1
60+
},
61+
"public-network": {
62+
"help": "LoRaWAN will connect to a public network or private network, true = public network",
63+
"value": true
64+
},
65+
"duty-cycle-on": {
66+
"help": "Enables/disables duty cycling. NOTE: Disable only for testing. Mandatory in many regions.",
67+
"value": true
68+
},
69+
"lbt-on": {
70+
"help": "Enables/disables LBT. NOTE: [This feature is not yet integrated].",
71+
"value": false
72+
}
73+
}
74+
}
75+
```
76+
77+
For changing any of these parameters, edit the `mbed_app.json` file in the root of your application. Prefix the parameter name with `lora.`, e.g., `lora.my-parameter: value`.
78+
79+
```json
80+
"target_overrides": {
81+
"*": {
82+
"lora.device-address": "0x12345678",
83+
"lora.over-the-air-activation": true,
84+
"lora.duty-cycle-on": true
85+
}
86+
}
87+
```
88+
89+
### Using APIs from LoRaWANInterface
90+
91+
See API reference [here](https://os.mbed.com/docs/v5.8/reference/lorawan.html).

‎docs/reference/api/connectivity/lorawan/lorawanevents.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
<h2 id="lorawan-events">Mbed LoRaWAN Stack events and callbacks</h2>
2+
3+
Owing to the fact that most of the LoRaWAN devices are simple telemetry drvices, the stack and its operation need to be as simple as possible. That's why the Mbed LoRaWAN stack is event driven.
4+
5+
### Network events
6+
7+
Here is the list of possible events that you can post from the stack to the application:
8+
9+
| Event | Description
10+
| --------------- | ------------- |
11+
| `CONNECTED` | When the connection is complete |
12+
| `DISCONNECTED` | When the protocol is shut down in response to disconnect() |
13+
| `TX_DONE` | When a packet is transmitted |
14+
| `TX_TIMEOUT` | When the stack is unable to send packet in TX window |
15+
| `TX_ERROR` | A general TX error |
16+
| `TX_CRYPTO_ERROR` | If MIC fails, or any other crypto related error |
17+
| `TX_SCHEDULING_ERROR` | When the stack is unable to schedule a packet |
18+
| `TX_TIMEOUT` | When the stack is unable to send a packet in TX window |
19+
| `RX_DONE` | When a packet is received |
20+
| `RX_ERROR` | A general RX error |
21+
22+
The application must attach an event handler to the stack. The `LoRaWANInterface` provides an API to attach various callbacks to the stacks. One such callback is the event handler callback.
23+
24+
### Application callbacks
25+
26+
The Mbed LoRaWAN stack currently maps 3 different callbacks:
27+
28+
| Callback type | Description
29+
| --------------- | ------------- |
30+
| `Event callback` | Mandatory, Direction: from stack to application |
31+
| `Link check response callback` |Optional, Direction: from stack to application |
32+
| `Battery level callabck` | Optional, Direction: from application to stack |
33+
34+
#### Event handler
35+
36+
An example of attaching your event handler to the stack:
37+
38+
```CPP
39+
40+
void your_event_handler(lorawan_event_t event)
41+
{
42+
switch (event) {
43+
case CONNECTED:
44+
//do something
45+
break;
46+
case DISCONNECTED:
47+
break;
48+
....
49+
....
50+
}
51+
}
52+
lorawan_app_callbacks_t callbacks;
53+
54+
callbacks.events = mbed::callback(your_event_handler);
55+
//lorawan is the LoRaWANInterface object
56+
lorawan.add_app_callbacks(&callbacks);
57+
```
58+
59+
#### Link check response handler
60+
61+
Link check request is a MAC command defined by the LoRaWAN Specification. To receive the response of this MAC command, the user should set `link_check_resp` callback.
62+
63+
```CPP
64+
void your_link_check_response(uint8_t demod_margin, uint8_t num_gw)
65+
{
66+
//demod_margin is the demodulation margin
67+
// num_gw represents the number of gateways involved in the path
68+
}
69+
70+
callbacks.link_check_resp = mbed::callback(your_link_check_response);
71+
lorawan.add_app_callbacks(&callbacks);
72+
73+
```
74+
75+
#### Battery level handler
76+
77+
The battery level callback is different from others. The direction of this callback is from the application to the stack. In other words, it provides information to the stack. The application is reponsible for letting the stack know about the current battery level.
78+
79+
```CPP
80+
uint8_t your_battery_level()
81+
{
82+
return battery_level;
83+
}
84+
85+
callbacks.battery_level = mbed::callback(your_battery_level);
86+
lorawan.add_app_callbacks(&callbacks);
87+
```

0 commit comments

Comments
 (0)