From fac27715ffb7f7dcdf3b09589290c6aca1255b0a Mon Sep 17 00:00:00 2001 From: Mirela Chirica Date: Wed, 16 Jan 2019 18:30:58 +0200 Subject: [PATCH 1/6] Cellular: Documenting the support for Non-IP data delivery feature --- docs/api/networksocket/CellularNonIPSocket.md | 88 +++++++++++++++++++ docs/api/networksocket/networksocket.md | 3 +- docs/reference/configuration/Connectivity.md | 15 ++++ .../technology/connectivity/connectivity.md | 9 +- 4 files changed, 113 insertions(+), 2 deletions(-) create mode 100644 docs/api/networksocket/CellularNonIPSocket.md diff --git a/docs/api/networksocket/CellularNonIPSocket.md b/docs/api/networksocket/CellularNonIPSocket.md new file mode 100644 index 0000000000..81c50ddd12 --- /dev/null +++ b/docs/api/networksocket/CellularNonIPSocket.md @@ -0,0 +1,88 @@ +## Non-IP cellular socket + +The CellularNonIPSocket class provides, through standard socket send and recv member functions, the ability to send and receive 3GPP Non-IP datagrams (NIDD) using Cellular IoT feature. This feature is implemented in [`ControlPlane_netif`](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_control_plane__netif.html) class. + +The constructor takes no parameters. To initialize the socket on a specified NetworkInterface, you must call `open` method, which takes a CellularContext pointer. + +[`CellularContext`](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h.html) is setting up the modem into the Control Plane optimisation mode of operation if it is requested and cellular network supports it. + +Control plane optimisations is a new feature for Cellular IoT (CIoT), where the device can use cellular control channels for data communications, to save power and resources as there is less radio singling needed. + +NOTE! Non-IP usage usually requires integration to cellular operator messaging service. The service supports a web API to send and receive to the non-IP using devices. + + +Control Plane optimisation mode can be requested either on CellularDevice's [`create_context`](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_cellular_device.html#a43b9e992dff1cb5d880acec576e9d06f) or configured in cellular mbed_lib.json: + +```json +{ + "name": "cellular", + "config": { + "control-plane-opt": { + "help": "Enables control plane CIoT EPS optimisation", + "value": true + } + } +} +``` +ControlPlane +### CellularNonIPSocket class reference + +[![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_cellular_non_i_p_socket.html) + +The following code demonstrates how to create and use a cellular Non-IP socket: +``` + +#include "mbed.h" +#include "CellularNonIPSocket.h" +#include "CellularDevice.h" + +// Network interface +NetworkInterface *iface; + +int main() { + // Bring up the cellular interface + iface = CellularContext::get_default_nonip_instance(); + MBED_ASSERT(iface); + + // sim pin, apn, credentials and possible plmn are taken automatically from json when using NetworkInterface::set_default_parameters() + iface->set_default_parameters(); + + printf("Cellular Non-IP Socket example\n"); + if(NSAPI_ERROR_OK != iface->connect() || NSAPI_STATUS_GLOBAL_UP != iface->get_connection_status()) { + printf("Error connecting\n"); + return -1; + } + + CellularNonIPSocket sock; + + nsapi_error_t retcode = sock.open((CellularContext*)iface); + + if (retcode != NSAPI_ERROR_OK) { + printf("CellularNonIPSocket.open() fails, code: %d\n", retcode); + return -1; + } + + const char *send_string = "TEST"; + + if(0 > sock.send((void*) send_string, sizeof(send_string))) { + printf("Error sending data\n"); + return -1; + } + + printf("Success sending data\n"); + + char recv_buf[4]; + if(0 > sock.recv((void *)recv_buf, sizeof(recv_buf))) { + printf("Error receiving data\n"); + return -1; + } + + printf("Success receiving data\n"); + + // Close the socket and bring down the network interface + sock.close(); + iface->disconnect(); + return 0; +} + +``` diff --git a/docs/api/networksocket/networksocket.md b/docs/api/networksocket/networksocket.md index b91e4254f8..44dc4c66f4 100644 --- a/docs/api/networksocket/networksocket.md +++ b/docs/api/networksocket/networksocket.md @@ -1,6 +1,6 @@

Network socket overview

-The application programming interface for IP networking is the Socket API. As described in the [IP networking](../reference/ip-networking.html) section, the Socket API relates to OSI layer 4, the Transport layer. In Mbed OS, the Socket API supports both TCP and UDP protocols. +The application programming interface for IP networking is the Socket API. As described in the [IP networking](../reference/ip-networking.html) section, the Socket API relates to OSI layer 4, the Transport layer. In Mbed OS, the Socket API is abstract and supports various protocols such as TCP, UDP and Non-IP data delivery for NB-IoT cellular networks. ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/ip-networking.png)Sockets @@ -97,6 +97,7 @@ The network socket API provides a common interface for using sockets on network - [UDPSocket](udpsocket.html): This class provides the ability to send packets of data over UDP. - [TCPSocket](tcpsocket.html): This class provides the ability to send a stream of data over TCP. - [SocketAddress](socketaddress.html): You can use this class to represent the IP address and port pair of a unique network endpoint. +- [CellularNonIPSocket](cellularnonipsocket.html): This class provides the ability to send and receive 3GPP Non-IP datagrams (NIDD) using Cellular IoT feature. - [Network status](network-status.html): API for monitoring network status changes. - [DNS resolver](dns-resolver.html): API for resolving DNS names diff --git a/docs/reference/configuration/Connectivity.md b/docs/reference/configuration/Connectivity.md index e571a4ba4d..9aaca1985d 100644 --- a/docs/reference/configuration/Connectivity.md +++ b/docs/reference/configuration/Connectivity.md @@ -157,6 +157,21 @@ Name: cellular.use-apn-lookup Defined by: library:cellular Macro name: MBED_CONF_CELLULAR_USE_APN_LOOKUP Value: 1 (set by library:cellular) +Name: cellular.debug-at + Description: Enable AT debug prints + Defined by: library:cellular + Macro name: MBED_CONF_CELLULAR_DEBUG_AT + Value: 0 (set by library:cellular) +Name: cellular.radio-access-technology + Description: Radio access technology to use. Value in integer: GSM=0, GSM_COMPACT=1, UTRAN=2, EGPRS=3, HSDPA=4, HSUPA=5, HSDPA_HSUPA=6, E_UTRAN=7, CATM1=8 ,NB1=9 + Defined by: library:cellular + Macro name: MBED_CONF_CELLULAR_RADIO_ACCESS_TECHNOLOGY + Value: null (set by library:cellular) +Name: cellular.control-plane-opt + Description: Enables control plane CIoT EPS optimisation + Defined by: library:cellular + Macro name: MBED_CONF_CELLULAR_CONTROL_PLANE_OPT + Value: 0 (set by library:cellular) Name: ppp-cell-iface.apn-lookup Defined by: library:ppp-cell-iface Macro name: MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP diff --git a/docs/reference/technology/connectivity/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index 2ece0a6fa8..85c09827e9 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -12,9 +12,10 @@ For IP devices: * NB-IoT. * Bluetooth Low Energy (BLE). -Non-IP devices require a gateway: +Non-IP devices: * LoRaWAN. +* Cellular. ### Choosing your connectivity method @@ -101,6 +102,12 @@ Near-field communication (NFC) is a short range (few centimeters) wireless techn To learn how to use NFC with Mbed OS, please refer to the [Mbed OS NFC overview](../apis/nfc.html). +#### NB-IoT Cellular + +Non-IP Data Delivery(NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane CIoT EPS optimization and meant to provide improved support of small data transfer. It does this by transporting user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. + +To learn how to use this feature with Mbed OS, please refer to [CellularNonIPSocket](../apis/cellularnonipsocket.html). + #### Memory needs for Pelion-connected devices Mbed OS's baseline memory footprint, without Pelion connectivity, is 2.8kb of RAM and 8.2kb of flash. When you add connectivity and full functionality, the footprint grows: From 38ecd702f17add631e61fe382deb4d949518628e Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 13 Feb 2019 16:27:53 -0600 Subject: [PATCH 2/6] Edit CellularNonIPSocket.md Edit file, mostly for minor style change and international English (as opposed to UK English). --- docs/api/networksocket/CellularNonIPSocket.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/api/networksocket/CellularNonIPSocket.md b/docs/api/networksocket/CellularNonIPSocket.md index 81c50ddd12..d0d8dd7240 100644 --- a/docs/api/networksocket/CellularNonIPSocket.md +++ b/docs/api/networksocket/CellularNonIPSocket.md @@ -1,17 +1,16 @@ ## Non-IP cellular socket -The CellularNonIPSocket class provides, through standard socket send and recv member functions, the ability to send and receive 3GPP Non-IP datagrams (NIDD) using Cellular IoT feature. This feature is implemented in [`ControlPlane_netif`](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_control_plane__netif.html) class. +The CellularNonIPSocket class provides, through standard socket `send` and `recv` member functions, the ability to send and receive 3GPP non-IP datagrams (NIDD) using our cellular IoT feature. This feature is implemented in the [`ControlPlane_netif`](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_control_plane__netif.html) class. -The constructor takes no parameters. To initialize the socket on a specified NetworkInterface, you must call `open` method, which takes a CellularContext pointer. +The constructor takes no parameters. To initialize the socket on a specified NetworkInterface, you must call the `open` method, which takes a CellularContext pointer. -[`CellularContext`](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h.html) is setting up the modem into the Control Plane optimisation mode of operation if it is requested and cellular network supports it. +[`CellularContext`](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h.html) sets up the modem into the Control Plane optimization mode of operation if it is requested and if the cellular network supports it. -Control plane optimisations is a new feature for Cellular IoT (CIoT), where the device can use cellular control channels for data communications, to save power and resources as there is less radio singling needed. +Control plane optimization is a new feature for cellular IoT (CIoT). With it, the device can use cellular control channels for data communications, to save power and resources. It does this by using less radio singling. -NOTE! Non-IP usage usually requires integration to cellular operator messaging service. The service supports a web API to send and receive to the non-IP using devices. +Note: **Note:** Non-IP use usually requires integration to a cellular operator messaging service. The service supports a web API to send to and receive the non-IP using devices. - -Control Plane optimisation mode can be requested either on CellularDevice's [`create_context`](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_cellular_device.html#a43b9e992dff1cb5d880acec576e9d06f) or configured in cellular mbed_lib.json: +You can request Control Plane optimization mode either with CellularDevice's [`create_context`](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_cellular_device.html#a43b9e992dff1cb5d880acec576e9d06f) or by configuring it in the cellular `mbed_lib.json`: ```json { @@ -24,12 +23,13 @@ Control Plane optimisation mode can be requested either on CellularDevice's [`cr } } ``` -ControlPlane + ### CellularNonIPSocket class reference [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_cellular_non_i_p_socket.html) -The following code demonstrates how to create and use a cellular Non-IP socket: +The following code demonstrates how to create and use a cellular non-IP socket: + ``` #include "mbed.h" From 3ec8229a7e02664f7a14f333717ad47ea84070bb Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 13 Feb 2019 16:37:20 -0600 Subject: [PATCH 3/6] Edit networksocket.md Edit file for consistent capitalization across docs. --- docs/api/networksocket/networksocket.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/api/networksocket/networksocket.md b/docs/api/networksocket/networksocket.md index 44dc4c66f4..7e881dc072 100644 --- a/docs/api/networksocket/networksocket.md +++ b/docs/api/networksocket/networksocket.md @@ -1,6 +1,6 @@

Network socket overview

-The application programming interface for IP networking is the Socket API. As described in the [IP networking](../reference/ip-networking.html) section, the Socket API relates to OSI layer 4, the Transport layer. In Mbed OS, the Socket API is abstract and supports various protocols such as TCP, UDP and Non-IP data delivery for NB-IoT cellular networks. +The application programming interface for IP networking is the Socket API. As described in the [IP networking](../reference/ip-networking.html) section, the Socket API relates to OSI layer 4, the Transport layer. In Mbed OS, the Socket API is abstract and supports various protocols such as TCP, UDP and non-IP data delivery for NB-IoT cellular networks. ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/ip-networking.png)Sockets @@ -97,7 +97,7 @@ The network socket API provides a common interface for using sockets on network - [UDPSocket](udpsocket.html): This class provides the ability to send packets of data over UDP. - [TCPSocket](tcpsocket.html): This class provides the ability to send a stream of data over TCP. - [SocketAddress](socketaddress.html): You can use this class to represent the IP address and port pair of a unique network endpoint. -- [CellularNonIPSocket](cellularnonipsocket.html): This class provides the ability to send and receive 3GPP Non-IP datagrams (NIDD) using Cellular IoT feature. +- [CellularNonIPSocket](cellularnonipsocket.html): This class provides the ability to send and receive 3GPP non-IP datagrams (NIDD) using our cellular IoT feature. - [Network status](network-status.html): API for monitoring network status changes. - [DNS resolver](dns-resolver.html): API for resolving DNS names From 56ef0f2b269c6591ca77edfc137a17b8101f2081 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Wed, 13 Feb 2019 16:38:52 -0600 Subject: [PATCH 4/6] Edit connectivity.md Make minor edits to add a missing space and standardize capitalization in headings throughout the document. --- docs/reference/technology/connectivity/connectivity.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/reference/technology/connectivity/connectivity.md b/docs/reference/technology/connectivity/connectivity.md index 85c09827e9..96fa514352 100644 --- a/docs/reference/technology/connectivity/connectivity.md +++ b/docs/reference/technology/connectivity/connectivity.md @@ -93,7 +93,6 @@ Because of its long range (up to 20 km) and low power, it is suitable for low da The [LoRa](lora-tech.html) section and [LoRa tutorial](../tutorials/LoRa-tutorial.html) describe LoRA networking. - #### NFC ![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/n_mark.png)NFC @@ -102,9 +101,9 @@ Near-field communication (NFC) is a short range (few centimeters) wireless techn To learn how to use NFC with Mbed OS, please refer to the [Mbed OS NFC overview](../apis/nfc.html). -#### NB-IoT Cellular +#### NB-IoT cellular -Non-IP Data Delivery(NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane CIoT EPS optimization and meant to provide improved support of small data transfer. It does this by transporting user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. +Non-IP Data Delivery (NIDD) is a new feature for communication over NB-IoT. It is enabled by Control Plane cellular IoT EPS optimization and meant to provide improved support of small data transfer. It does this by transporting user data over the control channel, thus reducing the total number of control plane messages when handling a short data transaction. To learn how to use this feature with Mbed OS, please refer to [CellularNonIPSocket](../apis/cellularnonipsocket.html). From b67853629bc810256d74addf29ad4a942989a9d5 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 19 Feb 2019 10:30:03 -0600 Subject: [PATCH 5/6] Update CellularNonIPSocket.md Make change suggested in comments. --- docs/api/networksocket/CellularNonIPSocket.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/networksocket/CellularNonIPSocket.md b/docs/api/networksocket/CellularNonIPSocket.md index d0d8dd7240..e88ddc6199 100644 --- a/docs/api/networksocket/CellularNonIPSocket.md +++ b/docs/api/networksocket/CellularNonIPSocket.md @@ -6,7 +6,7 @@ The constructor takes no parameters. To initialize the socket on a specified Net [`CellularContext`](https://os.mbed.com/docs/development/mbed-os-api-doxy/_cellular_context_8h.html) sets up the modem into the Control Plane optimization mode of operation if it is requested and if the cellular network supports it. -Control plane optimization is a new feature for cellular IoT (CIoT). With it, the device can use cellular control channels for data communications, to save power and resources. It does this by using less radio singling. +Control plane optimization is a new feature for cellular IoT (CIoT). With it, the device can use cellular control channels for data communications, to save power and resources by using less radio signaling. Note: **Note:** Non-IP use usually requires integration to a cellular operator messaging service. The service supports a web API to send to and receive the non-IP using devices. From 303292fe8e7959841ef2e0f9afda8c69dbe1a0d5 Mon Sep 17 00:00:00 2001 From: Amanda Butler Date: Tue, 19 Feb 2019 10:31:32 -0600 Subject: [PATCH 6/6] Update networksocket.md Make change suggested in comments for accuracy. --- docs/api/networksocket/networksocket.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api/networksocket/networksocket.md b/docs/api/networksocket/networksocket.md index 7e881dc072..9ace2a7054 100644 --- a/docs/api/networksocket/networksocket.md +++ b/docs/api/networksocket/networksocket.md @@ -97,7 +97,7 @@ The network socket API provides a common interface for using sockets on network - [UDPSocket](udpsocket.html): This class provides the ability to send packets of data over UDP. - [TCPSocket](tcpsocket.html): This class provides the ability to send a stream of data over TCP. - [SocketAddress](socketaddress.html): You can use this class to represent the IP address and port pair of a unique network endpoint. -- [CellularNonIPSocket](cellularnonipsocket.html): This class provides the ability to send and receive 3GPP non-IP datagrams (NIDD) using our cellular IoT feature. +- [CellularNonIPSocket](cellularnonipsocket.html): This class provides the ability to send and receive 3GPP non-IP datagrams (NIDD) using the cellular IoT feature. - [Network status](network-status.html): API for monitoring network status changes. - [DNS resolver](dns-resolver.html): API for resolving DNS names