Merge pull request #470 from SeppoTakalo/new_engine

Technology/Connectivity refactoring

Author: Amanda Butler

docs.json

@@ -89,7 +89,19 @@
             },
             {
                 "title": "Technology",
+                "intro": {
+                    "type": "markdown",
+                    "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/technology.md"
+                },
                 "sources": [{
+                        "type": "markdown",
+                        "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/connectivity/connectivity.md"
+                    },
+                    {
+                        "type": "markdown",
+                        "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/connectivity/networking.md"
+                    },
+                    {
                         "type": "markdown",
                         "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/mesh/quick_start_intro.md"
                     },
@@ -120,6 +132,10 @@
                     {
                         "type": "markdown",
                         "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/mesh/04_N_networking.md"
+                    },
+                    {
+                        "type": "markdown",
+                        "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/technology/connectivity/intro-to-lora.md"
                     }
                 ]
             },
@@ -370,35 +386,43 @@
                         },
                         "sources": [{
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/EthInterface.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/UDPSocket.md"
                             },
                             {
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/WifiInterface.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/TCPSocket.md"
                             },
                             {
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/CellularInterface.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/TCPServer.md"
                             },
                             {
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/MeshInterface.md"
-                            },
-                            {
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/SocketAddress.md"
+                            }
+                        ]
+                    },
+                    {
+                        "title": "Network Interfaces",
+                        "intro": {
+                            "type": "markdown",
+                            "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/networkinterface.md"
+                        },
+                        "sources": [{
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/UDPSocket.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/EthInterface.md"
                             },
                             {
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/TCPSocket.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/WifiInterface.md"
                             },
                             {
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/TCPServer.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/CellularInterface.md"
                             },
                             {
                                 "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/SocketAddress.md"
+                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/networksocket/MeshInterface.md"
                             }
                         ]
                     },
@@ -436,15 +460,7 @@
                     },
                     {
                         "title": "LoRaWAN",
-                        "intro": {
-                            "type": "markdown",
-                            "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lora.md"
-                        },
                         "sources": [{
-                                "type": "markdown",
-                                "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/intro-to-lora.md"
-                            },
-                            {
                                 "type": "markdown",
                                 "url": "https://github.com/ARMmbed/Handbook/blob/new_engine/docs/reference/api/connectivity/lorawan/lorawanevents.md"
                             },

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

@@ -6,6 +6,54 @@ The CellularBase provides a C++ API for connecting to the internet over a Cellul
 
 Arm Mbed OS provides a [reference implementation of CellularBase](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_easy_cellular_connection_8h_source.html), which has more information.
 
+#### Cellular
+
+The [CellularBase](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_cellular_base_8h_source.html) provides a C++ API for connecting to the internet over a Cellular device.
+
+Arm Mbed OS provides a [reference implementation of CellularBase](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_easy_cellular_connection_8h_source.html).
+
+##### Getting started
+
+1. Choose an [Mbed board that supports cellular](https://os.mbed.com/platforms/?mbed-enabled=15&connectivity=1), such as the [UBLOX-C027](https://os.mbed.com/platforms/u-blox-C027/) or [MTS-DRAGONFLY](https://os.mbed.com/platforms/MTS-Dragonfly/).
+
+1. Clone [`mbed-os-example-cellular`](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/). Follow the instructions in the repository.
+
+    1. Compile the code.
+    1. Flash the board.
+
+   You see output similar to the excerpt below:
+
+```
+mbed-os-example-cellular
+Establishing connection ......
+
+Connection Established.
+TCP: connected with echo.mbedcloudtesting.com server
+TCP: Sent 4 Bytes to echo.mbedcloudtesting.com
+Received from echo server 4 Bytes
+
+
+Success. Exiting
+```
+
+##### Basic working principles
+
+You can use and extend a cellular interface in various different ways. For example,
+
+- Using AT commands to control sockets in an existing IP stack built into the cellular modem.
+
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Cell_AT.png)</span>
+
+- Using a PPP (Point-to-Point Protocol) pipe to pass IP packets between an Mbed OS supported IP stack and cellular modem device.
+
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Cell_PPP.png)</span>
+
+[`mbed-os-example-cellular`](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/) uses [an easy cellular connection](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_easy_cellular_connection_8h_source.html). It depends on the modem whether the application uses PPP or AT mode. We can summarize this particular design as follows:
+
+- It uses an external IP stack, such as LWIP, or on-chip network stacks such as when the modem does not support PPP.
+- The easy cellular connection uses standard 3GPP AT 27.007 AT commands to set up the cellular modem and to register to the network.
+- After registration, the driver opens a PPP pipe using LWIP with the cellular modem and connects to the internet. If AT only mode is in use, then modem-specific AT commands are used for socket data control.
+
 ### CellularBase class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.html)

docs/reference/api/connectivity/networksocket/CellularInterface.md

@@ -2,20 +2,55 @@
 
 <span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_eth_interface.png)<span>EthInterface class hierarchy</span></span>
 
-The EthInterface provides a C++ API for connecting to the internet over Ethernet.
+The `EthInterface` provides a C++ API for connecting to the internet over Ethernet.
+By default, this class does not require any configuration. It is able to pick up the default
+Ethernet driver for the target and select correct network stack.
 
-### EthInterface class reference
-
-[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_eth_interface.html)
 
 ### Usage
 
-To bring up the network interface:
+To statically initialize the driver, create an object without passing any parameters:
+
+```cpp
+EthernetInterface eth;
+```
+
+Then, if the default configuration is enough, bring up the interface:
+
+```cpp
+nsapi_error_t status = eth.connect();
+```
+
+Now, the interface is ready to be used for [network sockets](/docs/development/reference/network-socket.html).
+
+```cpp
+// Open a TCP socket
+TCPSocket socket;
+socket.open(&eth);
+
+// Open a UDP socket
+UDPSocket socket;
+socket.open(&eth);
+```
 
-1. Instantiate the `EthInterface` class.
-1. Call the `connect` function.
-1. Once you connect the EthInterface, you can use it as a
-target for opening [network sockets](/docs/development/reference/network-socket.html).
+### Configuration
+
+For EthernetInterface, there are two possible configurations:
+
+- Use DHCP for network addressing. This is the default.
+- Use statically configured IP addresses.
+
+Refer to the API below for how to set the IP addresses by calling the `set_network()` function.
+
+### Troubleshooting information
+
+Network interface `connect` failure causes:
+1. `NSAPI_ERROR_NO_CONNECTION` indicates that Ethernet link up has failed. Check that the Ethernet connection is working.
+1. `NSAPI_ERROR_DHCP_FAILURE` indicates that acquiring IP address has failed. Check that the IP address configuration service is working.
+
+### EthInterface class reference
+
+[![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_eth_interface.html)
 
 ### EthInterface examples
 

docs/reference/api/connectivity/networksocket/EthInterface.md

@@ -1,13 +1,92 @@
-<h2 id="mesh-api">Mesh</h2>
+<h2 id="mesh-api">6LoWPAN Mesh</h2>
 
 <span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_mesh_interface.png)<span>MeshInterface class hierarchy</span></span>
 
-The Arm Mbed mesh API allows the application to use the IPv6 mesh network topologies through the [nanostack](/docs/development/reference/technology.html#nanostack) networking stack.
+#### 6LoWPAN Mesh Interfaces
+
+The Arm Mbed Mesh API allows the application to use the IPv6 mesh network topologies through the [Nanostack](/docs/v5.7/tutorials/mesh.html#nanostack) networking stack.
+
+Mbed OS provides two types of IPv6 based mesh networks:
+
+- 6LoWPAN_ND, loosely following the Zigbee-IP specification.
+- Thread, following the specification from Thread Group.
+
+Nanostack is the networking stack that provides both of these protocols. For more information on the stack internals, please refer to the [Nanostack documentation](/docs/v5.7/tutorials/mesh.html#nanostack). Application developers use Nanostack through the Mbed Mesh API.
+
+The application can use the `LoWPANNDInterface` or `ThreadInterface` object for connecting to the mesh network. When successfully connected, the application can use the Mbed C++ socket APIs to create a socket to start communication with a remote peer.
+
+##### Supported mesh networking modes
+
+Currently, 6LoWPAN-ND (neighbor discovery) and Thread bootstrap modes are supported.
+
+##### Module configuration
+
+This module supports static configuration via the **Mbed configuration system**. The application needs to create an `mbed_app.json` configuration file if you want to use other than default settings.
+
+An example of the configuration file:
+
+```
+{
+    "target_overrides": {
+        "*": {
+            "target.features_add": ["IPV6"],
+            "mbed-mesh-api.6lowpan-nd-channel": 12,
+            "mbed-mesh-api.6lowpan-nd-channel-mask": "(1<<12)",
+            "mbed-mesh-api.heap-size": 10000
+        }
+    }
+}
+```
+
+**Configurable parameters in the `mbed-mesh-api` section**
+
+| Parameter name  | Value         | Description |
+| --------------- | ------------- | ----------- |
+| `heap-size`       | number [0-0xfffe] | Nanostack's internal heap size |
+
+**Thread related configuration parameters**
+
+| Parameter name  | Value         | Description |
+| --------------- | ------------- | ----------- |
+| `thread-pskd`     | string [6-255 chars] | Human-scaled commissioning credentials. |
+| `thread-use-static-link-config` | boolean | True: Use the below link config, False: Use commissioning, ignore the below link config. |
+| `thread-device-type` | enum from `mesh_device_type_t` | Supported device operating modes:<br> `MESH_DEVICE_TYPE_THREAD_ROUTER`<br> `MESH_DEVICE_TYPE_THREAD_SLEEPY_END_DEVICE`<br> `MESH_DEVICE_TYPE_THREAD_MINIMAL_END_DEVICE` |
+| `thread-config-channel-mask` | number [0-0x07fff800] | Channel mask, 0x07fff800 scans all channels. |
+| `thread-config-channel-page` | number [0]| Channel page, 0 for 2,4 GHz radio. |
+| `thread-config-channel`      | number [11-26] | RF channel to use. |
+| `thread-config-panid`        | number [0-0xFFFF] | Network identifier. |
+| `thread-config-network-name` | string [1-16] |
+| `thread-config-commissioning-dataset-timestamp` | [0-0xFFFFFFFFFFFFFFFF] | [48 bit timestamp seconds]-[15 bit timestamp ticks]-[U bit] |
+| `thread-config-extended-panid` | byte array [8] | Extended PAN ID. |
+| `thread-master-key`      | byte array [16]| Network master key. |
+| `thread-config-ml-prefix` | byte array [8] | Mesh local prefix. |
+| `thread-config-pskc`      | byte array [16] | Pre-Shared Key for the Commissioner. |
+| `thread-security-policy` | number [0-0xFF] | Commissioning security policy bits. |
+
+**6LoWPAN related configuration parameters**
+
+| Parameter name  | Type     | Description |
+| --------------- | ---------| ----------- |
+| `6lowpan-nd-channel-mask`    | number [0-0x07fff800] | Channel mask, bit-mask of channels to use. |
+| `6lowpan-nd-channel-page`   | number [0, 2] | 0 for 2,4 GHz and 2 for sub-GHz radios. |
+| `6lowpan-nd-channel`        | number [0-26] | RF channel to use when `channel_mask` is not defined. |
+| `6lowpan-nd-panid-filter` | number [0-0xffff] | Beacon PAN ID filter, 0xffff means no filtering. |
+| `6lowpan-nd-security-mode` | "NONE" or "PSK" | To use either no security, or Pre shared network key. |
+| `6lowpan-nd-psk-key-id` | number | PSK key ID when PSK is enabled. |
+| `6lowpan-nd-psk-key` | byte array [16] | Pre-Shared network key. |
+| `6lowpan-nd-sec-level` | number [1-7] | Network security level. Use default `5`. |
+| `6lowpan-nd-device-type` | "NET_6LOWPAN_ROUTER" or "NET_6LOWPAN_HOST" | Device mode. Router is routing packets from other device, creating a mesh network. |
+
+**Network connection states**
+
+After the initialization, the network state is `MESH_DISCONNECTED`. After a successful connection, the state changes to `MESH_CONNECTED` and when disconnected from the network the state is changed back to `MESH_DISCONNECTED`.
+
+In case of connection errors, the state is changed to some of the connection error states. In an error state, there is no need to make a `disconnect` request and the application is allowed to attempt connecting again.
+
+##### Getting started
+
+See the example application [mbed-os-example-mesh-minimal](https://github.com/ARMmbed/mbed-os-example-mesh-minimal) for usage.
 
-**Tips:**
-- The mesh API supports 6LoWPAN-ND (neighbor discovery) and Thread bootstrap modes.
-- The applications do not use this module directly. The applications use `LoWPANNDInterface`, `ThreadInterface` or `NanostackEthernetInterface` directly.
-- When using an Ethernet interface, there are no configuration options available. It is using the dynamic mode to learn the IPv6 prefix from the network.
 
 ### Mesh class reference