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 optimization",
            "value": true

CellularNonIPSocket class reference

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

CellularNonIPSocket example

The following code demonstrates how to create and use a cellular non-IP socket:

 * Copyright (c) 2006-2020 Arm Limited and affiliates.
 * SPDX-License-Identifier: Apache-2.0
#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.