Skip to content

Cellular: update handbook to 5.11 #843

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Nov 27, 2018
Merged

Cellular: update handbook to 5.11 #843

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c8500ab
Cellular: update handbook to 5.11
Nov 14, 2018
8fe917a
Edit cellular.md
Nov 26, 2018
be4894d
Cellular: Review fixes, removed redundant references to same class.
Nov 27, 2018
808325d
Spell out abbreviation in cellular.md
Nov 27, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/api/networkinterfaces/CellularInterface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Query: Why do we link to the same Doxy page three times on the same page? Could we get rid of two?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point, removed two links.


#### 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

Expand Down Expand Up @@ -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.
Expand Down
Binary file modified docs/images/api-cellular-quick-start.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/porting/connectivity/CellularInterface.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 7 additions & 1 deletion docs/reference/configuration/Connectivity.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down
38 changes: 28 additions & 10 deletions docs/reference/technology/connectivity/cellular.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>

Expand All @@ -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 APN.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Query: What does APN stand for?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Access Point Name: https://en.wikipedia.org/wiki/Access_Point_Name

- `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
Expand Down Expand Up @@ -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).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch 👍


#### PSM - Power Save Mode

Expand Down