Cellular: update handbook to 5.11

docs/api/networkinterfaces/CellularInterface.md

@@ -4,13 +4,13 @@
 
 The CellularBase provides a C++ API for connecting to the internet over a Cellular device.
 
-Arm Mbed OS provides a [reference implementation of CellularBase](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_easy_cellular_connection_8h_source.html), which has more information.
+Arm Mbed OS provides a [reference implementation of CellularBase](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h_source.html), which has more information.
 
 #### Cellular
 
 The [CellularBase](http://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](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_easy_cellular_connection_8h_source.html).
+Arm Mbed OS provides a [reference implementation of CellularBase](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h_source.html).
 
 ##### Getting started
 
@@ -48,7 +48,7 @@ You can use and extend a cellular interface in various different ways. For examp
 
 <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](http://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:
+[`mbed-os-example-cellular`](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/) uses [a class CellularContext](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_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.

docs/porting/connectivity/CellularInterface.md

@@ -86,7 +86,7 @@ If your cellular module has an IP stack, you need to implement the AT commands t
 
 For example implementations of a socket adaptation, look in `features/cellular/framework/targets`.
 
-When the modem has AT and/or PPP mode support in place and the application developer has selected which mode to use, it's up to the cellular framework to instantiate the correct classes. For example, [mbed-os-example-cellular](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/) instantiates [EasyCellularConnection class](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_easy_cellular_connection_8h_source.html), which in turn instantiates [CellularConnectionFSM class](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_cellular_connection_f_s_m_8h_source.html). CellularConnectionFSM instantiates classes implementing [the AT command layer](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_a_t___cellular_device_8h_source.html) between the modem and the Mbed OS CPU. If an application developer has configured PPP mode in `mbed_app.json` then [AT_CellularNetwork](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_a_t___cellular_network_8h_source.html) connects to a cellular network and calls `nsapi_ppp_connect()` to start the data call through the PPP pipe using LWIP sockets.
+When the modem has AT and/or PPP mode support in place and the application developer has selected which mode to use, it's up to the cellular framework to instantiate the correct classes. For example, [mbed-os-example-cellular](https://os.mbed.com/teams/mbed-os-examples/code/mbed-os-example-cellular/) instantiates [CellularContext class](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h_source.html). CellularContext instantiates classes implementing [the AT command layer](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_a_t___cellular_device_8h_source.html) between the modem and the Mbed OS CPU. If an application developer has configured PPP mode in `mbed_app.json` then [AT_CellularContext](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/_a_t___cellular_context_8h_source.html) connects to a cellular network and calls `nsapi_ppp_connect()` to start the data call through the PPP pipe using LWIP sockets.
 
 ### Testing
 

docs/reference/configuration/Connectivity.md

@@ -191,7 +191,7 @@ Example application code can be as simple as:
     if (!net) {
         // There is no default...
     }
-    net->connet();
+    net->connect();
 ```
 
 Boards that provide only Ethernet connectivity do not require any configuration. The default settings are sufficient. Boards that provide other connectivity options require selecting the default interface type and providing settings for it.
@@ -223,6 +223,12 @@ 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
 Name: nsapi.default-cellular-apn
     Defined by: library:nsapi
     No value set

docs/reference/technology/connectivity/cellular.md

@@ -27,7 +27,7 @@ There are two phases to Mbed OS connectivity, in general:
 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 `CellularConnectionFSM` class. 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, as Figure 2 illustrates.
 
 <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>
 
@@ -48,33 +48,50 @@ If you use an Mbed OS target and a separate cellular hosted module via a serial
         [
             "CELLULAR_DEVICE=<manufacturer-module>",
             "MDMRXD=<rx-pin-name>",
-            "MDMTXD=<tx-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/CTS connected on UART.
+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/CTS connected on UART. If RTC/CTS are not connected on UART then define MDMRTS and MDMCTS to 'NC'.
 
 ### Cellular APIs
 
 As an application developer, you should use and refer only to classes located under API folder. All the other classes have implementation details which are expected to change frequently.
 
 Cellular APIs are structured based on main functionalities:
 
-- `CellularNetwork` for cellular network features, such as preferred operator and APN.
+- `CellularContext` is the main interface for application. Used to connect to operators 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.
 - `CellularSMS` to read and write SMS messages.
 
+CellularContext class can be easily instantiated with `CellularContext::get_default_instance()` which opens `CellularDevice` and via device opens `CellularContext`. Opening `CellularContext` via `get_default_instance` uses default values from mbed_app.json.
+Default values are not defined by default and must be overridden in mbed_app.json if they are needed:
+"target_overrides": {
+        "*": {
+            "nsapi.default-cellular-plmn": "\"12346\"",
+            "nsapi.default-cellular-sim-pin": "\"1234\"",
+            "nsapi.default-cellular-apn": "\"internet\"",
+            "nsapi.default-cellular-username": 0,
+            "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>
 
 When an application has opened a cellular API, you can use it to request API methods. For example:
 
-    CellularNetwork *network  = cellularDevice->get_network();
-    if (network) {
-        printf("Local IP address is %s", network->get_ip_address());
+    CellularContext *ctx  = cellularDevice->create_context();
+    if (ctx) {
+		if (ctx-connect() == NSAPI_ERROR_OK) {
+			printf("Local IP address is %s", ctx->get_ip_address());
+		}
     }
 
 ### UDP and TCP sockets
@@ -119,7 +136,7 @@ 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_powerl_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 `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).
 
 #### PSM - Power Save Mode