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

Cellular

CellularBase class hierarchy

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.

Cellular

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

Arm Mbed OS provides a reference implementation of CellularBase.

Getting started

  1. Choose an Mbed board that supports cellular, such as the UBLOX-C027 or MTS-DRAGONFLY.

  2. Clone mbed-os-example-cellular. Follow the instructions in the repository.

    1. Compile the code.
    2. Flash the board.

    You see output similar to the excerpt below:

mbed-os-example-cellular
Establishing connection ......

Connection Established.
TCP: connected with echo.mbedcloudtesting.com server
TCP: Sent 4 Bytes to echo.mbedcloudtesting.com
Received from echo server 4 Bytes


Success. Exiting

Basic working principles

You can use and extend a cellular interface in various different ways. For example,

  • Using AT commands to control sockets in an existing IP stack built into the cellular modem.

  • Using a PPP (Point-to-Point Protocol) pipe to pass IP packets between an Mbed OS supported IP stack and cellular modem device.

mbed-os-example-cellular uses an easy cellular connection. It depends on the modem whether the application uses PPP or AT mode. We can summarize this particular design as follows:

  • It uses an external IP stack, such as LWIP, or on-chip network stacks such as when the modem does not support PPP.
  • The easy cellular connection uses standard 3GPP AT 27.007 AT commands to set up the cellular modem and to register to the network.
  • 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.

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
virtual CellularBasecellularBase ()
 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_value_or_error_t gethostbyname_async (const char *host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC)
virtual nsapi_error_t gethostbyname_async_cancel (int id)
virtual nsapi_error_t add_dns_server (const SocketAddress &address)
virtual void attach (mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)
virtual nsapi_connection_status_t get_connection_status () const
virtual nsapi_error_t set_blocking (bool blocking)
virtual EthInterfaceethInterface ()
virtual WiFiInterfacewifiInterface ()
virtual MeshInterfacemeshInterface ()
virtual EMACInterfaceemacInterface ()
Static Public Member Functions
static CellularBaseget_default_instance ()
 Static Public Member Functions inherited from NetworkInterface
static NetworkInterfaceget_default_instance ()
Static Protected Member Functions
static CellularBaseget_target_default_instance ()
 Static Protected Member Functions inherited from NetworkInterface
static NetworkInterfaceget_target_default_instance ()
Additional Inherited Members
 Public Types inherited from NetworkInterface
typedef mbed::Callback< void(nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t
 Public Types inherited from DNS
typedef mbed::Callback< void(nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t
 Protected Member Functions inherited from NetworkInterface
virtual NetworkStackget_stack ()=0

Usage

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.

/*
 * Copyright (c) 2017 ARM Limited. All rights reserved.
 * SPDX-License-Identifier: Apache-2.0
 * Licensed under the Apache License, Version 2.0 (the License); you may
 * not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include "mbed.h"
#include "common_functions.h"
#include "UDPSocket.h"
#include "OnboardCellularInterface.h"

#define UDP 0
#define TCP 1

// SIM pin code goes here
#ifndef MBED_CONF_APP_SIM_PIN_CODE
# define MBED_CONF_APP_SIM_PIN_CODE    "1234"
#endif

#ifndef MBED_CONF_APP_APN
# define MBED_CONF_APP_APN         "internet"
#endif
#ifndef MBED_CONF_APP_USERNAME
# define MBED_CONF_APP_USERNAME    NULL
#endif
#ifndef MBED_CONF_APP_PASSWORD
# define MBED_CONF_APP_PASSWORD    NULL
#endif

// Number of retries /
#define RETRY_COUNT 3



// CellularInterface object
OnboardCellularInterface iface;

// Echo server hostname
const char *host_name = "echo.mbedcloudtesting.com";

// Echo server port (same for TCP and UDP)
const int port = 7;

Mutex PrintMutex;
Thread dot_thread(osPriorityNormal, 512);

#define PRINT_TEXT_LENGTH 128
char print_text[PRINT_TEXT_LENGTH];
void print_function(const char *input_string)
{
    PrintMutex.lock();
    printf("%s", input_string);
    fflush(NULL);
    PrintMutex.unlock();
}

void dot_event()
{

    while (true) {
        wait(4);
        if (!iface.is_connected()) {
            print_function(".");
        } else {
            break;
        }
    }

}


/**
 * Connects to the Cellular Network
 */
nsapi_error_t do_connect()
{
    nsapi_error_t retcode;
    uint8_t retry_counter = 0;

    while (!iface.is_connected()) {

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

        break;
    }

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

    return NSAPI_ERROR_OK;
}

/**
 * Opens a UDP or a TCP socket with the given echo server and performs an echo
 * transaction retrieving current.
 */
nsapi_error_t test_send_recv()
{
    nsapi_size_or_error_t retcode;
#if MBED_CONF_APP_SOCK_TYPE == TCP
    TCPSocket sock;
#else
    UDPSocket sock;
#endif

    retcode = sock.open(&iface);
    if (retcode != NSAPI_ERROR_OK) {
        snprintf(print_text, PRINT_TEXT_LENGTH, "UDPSocket.open() fails, code: %d\n", retcode);
        print_function(print_text);
        return -1;
    }

    SocketAddress sock_addr;
    retcode = iface.gethostbyname(host_name, &sock_addr);
    if (retcode != NSAPI_ERROR_OK) {
        snprintf(print_text, PRINT_TEXT_LENGTH, "Couldn't resolve remote host: %s, code: %d\n", host_name,
               retcode);
        print_function(print_text);
        return -1;
    }

    sock_addr.set_port(port);

    sock.set_timeout(15000);
    int n = 0;
    const char *echo_string = "TEST";
    char recv_buf[4];
#if MBED_CONF_APP_SOCK_TYPE == TCP
    retcode = sock.connect(sock_addr);
    if (retcode < 0) {
        snprintf(print_text, PRINT_TEXT_LENGTH, "TCPSocket.connect() fails, code: %d\n", retcode);
        print_function(print_text);
        return -1;
    } else {
        snprintf(print_text, PRINT_TEXT_LENGTH, "TCP: connected with %s server\n", host_name);
        print_function(print_text);
    }
    retcode = sock.send((void*) echo_string, sizeof(echo_string));
    if (retcode < 0) {
        snprintf(print_text, PRINT_TEXT_LENGTH, "TCPSocket.send() fails, code: %d\n", retcode);
        print_function(print_text);
        return -1;
    } else {
        snprintf(print_text, PRINT_TEXT_LENGTH, "TCP: Sent %d Bytes to %s\n", retcode, host_name);
        print_function(print_text);
    }

    n = sock.recv((void*) recv_buf, sizeof(recv_buf));
#else

    retcode = sock.sendto(sock_addr, (void*) echo_string, sizeof(echo_string));
    if (retcode < 0) {
        snprintf(print_text, PRINT_TEXT_LENGTH, "UDPSocket.sendto() fails, code: %d\n", retcode);
        print_function(print_text);
        return -1;
    } else {
        snprintf(print_text, PRINT_TEXT_LENGTH, "UDP: Sent %d Bytes to %s\n", retcode, host_name);
        print_function(print_text);
    }

    n = sock.recvfrom(&sock_addr, (void*) recv_buf, sizeof(recv_buf));
#endif

    sock.close();

    if (n > 0) {
        snprintf(print_text, PRINT_TEXT_LENGTH, "Received from echo server %d Bytes\n", n);
        print_function(print_text);
        return 0;
    }

    return -1;
}

int main()
{

    iface.modem_debug_on(MBED_CONF_APP_MODEM_TRACE);
    /* Set Pin code for SIM card */
    iface.set_sim_pin(MBED_CONF_APP_SIM_PIN_CODE);

    /* Set network credentials here, e.g., APN*/
    iface.set_credentials(MBED_CONF_APP_APN, MBED_CONF_APP_USERNAME, MBED_CONF_APP_PASSWORD);

    print_function("\n\nmbed-os-example-cellular\n");
    print_function("Establishing connection ");
    dot_thread.start(dot_event);

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

    print_function("\n\nFailure. Exiting \n\n");
    return -1;
}
// EOF

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.