Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
CellularDevice Class Reference
[Cellular]
Class CellularDevice. More...
#include <CellularDevice.h>
Inherited by AT_CellularDevice.
Public Member Functions | |
CellularDevice (FileHandle *fh) | |
Default constructor. | |
virtual | ~CellularDevice () |
virtual Destructor | |
virtual nsapi_error_t | clear () |
Clear modem to a default initial state. | |
virtual nsapi_error_t | shutdown () |
Shutdown cellular device to minimum functionality. | |
virtual CellularContext * | get_context_list () const |
Get the linked list of CellularContext instances. | |
virtual events::EventQueue * | get_queue () |
Get event queue that can be chained to main event queue. | |
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. | |
virtual nsapi_error_t | hard_power_off ()=0 |
Sets the modem in unplugged state. | |
virtual nsapi_error_t | soft_power_on ()=0 |
Powers up the modem. | |
virtual nsapi_error_t | soft_power_off ()=0 |
Powers down the modem. | |
virtual nsapi_error_t | set_pin (const char *sim_pin)=0 |
Open the SIM card by setting the pin code for SIM. | |
virtual nsapi_error_t | get_sim_state (SimState &state)=0 |
Get SIM card's state. | |
virtual CellularContext * | create_context (FileHandle *fh=NULL, const char *apn=NULL, bool cp_req=false, bool nonip_req=false)=0 |
Creates a new CellularContext interface. | |
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)=0 |
Creates a new CellularContext interface. | |
virtual void | delete_context (CellularContext *context)=0 |
Deletes the given CellularContext instance. | |
virtual void | modem_debug_on (bool on)=0 |
Turn modem debug traces on. | |
virtual nsapi_error_t | init ()=0 |
Initialize cellular device must be called right after the module is ready. | |
virtual nsapi_error_t | is_ready ()=0 |
Check whether the device is ready to accept commands. | |
virtual void | set_ready_cb (Callback< void()> callback)=0 |
Set callback function to listen when device is ready. | |
virtual nsapi_error_t | set_power_save_mode (int periodic_time, int active_time=0)=0 |
Set power save mode. | |
virtual ATHandler * | get_at_handler ()=0 |
Get the current ATHandler instance in use for debug purposes etc. | |
virtual nsapi_error_t | release_at_handler (ATHandler *at_handler)=0 |
Release the ATHandler taken into use with get_at_handler() | |
virtual nsapi_error_t | set_baud_rate (int baud_rate)=0 |
Sets cellular modem to given baud rate. | |
virtual CellularNetwork * | open_network (FileHandle *fh=NULL)=0 |
Create new CellularNetwork interface. | |
virtual CellularSMS * | open_sms (FileHandle *fh=NULL)=0 |
Create new CellularSMS interface. | |
virtual void | close_sms ()=0 |
Closes the opened CellularSMS by deleting the CellularSMS instance. | |
virtual CellularInformation * | open_information (FileHandle *fh=NULL)=0 |
Create new CellularInformation interface. | |
virtual void | close_network ()=0 |
Closes the opened CellularNetwork by deleting the CellularNetwork instance. | |
virtual void | close_information ()=0 |
Closes the opened CellularInformation by deleting the CellularInformation instance. | |
virtual void | set_timeout (int timeout)=0 |
Set the default response timeout. | |
MBED_DEPRECATED_SINCE ("mbed-os-5.15","Use CellularDevice::shutdown() instead.") void stop() | |
Stop the current operation. | |
FileHandle & | get_file_handle () const |
Get the current FileHandle item used when communicating with the modem. | |
void | set_sim_pin (const char *sim_pin) |
Set the pin code for SIM card. | |
void | set_plmn (const char *plmn) |
Plmn to use when registering to cellular network. | |
nsapi_error_t | set_device_ready () |
Start the interface. | |
nsapi_error_t | set_sim_ready () |
Start the interface. | |
nsapi_error_t | register_to_network () |
Start the interface. | |
nsapi_error_t | attach_to_network () |
Start the interface. | |
void | attach (Callback< void(nsapi_event_t, intptr_t)> status_cb) |
Register callback for status reporting. | |
void | set_retry_timeout_array (const uint16_t timeout[], int array_len) |
Set an array of timeouts to wait before CellularStateMachine retries after failure. | |
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. | |
static CellularDevice * | get_target_default_instance () |
Return target onboard instance of CellularDevice. | |
Protected Member Functions | |
virtual void | cellular_callback (nsapi_event_t ev, intptr_t ptr, CellularContext *ctx=NULL) |
Cellular callback to be attached to Network and CellularStateMachine classes. | |
void | get_retry_timeout_array (uint16_t *timeout, int &array_len) const |
Get the retry array from the CellularStateMachine. |
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
CellularDevice | ( | FileHandle * | fh ) |
Default constructor.
- Parameters:
-
fh File handle used in communication with the modem.
Definition at line 36 of file CellularDevice.cpp.
~CellularDevice | ( | ) | [virtual] |
virtual Destructor
Definition at line 48 of file CellularDevice.cpp.
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_cb The callback for status changes.
Definition at line 175 of file CellularDevice.cpp.
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
Definition at line 117 of file CellularDevice.cpp.
void cellular_callback | ( | nsapi_event_t | ev, |
intptr_t | ptr, | ||
CellularContext * | ctx = NULL |
||
) | [protected, virtual] |
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.
Definition at line 185 of file CellularDevice.cpp.
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.
Definition at line 257 of file CellularDevice.cpp.
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:
-
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
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:
-
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
Implemented in AT_CellularDevice.
virtual void delete_context | ( | CellularContext * | context ) | [pure virtual] |
Deletes the given CellularContext instance.
- Parameters:
-
context CellularContext 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.
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.
Definition at line 70 of file CellularDevice.cpp.
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
Definition at line 160 of file STModCellular.cpp.
FileHandle & get_file_handle | ( | ) | const |
Get the current FileHandle item used when communicating with the modem.
- Returns:
- reference to FileHandle
Definition at line 60 of file CellularDevice.cpp.
events::EventQueue * get_queue | ( | ) | [virtual] |
Get event queue that can be chained to main event queue.
- Returns:
- event queue
Definition at line 65 of file CellularDevice.cpp.
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:
-
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
Definition at line 75 of file CellularDevice.cpp.
virtual nsapi_error_t get_sim_state | ( | SimState & | state ) | [pure virtual] |
Get SIM card's state.
- Parameters:
-
state current state of SIM
- Returns:
- NSAPI_ERROR_OK on success NSAPI_ERROR_DEVICE_ERROR on failure
Implemented in AT_CellularDevice.
MBED_WEAK 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
Definition at line 31 of file CellularDevice.cpp.
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.
MBED_DEPRECATED_SINCE | ( | "mbed-os-5.15" | , |
"Use CellularDevice::shutdown() instead." | |||
) |
Stop the current operation.
Operations: set_device_ready, set_sim_ready, register_to_network, attach_to_network
virtual void modem_debug_on | ( | bool | on ) | [pure virtual] |
Turn modem debug traces on.
- Parameters:
-
on set true to enable debug traces
Implemented in AT_CellularDevice.
virtual CellularInformation* open_information | ( | FileHandle * | fh = NULL ) |
[pure virtual] |
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.
Implemented in AT_CellularDevice.
virtual CellularNetwork* open_network | ( | FileHandle * | fh = NULL ) |
[pure virtual] |
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.
Implemented in AT_CellularDevice.
virtual CellularSMS* open_sms | ( | FileHandle * | fh = NULL ) |
[pure virtual] |
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.
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
Definition at line 112 of file CellularDevice.cpp.
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.
virtual nsapi_error_t set_baud_rate | ( | int | baud_rate ) | [pure virtual] |
Sets cellular modem to given baud rate.
- Parameters:
-
baud_rate
- Returns:
- NSAPI_ERROR_OK on success, NSAPI_ERROR_DEVICE_ERROR 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
Definition at line 102 of file CellularDevice.cpp.
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_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
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:
-
plmn plmn used when registering to cellular network
Definition at line 92 of file CellularDevice.cpp.
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_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
Implemented in AT_CellularDevice.
virtual void set_ready_cb | ( | Callback< void()> | callback ) | [pure virtual] |
Set callback function to listen when device is ready.
- Parameters:
-
callback function 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:
-
timeout timeout array using seconds array_len length of the array
Definition at line 250 of file CellularDevice.cpp.
void set_sim_pin | ( | const char * | sim_pin ) |
Set the pin code for SIM card.
- Parameters:
-
sim_pin PIN for the SIM card
Definition at line 82 of file CellularDevice.cpp.
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
Definition at line 107 of file CellularDevice.cpp.
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:
-
timeout milliseconds to wait response from modem
Implemented in AT_CellularDevice.
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.
Definition at line 234 of file CellularDevice.cpp.
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.
Generated on Tue Jul 12 2022 13:55:42 by
