Mistake on this page?
Report an issue in GitHub or email us

Non-IP cellular socket

CellularNonIPSocket class hierarchy

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 class.

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

You can request Control Plane optimization mode either with CellularDevice's create_context or by configuring it in the cellular mbed_lib.json:

    "name": "cellular",
    "config": {
        "control-plane-opt": {
            "help": "Enables control plane CIoT EPS optimisation",
            "value": true

CellularNonIPSocket class reference

Public Member Functions
virtual ~CellularNonIPSocket ()
 Destroy the socket. More...
 CellularNonIPSocket ()
 Creates a socket. More...
virtual nsapi_error_t open (mbed::CellularContext *cellular_context)
 Opens a socket on the given cellular context. More...
virtual nsapi_error_t open (mbed::ControlPlane_netif *cp_netif)
 Opens a socket that will use the given control plane interface for data delivery. More...
virtual nsapi_error_t close ()
 Closes socket. More...
virtual nsapi_size_or_error_t send (const void *data, nsapi_size_t size)
 Send data over a control plane cellular context. More...
virtual nsapi_size_or_error_t recv (void *data, nsapi_size_t size)
 Receive data from a socket. More...
virtual void set_blocking (bool blocking)
 Set blocking or non-blocking mode of the socket. More...
virtual void set_timeout (int timeout)
 Set timeout on blocking socket operations. More...
virtual void sigio (mbed::Callback< void()> func)
 Register a callback on state change of the socket. More...
virtual nsapi_error_t connect (const SocketAddress &address)
virtual Socketaccept (nsapi_error_t *error=NULL)
virtual nsapi_error_t listen (int backlog=1)
virtual nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen)
virtual nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen)
virtual nsapi_error_t getpeername (SocketAddress *address)
virtual nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size)
virtual nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size)
virtual nsapi_error_t bind (const SocketAddress &address)

CellularNonIPSocket example

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();

    // sim pin, apn, credentials and possible plmn are taken automatically from json when using NetworkInterface::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
    return 0;

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.