Mistake on this page?
Report an issue in GitHub or email us
Public Member Functions | Static Public Member Functions | Protected Member Functions
CellularDevice Class Referenceabstract

Class CellularDevice. More...

#include <CellularDevice.h>

Inheritance diagram for CellularDevice:
AT_CellularDevice

Public Member Functions

 CellularDevice (FileHandle *fh)
 Default constructor. More...
 
virtual ~CellularDevice ()
 virtual Destructor More...
 
virtual nsapi_error_t clear ()
 Clear modem to a default initial state. More...
 
virtual nsapi_error_t hard_power_on ()=0
 Sets the modem up for powering on This is equivalent to plugging in the device, i.e., attaching power and serial port. More...
 
virtual nsapi_error_t hard_power_off ()=0
 Sets the modem in unplugged state. More...
 
virtual nsapi_error_t soft_power_on ()=0
 Powers up the modem. More...
 
virtual nsapi_error_t soft_power_off ()=0
 Powers down the modem. More...
 
virtual nsapi_error_t set_pin (const char *sim_pin)=0
 Open the SIM card by setting the pin code for SIM. More...
 
virtual nsapi_error_t get_sim_state (SimState &state)=0
 Get SIM card's state. More...
 
virtual CellularContextcreate_context (FileHandle *fh=NULL, const char *apn=NULL, bool cp_req=false, bool nonip_req=false)=0
 Creates a new CellularContext interface. More...
 
virtual CellularContextcreate_context (UARTSerial *serial, const char *apn, PinName dcd_pin=NC, bool active_high=false, bool cp_req=false, bool nonip_req=false)=0
 Creates a new CellularContext interface. More...
 
virtual void delete_context (CellularContext *context)=0
 Deletes the given CellularContext instance. More...
 
void stop ()
 Stop the current operation. More...
 
FileHandleget_file_handle () const
 Get the current FileHandle item used when communicating with the modem. More...
 
virtual events::EventQueueget_queue ()
 Get event queue that can be chained to main event queue. More...
 
void set_sim_pin (const char *sim_pin)
 Set the pin code for SIM card. More...
 
void set_plmn (const char *plmn)
 Plmn to use when registering to cellular network. More...
 
nsapi_error_t set_device_ready ()
 Start the interface. More...
 
nsapi_error_t set_sim_ready ()
 Start the interface. More...
 
nsapi_error_t register_to_network ()
 Start the interface. More...
 
nsapi_error_t attach_to_network ()
 Start the interface. More...
 
void attach (Callback< void(nsapi_event_t, intptr_t)> status_cb)
 Register callback for status reporting. More...
 
virtual CellularNetworkopen_network (FileHandle *fh=NULL)=0
 Create new CellularNetwork interface. More...
 
virtual CellularSMSopen_sms (FileHandle *fh=NULL)=0
 Create new CellularSMS interface. More...
 
virtual CellularInformationopen_information (FileHandle *fh=NULL)=0
 Create new CellularInformation interface. More...
 
virtual void close_network ()=0
 Closes the opened CellularNetwork by deleting the CellularNetwork instance. More...
 
virtual void close_sms ()=0
 Closes the opened CellularSMS by deleting the CellularSMS instance. More...
 
virtual void close_information ()=0
 Closes the opened CellularInformation by deleting the CellularInformation instance. More...
 
virtual void set_timeout (int timeout)=0
 Set the default response timeout. More...
 
void set_retry_timeout_array (const uint16_t timeout[], int array_len)
 Set an array of timeouts to wait before CellularStateMachine retries after failure. More...
 
virtual void modem_debug_on (bool on)=0
 Turn modem debug traces on. More...
 
virtual nsapi_error_t init ()=0
 Initialize cellular device must be called right after the module is ready. More...
 
virtual nsapi_error_t shutdown ()
 Shutdown cellular device to minimum functionality. More...
 
virtual nsapi_error_t is_ready ()=0
 Check whether the device is ready to accept commands. More...
 
virtual void set_ready_cb (Callback< void()> callback)=0
 Set callback function to listen when device is ready. More...
 
virtual nsapi_error_t set_power_save_mode (int periodic_time, int active_time=0)=0
 Set power save mode. More...
 
virtual CellularContextget_context_list () const
 Get the linked list of CellularContext instances. More...
 
virtual ATHandlerget_at_handler ()=0
 Get the current ATHandler instance in use for debug purposes etc. More...
 
virtual nsapi_error_t release_at_handler (ATHandler *at_handler)=0
 Release the ATHandler taken into use with get_at_handler() More...
 

Static Public Member Functions

static CellularDeviceget_default_instance ()
 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. More...
 
static CellularDeviceget_target_default_instance ()
 Return target onboard instance of CellularDevice. More...
 

Protected Member Functions

void get_retry_timeout_array (uint16_t *timeout, int &array_len) const
 Get the retry array from the CellularStateMachine. More...
 
virtual void cellular_callback (nsapi_event_t ev, intptr_t ptr, CellularContext *ctx=NULL)
 Cellular callback to be attached to Network and CellularStateMachine classes. More...
 

Detailed Description

Class CellularDevice.

An abstract interface that defines opening and closing of cellular interfaces. You can delete or close opened interfaces only through this class.

Definition at line 55 of file CellularDevice.h.

Constructor & Destructor Documentation

Default constructor.

Parameters
fhFile handle used in communication with the modem.
virtual ~CellularDevice ( )
virtual

virtual Destructor

Member Function Documentation

void attach ( Callback< void(nsapi_event_t, intptr_t)>  status_cb)

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_cbThe callback for status changes.
nsapi_error_t attach_to_network ( )

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
virtual void cellular_callback ( nsapi_event_t  ev,
intptr_t  ptr,
CellularContext ctx = NULL 
)
protectedvirtual

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 in AT_CellularDevice.

virtual nsapi_error_t clear ( )
virtual

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 in AT_CellularDevice.

virtual void close_information ( )
pure virtual

Closes the opened CellularInformation by deleting the CellularInformation instance.

Implemented in AT_CellularDevice.

virtual void close_network ( )
pure virtual

Closes the opened CellularNetwork by deleting the CellularNetwork instance.

Implemented in AT_CellularDevice.

virtual void close_sms ( )
pure virtual

Closes the opened CellularSMS by deleting the CellularSMS instance.

Implemented in AT_CellularDevice.

virtual CellularContext* create_context ( FileHandle fh = NULL,
const char *  apn = NULL,
bool  cp_req = false,
bool  nonip_req = false 
)
pure virtual

Creates a new CellularContext interface.

Parameters
fhfile handle used in communication to modem. This can be, for example, UART handle. If null, then the default file handle is used.
apnaccess point to use with context, can be null.
cp_reqflag indicating if EPS control plane optimization is required
nonip_reqflag indicating if this context is required to be Non-IP
Returns
new instance of class CellularContext or NULL in case of failure

Implemented in AT_CellularDevice.

virtual CellularContext* create_context ( UARTSerial serial,
const char *  apn,
PinName  dcd_pin = NC,
bool  active_high = false,
bool  cp_req = false,
bool  nonip_req = false 
)
pure virtual

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
serialUARTSerial used in communication to modem. If null then the default file handle is used.
apnaccess point to use with context, can be null.
dcd_pinPin used to set data carrier detect on/off for the given UART
active_higha boolean set to true if DCD polarity is active low
cp_reqFlag indicating if EPS control plane optimization is required
nonip_reqFlag indicating if this context is required to be Non-IP
Returns
new instance of class CellularContext or NULL in case of failure

Implemented in AT_CellularDevice.

virtual void delete_context ( CellularContext context)
pure virtual

Deletes the given CellularContext instance.

Parameters
contextCellularContext to delete

Implemented in AT_CellularDevice.

virtual ATHandler* get_at_handler ( )
pure virtual

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

Implemented in AT_CellularDevice.

virtual CellularContext* get_context_list ( ) const
virtual

Get the linked list of CellularContext instances.

Returns
Pointer to first item in linked list

Reimplemented in AT_CellularDevice.

static CellularDevice* get_default_instance ( )
static

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
FileHandle& get_file_handle ( ) const

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

Returns
reference to FileHandle
virtual events::EventQueue* get_queue ( )
virtual

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

Returns
event queue
void get_retry_timeout_array ( uint16_t *  timeout,
int &  array_len 
) const
protected

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
timeouttimeout array containing seconds for retry logic. Must have space for CELLULAR_RETRY_ARRAY_SIZE (defined in CellularCommon.h)
array_lenlength of the timeout array on return
virtual nsapi_error_t get_sim_state ( SimState &  state)
pure virtual

Get SIM card's state.

Parameters
statecurrent state of SIM
Returns
NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularDevice.

static CellularDevice* get_target_default_instance ( )
static

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
virtual nsapi_error_t hard_power_off ( )
pure virtual

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

Implemented in AT_CellularDevice.

virtual nsapi_error_t hard_power_on ( )
pure virtual

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

Implemented in AT_CellularDevice.

virtual nsapi_error_t init ( )
pure virtual

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

Implemented in AT_CellularDevice.

virtual nsapi_error_t is_ready ( )
pure virtual

Check whether the device is ready to accept commands.

Returns
NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularDevice.

virtual void modem_debug_on ( bool  on)
pure virtual

Turn modem debug traces on.

Parameters
onset true to enable debug traces

Implemented in AT_CellularDevice.

virtual CellularInformation* open_information ( FileHandle fh = NULL)
pure virtual

Create new CellularInformation interface.

Parameters
fhfile 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.

Implemented in AT_CellularDevice.

virtual CellularNetwork* open_network ( FileHandle fh = NULL)
pure virtual

Create new CellularNetwork interface.

Parameters
fhfile 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.

Implemented in AT_CellularDevice.

virtual CellularSMS* open_sms ( FileHandle fh = NULL)
pure virtual

Create new CellularSMS interface.

Parameters
fhfile 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.

Implemented in AT_CellularDevice.

nsapi_error_t register_to_network ( )

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
virtual nsapi_error_t release_at_handler ( ATHandler at_handler)
pure virtual

Release the ATHandler taken into use with get_at_handler()

Parameters
at_handler
Returns
NSAPI_ERROR_OK on success, NSAPI_ERROR_PARAMETER on failure

Implemented in AT_CellularDevice.

nsapi_error_t set_device_ready ( )

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
virtual nsapi_error_t set_pin ( const char *  sim_pin)
pure virtual

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

Parameters
sim_pinPIN 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

Implemented in AT_CellularDevice.

void set_plmn ( const char *  plmn)

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
plmnplmn used when registering to cellular network
virtual nsapi_error_t set_power_save_mode ( int  periodic_time,
int  active_time = 0 
)
pure virtual

Set power save mode.

Remarks
See 3GPP TS 27.007 PSM for details
Parameters
periodic_timein seconds to enable power save, or zero to disable
active_timein seconds to wait before entering power save mode
Returns
NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implemented in AT_CellularDevice.

virtual void set_ready_cb ( Callback< void()>  callback)
pure virtual

Set callback function to listen when device is ready.

Parameters
callbackfunction to call on device ready, or NULL to remove callback.

Implemented in AT_CellularDevice.

void set_retry_timeout_array ( const uint16_t  timeout[],
int  array_len 
)

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
timeouttimeout array using seconds
array_lenlength of the array
void set_sim_pin ( const char *  sim_pin)

Set the pin code for SIM card.

Parameters
sim_pinPIN for the SIM card
nsapi_error_t set_sim_ready ( )

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
virtual void set_timeout ( int  timeout)
pure virtual

Set the default response timeout.

Remarks
CellularStateMachine timeouts for all states are also changed to timeout.
Parameters
timeoutmilliseconds to wait response from modem

Implemented in AT_CellularDevice.

virtual nsapi_error_t shutdown ( )
virtual

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 in AT_CellularDevice.

virtual nsapi_error_t soft_power_off ( )
pure virtual

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

Implemented in AT_CellularDevice.

virtual nsapi_error_t soft_power_on ( )
pure virtual

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

Implemented in AT_CellularDevice.

void stop ( )

Stop the current operation.

Operations: set_device_ready, set_sim_ready, register_to_network, attach_to_network

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.