ARMmbed · AnotherButler · Mar 12, 2018 · Feb 16, 2018 · Feb 28, 2018 · Mar 1, 2018
diff --git a/docs.json b/docs.json
@@ -378,6 +378,30 @@
                             }
                         ]
                     },
+                    {
+                        "title": "LoRaWAN",
+                        "intro": {
+                            "type": "markdown",
+                            "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawan.md"
+                        },
+                        "sources": [{
+                                "type": "markdown",
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawanconfig.md"
+                            },
+                            {
+                                "type": "markdown",
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawanevents.md"
+                            },
+                            {
+                                "type": "markdown",
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/errorcodes.md"
+                            },
+                            {
+                                "type": "markdown",
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/loraradio.md"
+                            }
+                        ]
+                    },
                     {
                         "title": "Security",
                         "intro": {

diff --git a/docs/reference/api/api.md b/docs/reference/api/api.md
@@ -6,6 +6,7 @@ The [APIs](/docs/v5.7/introduction/glossary.html) in this document are organized
 - [Drivers](/docs/v5.7/reference/drivers.html): analog and digital input and outputs and digital interfaces.
 - [RTOS](/docs/v5.7/reference/rtos.html): handling tasks and events in Mbed OS.
 - [Network Socket](/docs/v5.7/reference/network-socket.html): network sockets, Ethernet, Wi-Fi, cellular and mesh networking.
+- [LoRaWAN](/docs/v5.8/reference/lorawan.html): low power wide area network.
 - [Bluetooth](/docs/v5.7/reference/bluetooth.html): bluetooth low energy.
 - [Security](/docs/v5.7/reference/security.html): working with Arm Mbed uVisor and Arm Mbed TLS in the context of Mbed OS.
 - [Storage](/docs/v5.7/reference/storage.html): working with the file system.

diff --git a/docs/reference/api/connectivity/lorawan/errorcodes.md b/docs/reference/api/connectivity/lorawan/errorcodes.md
@@ -0,0 +1,26 @@
+<h2 id="lorawan-error-codes">Mbed LoRaWAN Stack error codes</h2>
+
+All operations on `LoRaWANInterface` return an error code `lorawan_status_t` that reflects success or failure of the operation.
+
+Here  is the list of error codes and their description.
+
+| Error code    | Value |Description |
+| --------------- | ------------- | ----------|
+| `LORAWAN_STATUS_OK`| 0 | Service done successfully |
+| `LORAWAN_STATUS_BUSY`| -1000|  Stack busy |
+|`LORAWAN_STATUS_WOULD_BLOCK`| -1001 | Stack cannot send at the moment or have nothing to read|
+| `LORAWAN_STATUS_SERVICE_UNKNOWN`| -1002 | Unknown service request |
+| `LORAWAN_STATUS_PARAMETER_INVALID`| -1003 | Invalid parameter  |
+| `LORAWAN_STATUS_FREQUENCY_INVALID`| -1004| Invalid frequency  |
+| `LORAWAN_STATUS_DATARATE_INVALID` | -1005| Invalid frequency and datarate  |
+| `LORAWAN_STATUS_FREQ_AND_DR_INVALID`| -1006| When stack was unable to send packet in TX window  |
+|`LORAWAN_STATUS_NO_NETWORK_JOINED`| -1009 | Device is not part of a network yet (Applicable only for OTAA) |
+|`LORAWAN_STATUS_LENGTH_ERROR`|- 1010 | Payload lenght error |
+| `LORAWAN_STATUS_DEVICE_OFF`| -1011 | The device is off, i.e., disconnected state |
+| `LORAWAN_STATUS_NOT_INITIALIZED`| -1012| Stack not initialized  |
+| `LORAWAN_STATUS_UNSUPPORTED`| -1013|Unsupported service |
+| `LORAWAN_STATUS_CRYPTO_FAIL`| -1014| Crypto failure  |
+|`LORAWAN_STATUS_PORT_INVALID`| -1015 | Invalid port |
+|`LORAWAN_STATUS_CONNECT_IN_PROGRESS`|- 1016 | Connection in progress (application should wait for CONNECT event) |
+|`LORAWAN_STATUS_NO_ACTIVE_SESSIONS`| -1017 | No active session in progress |
+|`LORAWAN_STATUS_IDLE`|- 1018 | Stack idle at the moment|
diff --git a/docs/reference/api/connectivity/lorawan/loraradio.md b/docs/reference/api/connectivity/lorawan/loraradio.md
@@ -0,0 +1,12 @@
+<h2 id="loraradio-api">LoRaRadio</h2>
+
+`LoRaRadio` is a pure virtual class that defines APIs for a LoRa radio driver.
+
+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.
+
+### LoRaRadio class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_radio.html)
+
+### LoRaRadio example
+
diff --git a/docs/reference/api/connectivity/lorawan/lorawan.md b/docs/reference/api/connectivity/lorawan/lorawan.md
@@ -0,0 +1,70 @@
+<h2 id="lorawan-api">LoRaWAN</h2>
+
+LoRaWAN is a technology designed for low-power battery powered devices. These devices operate in an unlicensed spectrum, creating high desnity wide-area networks.
+
+Arm Mbed OS provides a native network stack for LoRaWAN, which can run on any Mbed Enabled device with a LoRa radio onboard. 
+
+The [LoRaWANInterface](https://github.com/ARMmbed/mbed-os/blob/feature-lorawan/features/lorawan/LoRaWANInterface.h) provides a C++ API for connecting to the internet over a LoRa network.
+
+## LoRaWANInterface class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/v5.8/mbed-os-api-doxy/class_l_o_r_a_w_a_n_interface.html)
+
+## Usage
+
+To bring up the Mbed LoRaWAN stack, consider the following progression: 
+
+1) An [EventQueue](https://os.mbed.com/docs/v5.8/reference/eventqueue.html) object. 
+
+```cpp
+// construct an event queue 
+EventQueue ev_queue(NUM_EVENTS * EVENTS_EVENT_SIZE);
+```
+2) A [LoRaRadio](https://os.mbed.com/docs/v5.8/reference/loraradio.html) object
+
+```CPP
+// construct a LoRadio object
+SX1272_LoRaRadio radio(PIN_NAMES ... );
+```
+
+3) Instantiate `LoRaWANInterface` and pass `LoRaRadio` object
+
+```CPP
+LoRaWANInterface lorawan(radio) ;
+``` 
+
+4) Initialize mac layer and pass `EventQueue` object
+
+```CPP
+lorawan.initialize(&ev_queue);
+```
+
+5) Setup the event callback.
+
+```cpp
+lorawan_app_callbacks_t callbacks
+callbacks.events = mbed::callback(YOUR_EVENT_HANDLER);
+lorawan.add_app_callbacks(&callbacks);
+```
+
+6) Add network credentials (security keys) and any configurations.
+
+```CPP
+lorawan_connect_t connection;
+
+connection.connect_type = LORAWAN_CONNECTION_OTAA;
+connection.connection_u.otaa.app_eui = YOUR_APP_EUI_KEY;
+connection.connection_u.otaa.dev_eui = YOUR_DEV_EUI_KEY;
+connection.connection_u.otaa.app_key = YOUR_APP_KEY;
+connection.connection_u.otaa.nb_trials = MBED_CONF_LORA_NB_TRIALS;
+
+lorawan.connect(connection);
+``` 
+
+### LoRaWAN example
+
+Please visit our [github example repository](https://github.com/ARMmbed/mbed-os-example-lorawan) and follow the instructions in the `README.md`.
+
+### Related content
+
+- End-to-end [LoRa on Arm Mbed tutorial](https://docs.mbed.com/docs/lora-with-mbed/en/latest/).
diff --git a/docs/reference/api/connectivity/lorawan/lorawanconfig.md b/docs/reference/api/connectivity/lorawan/lorawanconfig.md
@@ -0,0 +1,91 @@
+<h2 id="lorawan-configuration">Configuring Mbed LoRaWAN Stack</h2>
+
+Various parameters for Mbed LoRaWAN stack can be configured via either C++ APIs or by using Mbed configuration system. 
+
+### Using Mbed Configuration system
+
+Here are the parameters that can be configured using Mbed configuration system:
+
+```json
+{
+    "name": "lora",
+    "config": {
+        "phy": {
+            "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",
+            "value": "0"
+        },
+        "over-the-air-activation": {
+            "help": "When set to 1 the application uses the Over-the-Air activation procedure, default: true",
+            "value": true
+        },
+        "nb-trials": {
+            "help": "Indicates how many times join can be tried, default: 12",
+            "value": 12
+        },
+        "device-eui": {
+            "help": "Mote device IEEE EUI",
+            "value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
+        },
+        "application-eui": {
+            "help": "Application IEEE EUI",
+            "value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
+        },
+        "application-key": {
+            "help": "AES encryption/decryption cipher application key",
+            "value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
+        },
+        "device-address": {
+            "help": "Device address on the network",
+            "value": "0x00000000"
+        },
+        "nwkskey": {
+            "help": "AES encryption/decryption cipher network session key",
+            "value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
+        },
+        "appskey": {
+            "help": "AES encryption/decryption cipher application session key",
+            "value": "{0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}"
+        },
+        "app-port": {
+            "help": "LoRaWAN application port, default: 15",
+            "value": 15
+        },
+        "tx-max-size": {
+            "help": "User application data buffer maximum size, default: 64, MAX: 255",
+            "value": 64
+        },
+        "adr-on": {
+            "help": "LoRaWAN Adaptive Data Rate, default: 1",
+            "value": 1
+        },
+        "public-network": {
+            "help": "LoRaWAN will connect to a public network or private network, true = public network",
+            "value": true
+        },
+        "duty-cycle-on": {
+            "help": "Enables/disables duty cycling. NOTE: Disable only for testing. Mandatory in many regions.",
+            "value": true
+        },
+        "lbt-on": {
+            "help": "Enables/disables LBT. NOTE: [This feature is not yet integrated].",
+            "value": false
+        }
+    }
+}
+```
+
+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`.
+
+```json
+"target_overrides": {
+    "*": {
+        "lora.device-address":  "0x12345678",
+        "lora.over-the-air-activation": true,
+        "lora.duty-cycle-on": true
+    }
+}
+```
+
+### Using APIs from LoRaWANInterface
+
+See API reference [here](https://os.mbed.com/docs/v5.8/reference/lorawan.html).
diff --git a/docs/reference/api/connectivity/lorawan/lorawanevents.md b/docs/reference/api/connectivity/lorawan/lorawanevents.md
@@ -0,0 +1,87 @@
+<h2 id="lorawan-events">Mbed LoRaWAN Stack events and callbacks</h2>
+
+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.
+
+### Network events
+
+Here is the list of possible events that you can post from the stack to the application:
+
+| Event    | Description 
+| --------------- | ------------- | 
+| `CONNECTED` | When the connection is complete |
+| `DISCONNECTED` | When the protocol is shut down in response to disconnect() |
+| `TX_DONE` | When a packet is transmitted |
+| `TX_TIMEOUT` | When the stack is unable to send packet in TX window |
+| `TX_ERROR` | A general TX error |
+| `TX_CRYPTO_ERROR` | If MIC fails, or any other crypto related error |
+| `TX_SCHEDULING_ERROR` | When the stack is unable to schedule a packet |
+| `TX_TIMEOUT` | When the stack is unable to send a packet in TX window  |
+| `RX_DONE` | When a packet is received |
+| `RX_ERROR` | A general RX error |
+
+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. 
+
+### Application callbacks
+
+The Mbed LoRaWAN stack currently maps 3 different callbacks:
+
+| Callback type   | Description 
+| --------------- | ------------- | 
+| `Event callback` | Mandatory, Direction: from stack to application |
+| `Link check response callback` |Optional, Direction: from stack to application |
+| `Battery level callabck` | Optional, Direction: from application to stack |
+
+#### Event handler
+
+An example of attaching your event handler to the stack:
+
+```CPP
+
+void your_event_handler(lorawan_event_t event) 
+{
+    switch (event) {
+        case CONNECTED:
+        //do something
+            break;
+        case DISCONNECTED:
+            break;
+	....
+	....
+    }
+}
+lorawan_app_callbacks_t callbacks;
+
+callbacks.events = mbed::callback(your_event_handler);
+//lorawan is the LoRaWANInterface object
+lorawan.add_app_callbacks(&callbacks);
+```
+
+#### Link check response handler
+
+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.  
+
+```CPP
+void your_link_check_response(uint8_t demod_margin, uint8_t num_gw) 
+{
+	//demod_margin is the demodulation margin 
+	// num_gw represents the number of gateways involved in the path
+}
+
+callbacks.link_check_resp = mbed::callback(your_link_check_response);
+lorawan.add_app_callbacks(&callbacks);
+
+```
+
+#### Battery level handler
+
+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.
+
+```CPP
+uint8_t your_battery_level() 
+{
+	return battery_level;
+}
+
+callbacks.battery_level = mbed::callback(your_battery_level);
+lorawan.add_app_callbacks(&callbacks);
+```