Register callback for status reporting.

The specified status callback function will be called on the network and cellular device status changes. The parameters on the callback are the event type and event-type dependent reason parameter.

Remarks

deleting CellularDevice/CellularContext in callback not allowed.

Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which is now 2048. You can change to main thread for example via EventQueue.

Parameters

status_cb

The callback for status changes.

Start the interface.

Attempts to attach the device to cellular network. API is asynchronous. Application can get results from CellularContext callback, which is set with attach(...), or callback, which is set by attach(...), in this class.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on case of memory failure

Cellular callback to be attached to Network and CellularStateMachine classes.

CellularContext calls this when in PPP mode to provide network changes. This method will broadcast to every interested classes: CellularContext (might be many) and CellularStateMachine if available.

Reimplemented from CellularDevice.

Clear modem to a default initial state.

Clear persistent user data from the modem, such as PDP contexts.

Precondition

All open network services on modem, such as contexts and sockets, must be closed.

Postcondition

Modem power off/on may be needed to clear modem's runtime state.

Remarks

CellularStateMachine calls this on connect when cellular.clear-on-connect: true.

Returns

NSAPI_ERROR_OK on success, otherwise modem may be need power cycling

Reimplemented from CellularDevice.

Closes the opened CellularInformation by deleting the CellularInformation instance.

Implements CellularDevice.

Closes the opened CellularNetwork by deleting the CellularNetwork instance.

Implements CellularDevice.

Closes the opened CellularSMS by deleting the CellularSMS instance.

Implements CellularDevice.

Creates a new CellularContext interface.

Parameters

fh	file handle used in communication to modem. This can be, for example, UART handle. If null, then the default file handle is used.
apn	access point to use with context, can be null.
cp_req	flag indicating if EPS control plane optimization is required
nonip_req	flag indicating if this context is required to be Non-IP

Returns

new instance of class CellularContext or NULL in case of failure

Implements CellularDevice.

Creates a new CellularContext interface.

This API should be used if serial is UART and PPP mode used. CellularContext created will use data carrier detect to be able to detect disconnection much faster in PPP mode. UARTSerial usually is the same which was given for the CellularDevice.

Parameters

serial	UARTSerial used in communication to modem. If null then the default file handle is used.
apn	access point to use with context, can be null.
dcd_pin	Pin used to set data carrier detect on/off for the given UART
active_high	a boolean set to true if DCD polarity is active low
cp_req	Flag indicating if EPS control plane optimization is required
nonip_req	Flag indicating if this context is required to be Non-IP

Returns

new instance of class CellularContext or NULL in case of failure

Implements CellularDevice.

Creates new instance of AT_CellularContext or if overridden, modem specific implementation.

Parameters

at	ATHandler reference for communication with the modem.
apn	access point to use with context
cp_req	flag indicating if control plane EPS optimization needs to be setup
nonip_req	flag indicating if PDP context needs to be Non-IP

Returns

new instance of class AT_CellularContext

Deletes the given CellularContext instance.

Parameters

context

CellularContext to delete

Implements CellularDevice.

Get the current ATHandler instance in use for debug purposes etc.

Once use has been finished call to release_at_handler() has to be made

Returns

Pointer to the ATHandler in use

Implements CellularDevice.

Get the linked list of CellularContext instances.

Returns

Pointer to first item in linked list

Reimplemented from CellularDevice.

Returns singleton instance of CellularDevice, if Mbed target board has a supported onboard modem, or provide-default is defined for a cellular driver in JSON configuration files.

Otherwise returns NULL. See NetworkInterface::get_default_instance for details.

Remarks

Application may override this (non-weak) default implementation.

Returns

default CellularDevice, NULL if not defined

Get the current FileHandle item used when communicating with the modem.

Returns

reference to FileHandle

Get event queue that can be chained to main event queue.

Returns

event queue

Get the retry array from the CellularStateMachine.

Array is used in retry logic. Array contains seconds and retry logic uses those second to wait before trying again.

Parameters

timeout	timeout array containing seconds for retry logic. Must have space for CELLULAR_RETRY_ARRAY_SIZE (defined in CellularCommon.h)
array_len	length of the timeout array on return

Get SIM card's state.

Parameters

state

current state of SIM

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implements CellularDevice.

Return target onboard instance of CellularDevice.

Remarks

Mbed OS target shall override (non-weak) this function for an onboard modem.

Returns

CellularDevice* instance, NULL if not defined

Sets the modem in unplugged state.

This is equivalent to pulling the plug off of the device, i.e., detaching power and serial port.

This puts the modem in the lowest power state.

Remarks

CellularStateMachine disconnect or destruct does not shutdown or power off the modem, but you need to do that yourself.

Precondition

You must call soft_power_off to power off the modem before calling hard_power_off.

Returns

NSAPI_ERROR_OK on success

Implements CellularDevice.

Sets the modem up for powering on This is equivalent to plugging in the device, i.e., attaching power and serial port.

In general, hard_power_on and soft_power_on provides a simple hardware abstraction layer on top of the modem drivers written for Mbed OS; they can be overridden in a derived class to perform custom power controls in a particular board configuration. In many boards this will be a no-op if there is no separate power supply control circuitry.

Remarks

CellularStateMachine calls hard_power_on at first until successful, then soft_power_on and init until the modem responds. If you are not using CellularStateMachine then you need to call these functions yourself.

Postcondition

You must call soft_power_on to power on the modem after calling hard_power_on.

Returns

NSAPI_ERROR_OK on success

Implements CellularDevice.

Initialize cellular device must be called right after the module is ready.

For example, when multiple cellular modules are supported in a single driver this function detects and adapts to an actual module at runtime.

Remarks

CellularStateMachine calls soft_power_on and init repeatedly when starting to connect until the modem responds.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on case of memory failure NSAPI_ERROR_UNSUPPORTED if current cellular module type is not detected NSAPI_ERROR_DEVICE_ERROR if model information could not be read

Implements CellularDevice.

Check whether the device is ready to accept commands.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implements CellularDevice.

Turn modem debug traces on.

Parameters

on	set true to enable debug traces

Implements CellularDevice.

Create new CellularInformation interface.

Parameters

fh	file handle used in communication to modem. This can be, for example, UART handle. If null, then the default file handle is used.

Returns

New instance of interface CellularInformation.

Implements CellularDevice.

Create new instance of AT_CellularInformation or if overridden, modem specific implementation.

Parameters

at	ATHandler reference for communication with the modem.

Returns

new instance of class AT_CellularInformation

Create new CellularNetwork interface.

Parameters

fh	file handle used in communication to modem. This can be, for example, UART handle. If null, then the default file handle is used.

Returns

New instance of interface CellularNetwork.

Implements CellularDevice.

Create new instance of AT_CellularNetwork or if overridden, modem specific implementation.

Parameters

at	ATHandler reference for communication with the modem.

Returns

new instance of class AT_CellularNetwork

Create new CellularSMS interface.

Parameters

fh	file handle used in communication to modem. This can be, for example, UART handle. If null, then the default file handle is used.

Returns

New instance of interface CellularSMS.

Implements CellularDevice.

Create new instance of AT_CellularSMS or if overridden, modem specific implementation.

Parameters

at	ATHandler reference for communication with the modem.

Returns

new instance of class AT_CellularSMS

Start the interface.

Attempts to register the device to cellular network. API is asynchronous. Application can get results from CellularContext callback, which is set with attach(...), or callback, which is set by attach(...), in this class.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on case of memory failure

Releases the given at_handler.

If last reference to at_hander then it's deleted.

Parameters

at_handler

Returns

NSAPI_ERROR_OK on success, NSAPI_ERROR_PARAMETER on failure

Implements CellularDevice.

Start the interface.

Initializes the modem for communication. API is asynchronous. Application can get results from CellularContext callback, which is set with attach(...), or callback, which is set by attach(...), in this class.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on case of memory failure

Open the SIM card by setting the pin code for SIM.

Parameters

sim_pin

PIN for the SIM card

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_PARAMETER if sim_pin is null and sim is not ready NSAPI_ERROR_DEVICE_ERROR on failure

Implements CellularDevice.

Plmn to use when registering to cellular network.

If plmn is set, then registering is forced to this plmn. If plmn is not set, then automatic registering is used when registering to a cellular network. It doesn't start any operations.

Parameters

plmn	plmn used when registering to cellular network

Set power save mode.

Remarks

See 3GPP TS 27.007 PSM for details

Parameters

periodic_time	in seconds to enable power save, or zero to disable
active_time	in seconds to wait before entering power save mode

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implements CellularDevice.

Set callback function to listen when device is ready.

Parameters

callback

function to call on device ready, or NULL to remove callback.

Implements CellularDevice.

Set an array of timeouts to wait before CellularStateMachine retries after failure.

To disable retry behavior completely use set_retry_timeout_array(NULL, 0). CellularContext callback event cell_callback_data_t.final_try indicates true when all retries have failed.

Remarks

Use set_retry_timeout_array for CellularStateMachine to wait before it retries again after failure, this is useful to send repetitive requests when don't know exactly when modem is ready to accept requests. Use set_timeout for timeout how long to wait for a response from modem for each request, this is useful if modem can accept requests but processing takes long time before sending response.

Parameters

timeout	timeout array using seconds
array_len	length of the array

Set the pin code for SIM card.

Parameters

sim_pin

PIN for the SIM card

Start the interface.

Attempts to open the sim. API is asynchronous. Application can get results from CellularContext callback, which is set with attach(...), or callback, which is set by attach(...), in this class.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_NO_MEMORY on case of memory failure

Set the default response timeout.

Remarks

CellularStateMachine timeouts for all states are also changed to timeout.

Parameters

timeout

milliseconds to wait response from modem

Implements CellularDevice.

Shutdown cellular device to minimum functionality.

Actual functionality is modem specific, for example UART may is not be responsive without explicit wakeup signal (such as RTS) after shutdown.

Remarks

You must call shutdown before power off to prepare the modem and to quit cellular network.

Returns

NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Reimplemented from CellularDevice.

Powers down the modem.

This is equivalent to turning off the modem by button press.

Remarks

CellularStateMachine disconnect or destruct does not shutdown or power off the modem, but you need to do that yourself.

Precondition

You must call shutdown to prepare the modem for power off.

Returns

NSAPI_ERROR_OK on success

Implements CellularDevice.

Powers up the modem.

This is equivalent to pressing the "power button" to activate or reset the modem and usually implemented as a short pulse on a dedicated GPIO signal. It is expected to be present to make it possible to reset the modem. The driver may repeat this if the modem is not responsive to AT commands.

Remarks

CellularStateMachine calls this when requested to connect. If you are not using CellularStateMachine then you need to call this function yourself.

Postcondition

You must call init to setup the modem.

Returns

NSAPI_ERROR_OK on success

Implements CellularDevice.

Stop the current operation.

Operations: set_device_ready, set_sim_ready, register_to_network, attach_to_network