#include <AT_CellularDevice.h>

Inheritance diagram for AT_CellularDevice:

Public Member Functions
	AT_CellularDevice (FileHandle fh, char const delim="\r")
	Create an AT_CellularDevice. More...

virtual nsapi_error_t	clear ()
	Clear modem to a default initial state. More...

virtual nsapi_error_t	hard_power_on ()
	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 ()
	Sets the modem in unplugged state. More...

virtual nsapi_error_t	soft_power_on ()
	Powers up the modem. More...

virtual nsapi_error_t	soft_power_off ()
	Powers down the modem. More...

virtual nsapi_error_t	set_pin (const char *sim_pin)
	Open the SIM card by setting the pin code for SIM. More...

virtual nsapi_error_t	get_sim_state (SimState &state)
	Get SIM card's state. More...

virtual CellularContext *	create_context (const char *apn=NULL, bool cp_req=false, bool nonip_req=false)
	Creates a new CellularContext interface. More...

virtual void	delete_context (CellularContext *context)
	Deletes the given CellularContext instance. More...

virtual CellularNetwork *	open_network ()
	Create new CellularNetwork interface. More...

virtual CellularInformation *	open_information ()
	Create new CellularInformation interface. More...

virtual void	close_network ()
	Closes the opened CellularNetwork by deleting the CellularNetwork instance. More...

virtual void	close_information ()
	Closes the opened CellularInformation by deleting the CellularInformation instance. More...

virtual void	set_timeout (int timeout)
	Set the default response timeout. More...

virtual void	modem_debug_on (bool on)
	Turn modem debug traces on. More...

virtual nsapi_error_t	init ()
	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 ()
	Check whether the device is ready to accept commands. More...

virtual void	set_ready_cb (Callback< void()> callback)
	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)
	Set power save mode. More...

virtual ATHandler *	get_at_handler ()
	Get the current ATHandler instance in use for debug purposes etc. More...

virtual CellularContext *	get_context_list () const
	Get the linked list of CellularContext instances. More...

virtual nsapi_error_t	set_baud_rate (int baud_rate)
	Sets cellular modem to given baud rate. More...

intptr_t	get_property (CellularProperty key)
	Get value for the given key. More...

void	set_cellular_properties (const intptr_t *property_array)
	Cellular module need to define an array of cellular properties which defines module supported property values. More...

virtual events::EventQueue *	get_queue ()
	Get event queue that can be chained to main event queue. More...

virtual CellularSMS *	open_sms ()=0
	Create new CellularSMS interface. More...

virtual void	close_sms ()=0
	Closes the opened CellularSMS by deleting the CellularSMS instance. 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...

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

Static Public Member Functions
static CellularDevice *	get_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 CellularDevice *	get_target_default_instance ()
	Return target onboard instance of CellularDevice. More...

Protected Member Functions
virtual AT_CellularContext *	create_context_impl (ATHandler &at, const char *apn, bool cp_req=false, bool nonip_req=false)
	Creates new instance of AT_CellularContext or if overridden, modem specific implementation. More...

virtual AT_CellularNetwork *	open_network_impl (ATHandler &at)
	Create new instance of AT_CellularNetwork or if overridden, modem specific implementation. More...

virtual AT_CellularInformation *	open_information_impl (ATHandler &at)
	Create new instance of AT_CellularInformation or if overridden, modem specific implementation. 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...

void	get_retry_timeout_array (uint16_t *timeout, int &array_len) const
	Get the retry array from the CellularStateMachine. More...

Detailed Description

Class AT_CellularDevice.

A class defines opening and closing of cellular interfaces. Deleting/Closing of opened interfaces can be done only through this class.

Definition at line 44 of file AT_CellularDevice.h.

Constructor & Destructor Documentation

◆ AT_CellularDevice()

AT_CellularDevice	(	FileHandle *	fh,
		char const *	delim = `"\r"`
	)

Create an AT_CellularDevice.

Parameters

fh	file handle used for reading AT responses and writing AT commands
delim	delimiter used when parsing at responses, "\r" should be used as output_delimiter

Member Function Documentation

◆ clear()

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

Implements CellularDevice.

◆ hard_power_on()

virtual nsapi_error_t hard_power_on ( )

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

Implements CellularDevice.

Reimplemented in ONBOARD_SARA4_PPP, ONBOARD_TELIT_HE910, ONBOARD_TELIT_HE910, ONBOARD_TELIT_ME310, TELIT_ME310, ONBOARD_TELIT_ME910, and TELIT_ME910.

◆ hard_power_off()

virtual nsapi_error_t hard_power_off ( )

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

Implements CellularDevice.

Reimplemented in ONBOARD_SARA4_PPP, ONBOARD_TELIT_HE910, ONBOARD_TELIT_HE910, ONBOARD_TELIT_ME310, TELIT_ME310, ONBOARD_TELIT_ME910, and TELIT_ME910.

◆ soft_power_on()

virtual nsapi_error_t soft_power_on ( )

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

Implements CellularDevice.

Reimplemented in ALT1250_PPP, ONBOARD_SARA4_PPP, ONBOARD_TELIT_HE910, ONBOARD_TELIT_HE910, ONBOARD_TELIT_ME310, TELIT_ME310, ONBOARD_TELIT_ME910, and TELIT_ME910.

◆ soft_power_off()

virtual nsapi_error_t soft_power_off ( )

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

Implements CellularDevice.

Reimplemented in ONBOARD_SARA4_PPP, ONBOARD_TELIT_HE910, ONBOARD_TELIT_HE910, ONBOARD_TELIT_ME310, TELIT_ME310, ONBOARD_TELIT_ME910, and TELIT_ME910.

◆ set_pin()

virtual nsapi_error_t set_pin ( const char * sim_pin )

virtual

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.

◆ get_sim_state()

virtual nsapi_error_t get_sim_state ( SimState & state )

virtual

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.

◆ create_context()

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

virtual

Creates a new CellularContext interface.

Parameters

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.

◆ delete_context()

virtual void delete_context ( CellularContext * context )

virtual

Deletes the given CellularContext instance.

Parameters

context CellularContext to delete

Implements CellularDevice.

◆ open_network()

virtual CellularNetwork * open_network ( )

virtual

Create new CellularNetwork interface.

Returns: New instance of interface CellularNetwork.

Implements CellularDevice.

◆ open_information()

virtual CellularInformation * open_information ( )

virtual

Create new CellularInformation interface.

Returns: New instance of interface CellularInformation.

Implements CellularDevice.

◆ close_network()

virtual void close_network ( )

virtual

Closes the opened CellularNetwork by deleting the CellularNetwork instance.

Implements CellularDevice.

◆ close_information()

virtual void close_information ( )

virtual

Closes the opened CellularInformation by deleting the CellularInformation instance.

Implements CellularDevice.

◆ set_timeout()

virtual void set_timeout ( int timeout )

virtual

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.

◆ modem_debug_on()

virtual void modem_debug_on ( bool on )

virtual

Turn modem debug traces on.

Parameters

on	set true to enable debug traces

Implements CellularDevice.

◆ init()

virtual nsapi_error_t init ( )

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

Implements CellularDevice.

Reimplemented in GEMALTO_CINTERION, RM1000_AT, TELIT_HE910, ONBOARD_TELIT_ME310, TELIT_ME310, ONBOARD_TELIT_ME910, and TELIT_ME910.

◆ shutdown()

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 from CellularDevice.

◆ is_ready()

virtual nsapi_error_t is_ready ( )

virtual

Check whether the device is ready to accept commands.

Returns: NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure

Implements CellularDevice.

◆ set_ready_cb()

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

virtual

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_power_save_mode()

virtual nsapi_error_t set_power_save_mode	(	int	periodic_time,
		int	active_time = `0`
	)

virtual

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.

Reimplemented in SARA4_PPP.

◆ get_at_handler()

virtual ATHandler * get_at_handler ( )

virtual

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

Returns: Pointer to the ATHandler in use, NULL if device is non-AT -device.

Implements CellularDevice.

◆ get_context_list()

virtual CellularContext * get_context_list ( ) const

virtual

Get the linked list of CellularContext instances.

Returns: Pointer to first item in linked list

Implements CellularDevice.

◆ set_baud_rate()

virtual nsapi_error_t set_baud_rate ( int baud_rate )

virtual

Sets cellular modem to given baud rate.

Parameters

baud_rate

Returns: NSAPI_ERROR_OK on success, NSAPI_ERROR_DEVICE_ERROR on failure

Implements CellularDevice.

◆ get_property()

intptr_t get_property ( CellularProperty key )

Get value for the given key.

Parameters

key	key for value to be fetched

Returns: property value for the given key. Value type is defined in enum CellularProperty

◆ set_cellular_properties()

void set_cellular_properties ( const intptr_t * property_array )

Cellular module need to define an array of cellular properties which defines module supported property values.

Parameters

property_array array of module properties

◆ create_context_impl()

virtual AT_CellularContext * create_context_impl	(	ATHandler &	at,
		const char *	apn,
		bool	cp_req = `false`,
		bool	nonip_req = `false`
	)

protectedvirtual

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

Reimplemented in ALT1250_PPP, GEMALTO_CINTERION, RM1000_AT, TELIT_ME310, and TELIT_ME910.

◆ open_network_impl()

virtual AT_CellularNetwork * open_network_impl ( ATHandler & at )

protectedvirtual

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

Reimplemented in ALT1250_PPP, SARA4_PPP, RM1000_AT, TELIT_ME310, and TELIT_ME910.

◆ open_information_impl()

virtual AT_CellularInformation * open_information_impl ( ATHandler & at )

protectedvirtual

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

Reimplemented in GEMALTO_CINTERION.

◆ cellular_callback()

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 from CellularDevice.

◆ get_default_instance()

static CellularDevice * get_default_instance ( )

staticinherited

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_target_default_instance()

static CellularDevice * get_target_default_instance ( )

staticinherited

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

◆ get_queue()

virtual events::EventQueue * get_queue ( )

virtualinherited

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

Returns: event queue

◆ open_sms()

virtual CellularSMS * open_sms ( )

pure virtualinherited

Create new CellularSMS interface.

Returns: New instance of interface CellularSMS.

◆ close_sms()

virtual void close_sms ( )

pure virtualinherited

Closes the opened CellularSMS by deleting the CellularSMS instance.

◆ set_sim_pin()

void set_sim_pin ( const char * sim_pin )

inherited

Set the pin code for SIM card.

Parameters

sim_pin PIN for the SIM card

◆ set_plmn()

void set_plmn ( const char * plmn )

inherited

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_device_ready()

nsapi_error_t set_device_ready ( )

inherited

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

◆ set_sim_ready()

nsapi_error_t set_sim_ready ( )

inherited

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

◆ register_to_network()

nsapi_error_t register_to_network ( )

inherited

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

◆ attach_to_network()

nsapi_error_t attach_to_network ( )

inherited

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

◆ attach()

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

inherited

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.

◆ set_retry_timeout_array()

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

inherited

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

◆ get_retry_timeout_array()

void get_retry_timeout_array	(	uint16_t *	timeout,
		int &	array_len
	)		const

protectedinherited

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ AT_CellularDevice()

Member Function Documentation

◆ clear()

◆ hard_power_on()

◆ hard_power_off()

◆ soft_power_on()

◆ soft_power_off()

◆ set_pin()

◆ get_sim_state()

◆ create_context()

◆ delete_context()

◆ open_network()

◆ open_information()

◆ close_network()

◆ close_information()

◆ set_timeout()

◆ modem_debug_on()

◆ init()

◆ shutdown()

◆ is_ready()

◆ set_ready_cb()

◆ set_power_save_mode()

◆ get_at_handler()

◆ get_context_list()

◆ set_baud_rate()

◆ get_property()

◆ set_cellular_properties()

◆ create_context_impl()

◆ open_network_impl()

◆ open_information_impl()

◆ cellular_callback()

◆ get_default_instance()

◆ get_target_default_instance()

◆ get_queue()

◆ open_sms()

◆ close_sms()

◆ set_sim_pin()

◆ set_plmn()

◆ set_device_ready()

◆ set_sim_ready()

◆ register_to_network()

◆ attach_to_network()

◆ attach()

◆ set_retry_timeout_array()

◆ get_retry_timeout_array()