Merge pull request #843 from jarvte/cellular_update_to_511

Amanda Butler · web-flow · commit 042587ad654b · 2018-11-27T16:23:30.000-06:00
Cellular: update handbook to 5.11
diff --git a/docs/api/networkinterfaces/CellularInterface.md b/docs/api/networkinterfaces/CellularInterface.md
@@ -2,15 +2,9 @@
 
 <span class="images">![](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/class_cellular_base.png)<span>CellularBase class hierarchy</span></span>
 
-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.
-
-#### 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), which has more information.
 
 ##### Getting started
 
@@ -48,7 +42,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 PPP or AT mode depending on the modem. 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.
diff --git a/docs/images/api-cellular-quick-start.png b/docs/images/api-cellular-quick-start.png
diff --git a/docs/porting/connectivity/CellularInterface.md b/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
 
diff --git a/docs/reference/configuration/Connectivity.md b/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
diff --git a/docs/reference/technology/connectivity/cellular.md b/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,51 @@ 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 and CTS connected on UART. If RTC and CTS are not connected on UART, then define MDMRTS and MDMCTS as `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.
+As an application developer, you should use and refer only to classes located under API folder. All the other classes have implementation details that 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 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.
 - `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\"",
+            "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 +137,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
 
