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


The CellularBase provides a C++ API for connecting to the internet over a Cellular device.

Arm Mbed OS provides a reference implementation of CellularBase, which has more information.

CellularBase class reference

Public Member Functions
virtual void set_credentials (const char *apn, const char *uname=0, const char *pwd=0)=0
virtual void set_sim_pin (const char *sim_pin)=0
virtual nsapi_error_t connect (const char *sim_pin, const char *apn=0, const char *uname=0, const char *pwd=0)=0
virtual nsapi_error_t connect ()=0
virtual nsapi_error_t disconnect ()=0
virtual bool is_connected ()=0
virtual const char * get_ip_address ()=0
virtual const char * get_netmask ()=0
virtual const char * get_gateway ()=0
 Public Member Functions inherited from NetworkInterface
virtual const char * get_mac_address ()
virtual nsapi_error_t set_network (const char *ip_address, const char *netmask, const char *gateway)
virtual nsapi_error_t set_dhcp (bool dhcp)
virtual nsapi_error_t gethostbyname (const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC)
virtual nsapi_error_t add_dns_server (const SocketAddress &address)
Additional Inherited Members
 Protected Member Functions inherited from NetworkInterface
virtual NetworkStackget_stack ()=0


To bring up the network interface:

  1. Instantiate an implementation of the CellularBase class.
  2. Call the connect(pincode, apn) function with a PIN code for your SIM card and an APN for your network.
  3. Once connected, you can use Mbed OS network sockets as usual.

Cellular example: connection establishment

This example establishes connection with the cellular network using Mbed OS CellularInterface.

#include "mbed.h"
#include "OnboardCellularInterface.h"

/* SIM pin code goes here */
#define PIN_CODE    "1234"

/* Network credentials like APN go here, e.g.,
    "apn, username, password" */
#define CREDENTIALS "internet"

/* Number of retries */
#define RETRY_COUNT 3

OnboardCellularInterface iface;

nsapi_error_t do_connect()
    nsapi_error_t retcode;
    bool disconnected = false;
    uint8_t retry_counter = 0;

    while (!iface.is_connected()) {

        retcode = iface.connect();
        if (retcode == NSAPI_ERROR_AUTH_FAILURE) {
            printf("\n\nAuthentication Failure. Exiting application\n");
            return retcode;
        } else if (retcode != NSAPI_ERROR_OK) {
            printf("\n\nCouldn't connect: %d, will retry\n", retcode);
        } else if (retcode != NSAPI_ERROR_OK && retry_counter > RETRY_COUNT) {
            printf("\n\nFatal connection failure: %d\n", retcode);
            return retcode;


    printf("\n\nConnection Established.\n");

    return NSAPI_ERROR_OK;

int main()
    /* Set Pin code for SIM card */

    /* Set network credentials here, e.g., APN*/

    printf("\n\nmbed-os-example-cellular, Connecting...\n");

    /* Attempt to connect to a cellular network */
    if (do_connect() == NSAPI_ERROR_OK) {
        printf("\n\nSuccess. Exiting \n\n");
        return 0;

    printf("\n\nFailure. Exiting \n\n");
    return -1;
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.