ARMmbed · AnotherButler · Feb 20, 2019 · Jan 10, 2019
diff --git a/docs/api/networkinterfaces/CellularInterface.md b/docs/api/networkinterfaces/CellularInterface.md
@@ -1,10 +1,8 @@
-<h2 id="cellular-api">Cellular</h2>
+<h2 id="cellular-api">Cellular API</h2>
 
-<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.png)<span>CellularBase class hierarchy</span></span>
+<span class="images">![](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.png)<span>CellularInterface class hierarchy</span></span>
 
-The [CellularBase](https://os.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.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h_source.html), which has more information.
+The [CellularInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.html) class provides a C++ API for connecting to the internet over a Cellular device.
 
 ##### Getting started
 
@@ -48,15 +46,15 @@ You can use and extend a cellular interface in various different ways. For examp
 - 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
+### CellularInterface class reference
 
-[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.html)
+[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.html)
 
 ### Usage
 
 To bring up the network interface:
 
-1. Instantiate an implementation of the CellularBase class.
+1. Instantiate an implementation of the CellularInterface class.
 1. Call the `connect(pincode, apn)` function with a PIN code for your SIM card and an APN for your network.
 1. Once connected, you can use Mbed OS [network sockets](network-socket.html) as usual.
 
@@ -69,6 +67,6 @@ This example establishes connection with the cellular network using Mbed OS Cell
 ### Related content
 
 - [Network socket](network-socket.html) API reference overview.
-- [Cellular architecture](../reference/cellular.html).
+- [Cellular overview](../reference/cellular.html) describes cellular architecture and its usage in more detail.
 - [Cellular TCP sockets example](../tutorials/cellular-tcp-sockets.html).
 - [Cellular configuration documentation](../reference/configuration-connectivity.html).
diff --git a/docs/api/networkinterfaces/networkinterface.md b/docs/api/networkinterfaces/networkinterface.md
@@ -79,7 +79,7 @@ Applications may also ask for a specific type of connection, as the following ta
 |`*WiFiInterface::get_default_instance()`| Wi-Fi interface | Requires security parameters (mode, SSID, password). |
 |`*EthInterface::get_default_instance()` | Wired Ethernet interface, not Wi-Fi | none |
 |`*MeshInterface::get_default_instance()` | Returns either `LoWPANNDInterface` or `ThreadInterface`, depending on which is set to default | Target provides a driver or macro `DEVICE_802_15_4_PHY` is enabled. |
-| `*CellularBase::get_default_instance()` | Return cellular connectivity | Requires network parameters (pin, APN, username, password). |
+| `*CellularInterface::get_default_instance()` | Return cellular connectivity | Requires network parameters (pin, APN, username, password). |
 | `*NetworkInterface::get_default_instance()` | One of the above, depending on `target.network-default-interface-type`. |  |
 
 Note that the calls for a specific interface type do not preconfigure credentials such as SSID because an interface-type-specific application is expected to configure these in code. `NULL` is returned if no interface of that type is available.

diff --git a/docs/porting/connectivity/CellularInterface.md b/docs/porting/connectivity/CellularInterface.md
@@ -1,8 +1,8 @@
-## Cellular module porting
+## Cellular device porting
 
-This document provides guidelines how to make a cellular modem adaptation for Mbed OS. Please see [Cellular API usage](../apis/cellular-api.html) about how to use cellular modules from an application point of view.
+This document provides guidelines how to make a cellular device adaptation for Mbed OS.
 
-### Adding modem target support
+### Adding cellular on an Mbed OS target
 
 For new targets, you may need to modify [targets.json](../reference/adding-and-configuring-targets.html), which defines all the target platforms that Mbed OS supports. If Mbed OS supports your specific target, an entry for your target is in this file. To tell the Mbed OS build configuration that your target board has an onboard cellular module, you need to define `modem_is_on_board` and `modem_data_connection_type`.
 
@@ -56,9 +56,9 @@ typedef enum {
 
 ```
 
-### Adding a new cellular target
+### Adding a new cellular device
 
-You need to specify in [CellularTargets.h](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_targets_8h_source.html) the `<manufacturer-module>` that is mounted on your board.
+You need to specify in [CellularTargets.h](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_targets_8h_source.html) the `<manufacturer-module>` mounted on your board.
 
 ```target
 

diff --git a/docs/porting/connectivity/NetworkStack.md b/docs/porting/connectivity/NetworkStack.md
@@ -14,7 +14,7 @@ Please refer to the [IP networking architecture](../reference/ip-networking.html
 
 #### NetworkInterface Class
 
-The current NetworkInterface subclasses are [CellularInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.html), [EthernetInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_eth_interface.html), [MeshInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_mesh_interface.html) and [WiFiInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_wi_fi_interface.html). Your communication interface is a subclass of one of these, as well as the NetworkStack. For example, the [ESP8266Interface](https://github.com/ARMmbed/esp8266-driver) inheritance structure looks like this:
+The current NetworkInterface subclasses are [CellularInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.html), [EthernetInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_eth_interface.html), [MeshInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_mesh_interface.html) and [WiFiInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_wi_fi_interface.html). Your communication interface is a subclass of one of these, as well as the NetworkStack. For example, the [ESP8266Interface](https://github.com/ARMmbed/esp8266-driver) inheritance structure looks like this:
 
 <span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/esp-class.png)<span>Class</span></span>
 

diff --git a/docs/porting/connectivity/connectivity.md b/docs/porting/connectivity/connectivity.md
@@ -12,7 +12,7 @@ The **DeviceInterface** should also inherit one of the following (unless it is a
 
 - [EthInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_eth_interface.html).
 - [WiFiInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_wi_fi_interface.html).
-- [CellularInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.html).
+- [CellularInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_interface.html).
 - [MeshInterface](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_mesh_interface.html).
 
 The **NetworkInterface** implementation provides the following methods:

diff --git a/docs/reference/configuration/Connectivity.md b/docs/reference/configuration/Connectivity.md
@@ -198,11 +198,11 @@ Boards that provide only Ethernet connectivity do not require any configuration.
 
 Select the default interface type by using one of the following `target.network-default-interface-type` parameters:
 
-| `target.network-default-interface-type` | Required configuration |
+| `target.network-default-interface-type` | Configuration parameters |
 |-----------------------------------------|------------------------|
 | `ETHERNET` | nothing |
 | `WIFI`     | `nsapi.default-wifi-security`, `nsapi.default-wifi-ssid` and `nsapi.default-wifi-password` |
-| `CELLULAR` | `nsapi.default-cellular-apn`, `nsapi.default-cellular-username` and `nsapi.default-cellular-password` |
+| `CELLULAR` | `nsapi.default-cellular-sim-pin`, `nsapi.default-cellular-apn`, `nsapi.default-cellular-username` and `nsapi.default-cellular-password`, `nsapi.default-cellular-plmn` |
 | `MESH`     | `nsapi.default-mesh-type` |
 
 ```
@@ -223,9 +223,6 @@ Name: nsapi.default-wifi-ssid
 Name: nsapi.default-wifi-password
     Defined by: library:nsapi
     No value set
-Name: nsapi.default-cellular-plmn
-	Defined by: library:nsapi
-    No value set
 Name: nsapi.default-cellular-sim-pin
 	Defined by: library:nsapi
     No value set
@@ -238,6 +235,9 @@ Name: nsapi.default-cellular-password
 Name: nsapi.default-cellular-username
     Defined by: library:nsapi
     No value set
+Name: nsapi.default-cellular-plmn
+    Defined by: library:nsapi
+    No value set
 Name: nsapi.default-mesh-type
     Defined by: library:nsapi
     Macro name: MBED_CONF_NSAPI_DEFAULT_MESH_TYPE

diff --git a/docs/reference/technology/connectivity/cellular.md b/docs/reference/technology/connectivity/cellular.md
@@ -1,4 +1,4 @@
-## Cellular
+## Cellular networking
 
 Mbed OS cellular provides your IoT application with access to world-wide operator-maintained cellular networks, both IP and non-IP, as Figure 1 illustrates. Mbed OS cellular implementation is based on international 3GPP and OMA standards, and it has been verified to work with all cellular networks such as NB-IoT, CAT-M1, 4G LTE, 3G WCDMA and GPRS.
 
@@ -12,49 +12,30 @@ Key features of the Mbed OS cellular APIs include:
 
 - Compatible with 3GPP TS 27.007 and 27.005.
 - Implements core functionality for OMA Lightweight M2M Client.
-- Hosted cellular modules on Mbed Enabled boards.
+- Supports many Mbed Enabled cellular boards.
 
 3GPP TS 27.007 and 27.005 are standards to provide consistent cellular network data connectivity and SMS over an AT command interface for cellular devices, regardless of the underlying cellular network.
 
 OMA Lightweight M2M is a protocol from the Open Mobile Alliance for IoT device management. The Mbed OS cellular API provides core functionality to implement the LWM2M Client. For more information, please see _OMA LightweightM2M_ and _OMA LWM2M Object Connectivity Management_ at [OMA Specifications](http://openmobilealliance.org/wp/index.html).
 
-Mbed OS already supports several Mbed Enabled boards with on-board cellular hosted modules. Because Mbed OS is an open source platform, developers can enable support for new cellular boards with our adaptation framework. Please see our [cellular porting guide](../porting/porting-connectivity.html#cellularinterface) for more information.
+Many Mbed Enabled boards already support cellular connectivity. Because Mbed OS is an open source platform, developers can enable support for new cellular boards with our adaptation framework. Please see our [cellular porting guide](../porting/cellular-module-porting.html) for more information.
 
 ### Quick start
 
-There are two phases to Mbed OS connectivity, in general:
+To use cellular data connection:
 
 1. Connect to a network.
 1. Open a socket to send or receive data.
 
-With cellular, the easiest way to connect your application to the internet over a cellular network is to use the `CellularContext` class and `get_default_instance`. It encapsulates most of the complexity of connecting to the cellular network and also reports any changes in connection status to your application. When connected to a cellular network, you can use Mbed OS network sockets as usual, as Figure 2 illustrates.
+With cellular, the easiest way to connect your application to the internet over a cellular network is to use the `CellularContext` class and `get_default_instance`. It encapsulates most of the complexity of connecting to the cellular network and also reports any changes in connection status to your application. When connected to a cellular network, you can use Mbed OS network sockets as usual.
 
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/api-cellular-quick-start.png)<span>Figure 2. Connect to cellular network and open a socket</span></span>
+A network interface instantiated directly or using calls such as `CellularInterface::get_default_instance()` or `CellularContext::get_default_instance()` is initially unconfigured. You can call `NetworkInterface::set_default_parameters()` to set the default parameters that would have been set if the interface had been requested using `NetworkInterface::get_default_instance()`.
 
 If you want to see code, you can go to our [cellular example](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/).
 
-### Cellular hosted module
+### Cellular device selection
 
-If you are using an Mbed OS target that has a supported on-board (mounted) cellular hosted module then cellular framework decides the correct cellular hosted module at compile-time. You can run `mbedls` to find out your current Mbed OS target and then match that to the supported targets in the `CellularTargets.h` file, where a CELLULAR_DEVICE macro is defined based on the Mbed OS target definition and can be used as a C++ class type to instantiate a driver class (inherited from `CellularDevice.h`).
-
-You can browse `CellularTargets.h` file to find out if the hosted module you are using is already supported. In case the hosted module is not yet supported, you could adapt some existing driver for your needs.
-
-Some Mbed OS target boards may have several different kind of cellular hosted modules on-board. In that case, the cellular hosted module driver detects at runtime the actual hosted module that is currently mounted and adapts to that specific cellular hosted module during runtime.
-
-If you use an Mbed OS target and a separate cellular hosted module via a serial line (UART), you need to configure in your `mbed_app.json` configuration file which cellular hosted module to use and which UART pins are connected between the Mbed OS target board and the cellular hosted module:
-
-    {
-        "macros":
-        [
-            "CELLULAR_DEVICE=<manufacturer-module>",
-            "MDMRXD=<rx-pin-name>",
-            "MDMTXD=<tx-pin-name>",
-            "MDMRTS=<rts-pin-name>",
-            "MDMCTS=<cts-pin-name>"
-        ]
-    }
-
-You need to change the pin names above to actual pins, such as D0 and D1, according to your Mbed target. You may also need to define MDMRTS and MDMCTS pins if you have RTS and CTS connected on UART. If RTC and CTS are not connected on UART, then define MDMRTS and MDMCTS as `NC`.
+If an Mbed OS target board has an on-board cellular device then the cellular framework uses that by default when calling `get_default_instance()`. The default cellular device instance can be overridden in the cellular driver `mbed_lib.json` files or an application can override  `NetworkInterface::get_default_instance()`.
 
 ### Cellular APIs
 
@@ -64,14 +45,12 @@ Cellular APIs are structured based on main functionalities:
 
 - `CellularContext` is the main interface for the application. You can use it to connect to the operator's Access Point Name (APN).
 - `CellularNetwork` for cellular network features, such as registering and attaching to a network.
-- `CellularPower` for cellular hosted module power control, such as enabling power save.
-- `CellularInformation` to read the cellular hosted module type and firmware version.
-- `CellularSIM` to enter the PIN code and other SIM management functions.
+- `CellularInformation` to read the cellular device and SIM information.
 - `CellularSMS` to read and write SMS messages.
 
 You can instantiate the CellularContext class with `CellularContext::get_default_instance()`, which opens `CellularDevice` and, through the device, opens `CellularContext`. Opening `CellularContext` through `get_default_instance` uses values from `mbed_app.json`.
 These values are not defined by default, and you must override them in `mbed_app.json` if you need them:
-
+```
 "target_overrides": {
         "*": {
             "nsapi.default-cellular-plmn": "\"12346\"",
@@ -81,25 +60,21 @@ These values are not defined by default, and you must override them in `mbed_app
             "nsapi.default-cellular-password": 0
         }
     }
-
-The CellularDevice class encloses cellular APIs. Therefore, to use any cellular API, you need to get CellularDevice first. You can then use CellularDevice to open and close cellular APIs, as Figure 3 illustrates.
-
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/api-cellular-device.png)<span>Figure 3. Use CellularDevice to open Cellular APIs</span></span>
+```
+The CellularDevice class encloses cellular APIs. Therefore, to use a cellular API, you need to get CellularDevice first. You can then use CellularDevice to open and close cellular APIs.
 
 When an application has opened a cellular API, you can use it to request API methods. For example:
-
+```
     CellularContext *ctx  = cellularDevice->create_context();
     if (ctx) {
-		if (ctx-connect() == NSAPI_ERROR_OK) {
-			printf("Local IP address is %s", ctx->get_ip_address());
-		}
+    		if (ctx->connect() == NSAPI_ERROR_OK) {
+      			printf("Local IP address is %s", ctx->get_ip_address());
+    		}
     }
-
+```
 ### UDP and TCP sockets
 
-If you want to use UDP or TCP sockets, you need an IP stack. Mbed OS cellular has an option to use either the LWIP stack, which is part of Mbed OS, or to use the IP stack on the cellular hosted module. Figure 4 illustrates IP stack deployment.
-
-<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/api-cellular-ip-stack.png)<span>Figure 4. IP stack can be used in PPP or AT mode</span></span>
+If you want to use UDP or TCP sockets, you need an IP stack. Mbed OS cellular has an option to use either the LWIP stack (PPP mode), which is part of Mbed OS, or to use the IP stack on the cellular device (AT mode).
 
 #### PPP mode with the LWIP stack on Mbed OS
 
@@ -128,7 +103,7 @@ The AT mode is enabled when the PPP mode is not enabled:
 
 Consider the following points when selecting PPP or AT mode:
 
-- Your cellular hosted module may support only AT or PPP mode.
+- A cellular device may support only AT or PPP mode.
 - PPP mode supports both UDP and TCP sockets.
 - PPP mode does not allow AT commands after connecting to data mode.
 - PPP mode uses the LWIP stack, which uses memory from your Mbed OS application.
@@ -137,11 +112,11 @@ Consider the following points when selecting PPP or AT mode:
 
 ### Optimize for power consumption
 
-The `CellularPower` class has methods to optimize power saving. The `set_power_level()` offers flexibility to control the reception and transmission power levels. In addition, 3GPP has specified advanced power optimizations that are useful for celluar IoT devices: Power Save Mode (PSM) and extended Discontinuous Reception (eDRX).
+The cellular API has methods to optimize power saving: Power Save Mode (PSM) and extended Discontinuous Reception (eDRX).
 
 #### PSM - Power Save Mode
 
-    opt_power_save_mode(int periodic_time, int active_time)
+    set_power_save_mode(int periodic_time, int active_time)
 
 The new 4G modems implementing specifications release 13 and later include PSM. PSM allows the application to tell the modem and network that it does not expect any data in a given time interval, the `periodic_time`. The modem and network can optimize the sleep state and network resource reservations based on this information. During the PSM time, nothing can contact the device from the network side. The application can still send at any time. PSM time can be hours, days or weeks.
 
@@ -153,7 +128,7 @@ PSM configuration is negotiated with the network, and the actual PSM time that n
 
 #### eDRX - extended Discontinuous Reception
 
-    opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value)
+    set_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value)
 
 eDRX tells how long the device sleeps in continuous connection. The device needs to be able to receive data, but it can tell the network that it checks for incoming messages, for example only every 200 seconds. It can receive messages but only at the given times to allow battery saving sleep periods. These time values are greatly extended compared to normal 4G data transmission – hence the name.