You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/api/networkinterfaces/CellularInterface.md
+7-9Lines changed: 7 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,8 @@
1
-
<h2id="cellular-api">Cellular</h2>
1
+
<h2id="cellular-api">Cellular API</h2>
2
2
3
-
<spanclass="images"><span>CellularBase class hierarchy</span></span>
3
+
<spanclass="images"><span>CellularInterface class hierarchy</span></span>
4
4
5
-
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.
6
-
7
-
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.
5
+
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.
8
6
9
7
##### Getting started
10
8
@@ -48,15 +46,15 @@ You can use and extend a cellular interface in various different ways. For examp
48
46
- The easy cellular connection uses standard 3GPP AT 27.007 AT commands to set up the cellular modem and to register to the network.
49
47
- 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.
|`*EthInterface::get_default_instance()`| Wired Ethernet interface, not Wi-Fi | none |
81
81
|`*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. |
|`*NetworkInterface::get_default_instance()`| One of the above, depending on `target.network-default-interface-type`. ||
84
84
85
85
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.
Copy file name to clipboardExpand all lines: docs/porting/connectivity/CellularInterface.md
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
-
## Cellular module porting
1
+
## Cellular device porting
2
2
3
-
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.
3
+
This document provides guidelines how to make a cellular device adaptation for Mbed OS.
4
4
5
-
### Adding modem target support
5
+
### Adding cellular on an Mbed OS target
6
6
7
7
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`.
8
8
@@ -56,9 +56,9 @@ typedef enum {
56
56
57
57
```
58
58
59
-
### Adding a new cellular target
59
+
### Adding a new cellular device
60
60
61
-
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.
61
+
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.
Copy file name to clipboardExpand all lines: docs/porting/connectivity/NetworkStack.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ Please refer to the [IP networking architecture](../reference/ip-networking.html
14
14
15
15
#### NetworkInterface Class
16
16
17
-
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:
17
+
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:
Copy file name to clipboardExpand all lines: docs/reference/technology/connectivity/cellular.md
+22-47Lines changed: 22 additions & 47 deletions
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
## Cellular
1
+
## Cellular networking
2
2
3
3
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.
4
4
@@ -12,49 +12,30 @@ Key features of the Mbed OS cellular APIs include:
12
12
13
13
- Compatible with 3GPP TS 27.007 and 27.005.
14
14
- Implements core functionality for OMA Lightweight M2M Client.
15
-
-Hosted cellular modules on Mbed Enabled boards.
15
+
-Supports many Mbed Enabled cellular boards.
16
16
17
17
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.
18
18
19
19
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).
20
20
21
-
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.
21
+
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.
22
22
23
23
### Quick start
24
24
25
-
There are two phases to Mbed OS connectivity, in general:
25
+
To use cellular data connection:
26
26
27
27
1. Connect to a network.
28
28
1. Open a socket to send or receive data.
29
29
30
-
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.
30
+
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.
31
31
32
-
<spanclass="images"><span>Figure 2. Connect to cellular network and open a socket</span></span>
32
+
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()`.
33
33
34
34
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/).
35
35
36
-
### Cellular hosted module
36
+
### Cellular device selection
37
37
38
-
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`).
39
-
40
-
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.
41
-
42
-
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.
43
-
44
-
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:
45
-
46
-
{
47
-
"macros":
48
-
[
49
-
"CELLULAR_DEVICE=<manufacturer-module>",
50
-
"MDMRXD=<rx-pin-name>",
51
-
"MDMTXD=<tx-pin-name>",
52
-
"MDMRTS=<rts-pin-name>",
53
-
"MDMCTS=<cts-pin-name>"
54
-
]
55
-
}
56
-
57
-
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`.
38
+
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()`.
58
39
59
40
### Cellular APIs
60
41
@@ -64,14 +45,12 @@ Cellular APIs are structured based on main functionalities:
64
45
65
46
-`CellularContext` is the main interface for the application. You can use it to connect to the operator's Access Point Name (APN).
66
47
-`CellularNetwork` for cellular network features, such as registering and attaching to a network.
67
-
-`CellularPower` for cellular hosted module power control, such as enabling power save.
68
-
-`CellularInformation` to read the cellular hosted module type and firmware version.
69
-
-`CellularSIM` to enter the PIN code and other SIM management functions.
48
+
-`CellularInformation` to read the cellular device and SIM information.
70
49
-`CellularSMS` to read and write SMS messages.
71
50
72
51
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`.
73
52
These values are not defined by default, and you must override them in `mbed_app.json` if you need them:
74
-
53
+
```
75
54
"target_overrides": {
76
55
"*": {
77
56
"nsapi.default-cellular-plmn": "\"12346\"",
@@ -81,25 +60,21 @@ These values are not defined by default, and you must override them in `mbed_app
81
60
"nsapi.default-cellular-password": 0
82
61
}
83
62
}
84
-
85
-
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.
86
-
87
-
<spanclass="images"><span>Figure 3. Use CellularDevice to open Cellular APIs</span></span>
63
+
```
64
+
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.
88
65
89
66
When an application has opened a cellular API, you can use it to request API methods. For example:
printf("Local IP address is %s", ctx->get_ip_address());
95
-
}
70
+
if (ctx->connect() == NSAPI_ERROR_OK) {
71
+
printf("Local IP address is %s", ctx->get_ip_address());
72
+
}
96
73
}
97
-
74
+
```
98
75
### UDP and TCP sockets
99
76
100
-
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.
101
-
102
-
<spanclass="images"><span>Figure 4. IP stack can be used in PPP or AT mode</span></span>
77
+
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).
103
78
104
79
#### PPP mode with the LWIP stack on Mbed OS
105
80
@@ -128,7 +103,7 @@ The AT mode is enabled when the PPP mode is not enabled:
128
103
129
104
Consider the following points when selecting PPP or AT mode:
130
105
131
-
-Your cellular hosted module may support only AT or PPP mode.
106
+
-A cellular device may support only AT or PPP mode.
132
107
- PPP mode supports both UDP and TCP sockets.
133
108
- PPP mode does not allow AT commands after connecting to data mode.
134
109
- 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:
137
112
138
113
### Optimize for power consumption
139
114
140
-
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).
115
+
The cellular API has methods to optimize power saving: Power Save Mode (PSM) and extended Discontinuous Reception (eDRX).
141
116
142
117
#### PSM - Power Save Mode
143
118
144
-
opt_power_save_mode(int periodic_time, int active_time)
119
+
set_power_save_mode(int periodic_time, int active_time)
145
120
146
121
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.
147
122
@@ -153,7 +128,7 @@ PSM configuration is negotiated with the network, and the actual PSM time that n
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.
0 commit comments