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

Cellular module porting

This document provides guidelines how to make a cellular modem adaptation for Mbed OS. Please see Cellular API usage about how to use cellular modules from an application point of view.

Adding modem target support

For new targets, you may need to modify targets.json, which defines all the target platforms that Mbed OS supports. If Mbed OS supports your specific target, an entry for your target is in this file. To tell the Mbed OS build configuration that your target board has an onboard cellular module, you need to define modem_is_on_board and modem_data_connection_type.

For example,

    "MY_NEW_TARGET": {
        "supported_form_factors": ["ARDUINO"],
        "core": "Cortex-M3",
        "supported_toolchains": ["ARM", "uARM", "GCC_ARM", "GCC_CR", "IAR"],
        "extra_labels": ["LABEL", "ANOTHER_LABEL"],
        "config": {
            "modem_is_on_board": {
                "help": "Value: Tells the build system that the modem is on-board as opposed to a plug-in shield/module.",
                "value": 1,
                "macro_name": "MODEM_ON_BOARD"
            "modem_data_connection_type": {
                "help": "Value: Defines how the modem is wired up to the MCU, e.g., data connection can be a UART or USB and so forth.",
                "value": 1,
                "macro_name": "MODEM_ON_BOARD_UART"
        "macros": ["TARGET_NEW"],
        "inherits": ["BaseTargetForAll"],
        "device_has": ["ETHERNET", "SPI"],
        "device_name": "NewDevice"

In addition you need to map onboard modem pin aliases to your target board pin names and polarity in targets/TARGET_FAMILY/YOUR_TARGET/PinNames.h. If any of the pins are not connected, mark it 'NC'. An example UART configuration:

typedef enum {

	MDMTXD = P0_15, // Transmit Data
	MDMRXD = P0_16, // Receive Data
	MDMCTS = P0_17, // Clear to Send
	MDMDCD = P0_18, // Data Carrier Detect
	MDMDSR = P0_19, // Data Set Ready
	MDMDTR = P0_20, // Data Terminal Ready
	MDMRI  = P0_21, // Ring Indicator
	MDMRTS = P0_22, // Ready to Receive

} PinName;



Adding a new cellular target

You need to specify in CellularTargets.h the <manufacturer-module> that is mounted on your board.

#elif <your target>
#define CELLULAR_DEVICE <manufacturer-module>

You can browse the existing manufacturer-modules under features/cellular/framework/targets. If none of those are compatible with your module then you need to make a new cellular module adaptation.

Adding a new cellular module

You can probably reuse an existing adaptation because most cellular modules are similar to one another.

You need to create a new folder as MANUFACTURER/MODULE/ for your new cellular module in features/cellular/framework/targets/. A device class inheriting AT_CellularDevice is a minimum, and you may need to extend other cellular APIs as well if the default implementation is not sufficient for your cellular module.

Socket adaptation

You can implement the socket API in two ways:

  • Use the IP stack on the cellular module (AT mode).
  • Use the LWIP stack on Mbed OS (PPP mode).

If your cellular module has an IP stack, you need to implement the AT commands to connect to a network and to control network sockets. If the modem supports PPP mode, you can use the LWIP stack to handle sockets and IP connectivity for your modem after it connects to a network. A modem can support both the AT and PPP modes, but an application developer needs to select at compile time which mode should be used. This selection is made in the application's mbed_app.json configuration file using the lwip.ppp-enabled flag.

For example implementations of a socket adaptation, look in features/cellular/framework/targets.

When the modem has AT and/or PPP mode support in place and the application developer has selected which mode to use, it's up to the cellular framework to instantiate the correct classes. For example, mbed-os-example-cellular instantiates CellularContext class. CellularContext instantiates classes implementing the AT command layer between the modem and the Mbed OS CPU. If an application developer has configured PPP mode in mbed_app.json then AT_CellularContext connects to a cellular network and calls nsapi_ppp_connect() to start the data call through the PPP pipe using LWIP sockets.


Once you have your target and driver port ready, you can verify your implementation by running port verification tests on your system. You must have mbed-greentea installed for this.

To run the tests:

  1. From the root of your application, enter this command:

    mbed test --compile-list
  2. Look for the name of a test suite matching features-cellular-tests-*.

  3. Run tests with the command:

    mbed test -n "mbed-os-features-cellular-tests-*" -m TARGET -t TOOLCHAIN --app-config YOURCONFIG.json
  4. Run Mbed OS Socket tests. Please see the Network Socket test plan for instructions on how to run Mbed OS socket tests.

For more information on the mbed-greentea test suite, please visit its documentation.

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.