upsv

Embed: (wiki syntax)

« Back to documentation index

UbloxCellularBase Class Reference

UbloxCellularBase class. More...

#include <UbloxCellularBase.h>

Data Structures

struct  DeviceInfo
 Info about the modem. More...

Public Types

enum  NetworkRegistrationStatusCsd
 

Circuit Switched network registration status (CREG Usage).

More...
enum  NetworkRegistrationStatusPsd
 

Packet Switched network registration status (CGREG Usage).

More...
enum  NetworkRegistrationStatusEps
 

EPS network registration status (CEREG Usage).

More...
enum  ModemPSMState
 

modem PSM states.

More...
enum  RAT
 

RAT values for +URAT command R412M only supports value 7 (CatM1), 8 (NB1), and 9 (GPRS)

More...
enum  FunctionalityMode
 

Module functionality modes.

More...
enum  MNOProfile
 

Supported MNO profiles for SARA-R4.

More...

Public Member Functions

bool init (const char *pin=0)
 Initialise the modem, ready for use.
bool nwk_registration ()
 Perform registration with the network.
bool is_registered_csd ()
 True if the modem is registered for circuit switched data, otherwise false.
bool is_registered_psd ()
 True if the modem is registered for packet switched data, otherwise false.
bool is_registered_eps ()
 True if the modem is registered for enhanced packet switched data (i.e.
bool nwk_deregistration ()
 Perform deregistration from the network.
void deinit ()
 Put the modem into its lowest power state.
void set_pin (const char *pin)
 Set the PIN code for the SIM card.
bool sim_pin_check_enable (bool enableNotDisable)
 Enable or disable SIM pin checking.
bool change_sim_pin (const char *new_pin)
 Change the SIM pin.
 MBED_DEPRECATED ("This method is now replaced by const char * imei(), please use that instead") bool get_imei(char *imei_to_send
 Get the IMEI.
const char * imei ()
 Get the IMEI of the module.
const char * meid ()
 Get the Mobile Equipment ID (which may be the same as the IMEI).
const char * imsi ()
 Get the IMSI of the SIM.
const char * iccid ()
 Get the ICCID of the SIM.
int rssi ()
 Get the RSSI.
bool set_mno_profile (MNOProfile profile=DEFAULT_MNO_PROFILE)
 Reads the current MNO profile from modem and sets it to user specified profile.
bool get_mno_profile (int *profile)
 Get current MNO profile.
bool set_idle_mode (bool enable=false)
 Enable or disable the UPSV Power Saving Mode.
bool get_idle_mode (int *status)
 Queries the modem for idle mode status.
bool set_modem_rat (RAT selected_rat, RAT preferred_rat=NOT_USED, RAT second_preferred_rat=NOT_USED)
 Set Radio Access Technology on modem.
bool get_modem_rat (int *selected_rat, int *preferred_rat, int *second_preferred_rat)
 Get last saved values for RAT using +URAT read command.
bool set_functionality_mode (FunctionalityMode mode)
 Sets the modem to specified functionality mode.
bool get_functionality_mode (int *mode)
 Get the modem functionality mode.
bool reboot_modem ()
 reboot the modem using AT+CFUN=15.
void attach_cb_psm_going_in (Callback< void(void *)> func, void *param)
 Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
void attach_cb_psm_coming_out (Callback< void(void *)> func, void *param)
 Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
void detach_cb_psm_going_in ()
 de-register the application callback for modem going in to PSM sleep
void detach_cb_psm_coming_out ()
 de-register application callback for modem coming out of PSM sleep
bool set_power_saving_mode (int periodic_tau, int active_time)
 Enable or disable the 3GPP PSM.
bool get_power_saving_mode (int *status, int *periodic_tau, int *active_time)
 Reads the 3GPP PSM status (enabled or disabled) and returns assigned periodic tau and active time values.
void wakeup_modem ()
 Wake up the modem from PSM.
bool is_modem_awake ()
 True if the modem is not in PSM sleep otherwise false.

Protected Types

enum  DeviceType
 

Supported u-blox modem variants.

More...
enum  RadioAccessNetworkType
 

Network registration status.

More...

Protected Member Functions

virtual void modem_init ()
 Sets the modem up for powering on.
virtual void modem_deinit ()
 Sets the modem in unplugged state.
virtual void modem_power_up ()
 Powers up the modem.
virtual void modem_power_down ()
 Powers down the modem.
void baseClassInit (PinName tx=MDMTXD, PinName rx=MDMRXD, int baud=MBED_CONF_UBLOX_CELL_BAUD_RATE, bool debug_on=false)
 Initialise this class.
void at_set_timeout (int timeout)
 Set the AT parser timeout.
int read_at_to_char (char *buf, int size, char end)
 Read up to size characters from buf or until the character "end" is reached, overwriting the newline with 0 and ensuring a terminator in all cases.
bool power_up ()
 Powers up the modem.
void power_down ()
 Power down the modem.
void lock (void)
 Lock a mutex when accessing the modem.
void unlock (void)
 Unlock the modem when done accessing it.
bool set_device_identity (DeviceType *dev)
 Set the device identity in _dev_info based on the ATI string returned by the module.
bool device_init (DeviceType dev)
 Perform any modem initialisation that is specialised by device type.
bool initialise_sim_card ()
 Set up the SIM.
void uint_to_binary_str (uint32_t num, char *str, int str_size, int bit_cnt)
 Converts the given uint to binary string.

Protected Attributes

UbloxATCmdParser * _at
 Point to the instance of the AT parser in use.
int _at_timeout
 The current AT parser timeout value.
FileHandle * _fh
 File handle used by the AT parser.
Mutex _mtx
 The mutex resource.
DeviceInfo _dev_info
 General info about the modem as a device.
const char * _pin
 The SIM PIN to use.
bool _debug_trace_on
 Set to true to spit out debug traces.
int _baud
 The baud rate to the modem.
bool _modem_initialised
 True if the modem is ready register to the network, otherwise false.
bool _sim_pin_check_enabled
 True it the SIM requires a PIN, otherwise false.

Detailed Description

UbloxCellularBase class.

This class provides all the base support for generic u-blox modems on C030 and C027 boards: module identification, power-up, network registration, etc.

Definition at line 34 of file UbloxCellularBase.h.


Member Enumeration Documentation

enum DeviceType [protected]

Supported u-blox modem variants.

Definition at line 425 of file UbloxCellularBase.h.

Module functionality modes.

Ref to section 5.3.3 of UBX-13002752 for details.

Definition at line 204 of file UbloxCellularBase.h.

enum MNOProfile

Supported MNO profiles for SARA-R4.

Definition at line 220 of file UbloxCellularBase.h.

modem PSM states.

Definition at line 81 of file UbloxCellularBase.h.

Circuit Switched network registration status (CREG Usage).

UBX-13001820 - AT Commands Example Application Note (Section 7.10.3).

Definition at line 40 of file UbloxCellularBase.h.

EPS network registration status (CEREG Usage).

UBX-13001820 - AT Commands Example Application Note (Section 18.36.3).

Definition at line 68 of file UbloxCellularBase.h.

Packet Switched network registration status (CGREG Usage).

UBX-13001820 - AT Commands Example Application Note (Section 18.27.3).

Definition at line 55 of file UbloxCellularBase.h.

enum RadioAccessNetworkType [protected]

Network registration status.

UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5).

Definition at line 440 of file UbloxCellularBase.h.

enum RAT

RAT values for +URAT command R412M only supports value 7 (CatM1), 8 (NB1), and 9 (GPRS)

Definition at line 188 of file UbloxCellularBase.h.


Member Function Documentation

void at_set_timeout ( int  timeout ) [protected]

Set the AT parser timeout.

Definition at line 564 of file UbloxCellularBase.cpp.

void attach_cb_psm_coming_out ( Callback< void(void *)>  func,
void *  param 
)

Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.

It is recommended to set a flag/event/signal in callback and application can use that to wake up the modem and re-initialize it

application callback for modem coming out of PSM sleep

Parameters:
funccallback function to be executed when modem is coming out of PSM sleep.
paramparameter to be passed to callback function.

Definition at line 340 of file UbloxCellularBase.h.

void attach_cb_psm_going_in ( Callback< void(void *)>  func,
void *  param 
)

Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.

It is recommended to set a flag/event/signal in callback and application can use that to wake up the modem and re-initialize it

application callback for modem going in to PSM sleep

Parameters:
funccallback function to be executed when modem is going in to PSM sleep
paramparameter to be passed to callback function.

Definition at line 326 of file UbloxCellularBase.h.

void baseClassInit ( PinName  tx = MDMTXD,
PinName  rx = MDMRXD,
int  baud = MBED_CONF_UBLOX_CELL_BAUD_RATE,
bool  debug_on = false 
) [protected]

Initialise this class.

Parameters:
txthe UART TX data pin to which the modem is attached.
rxthe UART RX data pin to which the modem is attached.
baudthe UART baud rate.
debug_ontrue to switch AT interface debug on, otherwise false.

Note: it would be more natural to do this in the constructor however, to avoid the diamond of death, this class is only every inherited virtually. Classes that are inherited virtually do not get passed parameters in their constructor and hence classInit() must be called separately by the first one to wake the beast.

Definition at line 513 of file UbloxCellularBase.cpp.

bool change_sim_pin ( const char *  new_pin )

Change the SIM pin.

Parameters:
new_pinthe new PIN to use.
Returns:
true if successful, otherwise false.
void deinit (  )

Put the modem into its lowest power state.

void detach_cb_psm_coming_out (  )

de-register application callback for modem coming out of PSM sleep

Definition at line 358 of file UbloxCellularBase.h.

void detach_cb_psm_going_in (  )

de-register the application callback for modem going in to PSM sleep

Definition at line 349 of file UbloxCellularBase.h.

bool device_init ( DeviceType  dev ) [protected]

Perform any modem initialisation that is specialised by device type.

Returns:
true if successful, otherwise false.

Definition at line 724 of file UbloxCellularBase.cpp.

bool get_functionality_mode ( int *  mode )

Get the modem functionality mode.

Returns:
true if successful, otherwise false.
bool get_idle_mode ( int *  status )

Queries the modem for idle mode status.

Parameters:
statuspointer to variable that can hold the value for idle mode status 1: enabled 0: disabled
Returns:
true if successful, otherwise false.
bool get_mno_profile ( int *  profile )

Get current MNO profile.

Parameters:
profilepointer to variable that can hold the value for returned profile
Returns:
true if operation was successful, false if there was an error
bool get_modem_rat ( int *  selected_rat,
int *  preferred_rat,
int *  second_preferred_rat 
)

Get last saved values for RAT using +URAT read command.

Note: The current selected RAT is indicated by DeviceInfo.rat

Parameters:
selected_ratpointer to variable that can hold the value for selected_rat
preferred_ratpointer to variable that can hold the value for preferred_rat
second_preferred_ratpointer to variable that can hold the value for second_preferred_rat

Note: NOT_USED will be returned in the variables if dual or tri modes are not enabled.

Returns:
true if successful, otherwise false.
bool get_power_saving_mode ( int *  status,
int *  periodic_tau,
int *  active_time 
)

Reads the 3GPP PSM status (enabled or disabled) and returns assigned periodic tau and active time values.

Parameters:
status0: PSM disabled, 1: PSM enabled
periodic_tauassigned periodic TAU in seconds.
active_timeassigned active time in seconds
Returns:
True if command successful, otherwise false.
const char* iccid (  )

Get the ICCID of the SIM.

Returns:
a pointer to the ICCID as a null-terminated string.
const char* imei (  )

Get the IMEI of the module.

Returns:
a pointer to the IMEI as a null-terminated string.
const char* imsi (  )

Get the IMSI of the SIM.

Returns:
a pointer to the IMSI as a null-terminated string.
bool init ( const char *  pin = 0 )

Initialise the modem, ready for use.

Parameters:
pinPIN for the SIM card.
Returns:
true if successful, otherwise false.

Table 10.5.163a/3GPP TS 24.008: GPRS Timer 3 information element

Bits 5 to 1 represent the binary coded timer value.

Bits 6 to 8 defines the timer value unit for the GPRS timer as follows: 8 7 6 0 0 0 value is incremented in multiples of 10 minutes 0 0 1 value is incremented in multiples of 1 hour 0 1 0 value is incremented in multiples of 10 hours 0 1 1 value is incremented in multiples of 2 seconds 1 0 0 value is incremented in multiples of 30 seconds 1 0 1 value is incremented in multiples of 1 minute 1 1 0 value is incremented in multiples of 320 hours (NOTE 1) 1 1 1 value indicates that the timer is deactivated (NOTE 2).

Table 10.5.172/3GPP TS 24.008: GPRS Timer information element

Bits 5 to 1 represent the binary coded timer value.

Bits 6 to 8 defines the timer value unit for the GPRS timer as follows:

8 7 6 0 0 0 value is incremented in multiples of 2 seconds 0 0 1 value is incremented in multiples of 1 minute 0 1 0 value is incremented in multiples of decihours 1 1 1 value indicates that the timer is deactivated.

Other values shall be interpreted as multiples of 1 minute in this version of the protocol.

Definition at line 799 of file UbloxCellularBase.cpp.

bool initialise_sim_card (  ) [protected]

Set up the SIM.

Returns:
true if successful, otherwiss false.

Definition at line 744 of file UbloxCellularBase.cpp.

bool is_modem_awake (  )

True if the modem is not in PSM sleep otherwise false.

bool is_registered_csd (  )

True if the modem is registered for circuit switched data, otherwise false.

bool is_registered_eps (  )

True if the modem is registered for enhanced packet switched data (i.e.

LTE and beyond), otherwise false.

bool is_registered_psd (  )

True if the modem is registered for packet switched data, otherwise false.

void lock ( void   ) [protected]

Lock a mutex when accessing the modem.

Definition at line 605 of file UbloxCellularBase.h.

MBED_DEPRECATED ( "This method is now replaced by const char *   imei(),
please use that instead"   
)

Get the IMEI.

Returns:
true if successful, otherwise false.
const char* meid (  )

Get the Mobile Equipment ID (which may be the same as the IMEI).

Returns:
a pointer to the Mobile Equipment ID as a null-terminated string.
void modem_deinit (  ) [protected, virtual]

Sets the modem in unplugged state.

modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power and serial port. This puts the modem in lowest power state. Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.

Definition at line 440 of file UbloxCellularBase.cpp.

void modem_init (  ) [protected, virtual]

Sets the modem up for powering on.

modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port. Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.

Definition at line 435 of file UbloxCellularBase.cpp.

void modem_power_down (  ) [protected, virtual]

Powers down the modem.

modem_power_down() is equivalent to turning off the modem by button press. Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.

Definition at line 450 of file UbloxCellularBase.cpp.

void modem_power_up (  ) [protected, virtual]

Powers up the modem.

modem_power_up() is equivalent to pressing the soft power button. The driver may repeat this if the modem is not responsive to AT commands. Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.

Definition at line 445 of file UbloxCellularBase.cpp.

bool nwk_deregistration (  )

Perform deregistration from the network.

Returns:
true if successful, otherwise false.
bool nwk_registration (  )

Perform registration with the network.

Returns:
true if successful, otherwise false.
void power_down (  ) [protected]

Power down the modem.

Definition at line 662 of file UbloxCellularBase.cpp.

bool power_up (  ) [protected]

Powers up the modem.

Returns:
true if successful, otherwise false.

Definition at line 602 of file UbloxCellularBase.cpp.

int read_at_to_char ( char *  buf,
int  size,
char  end 
) [protected]

Read up to size characters from buf or until the character "end" is reached, overwriting the newline with 0 and ensuring a terminator in all cases.

Parameters:
bufthe buffer to write to.
sizethe size of the buffer.
endthe character to stop at.
Returns:
the number of characters read, not including the terminator.

Definition at line 574 of file UbloxCellularBase.cpp.

bool reboot_modem (  )

reboot the modem using AT+CFUN=15.

Application should call init() or connect() before making any other API calls.

Returns:
true if successful, otherwise false.
int rssi (  )

Get the RSSI.

Returns:
the RSSI in dBm. If it is not possible to obtain an RSSI reading at the time (e.g. because the modem is in data mode rather than AT command mode) then 0 is returned.
bool set_device_identity ( DeviceType dev ) [protected]

Set the device identity in _dev_info based on the ATI string returned by the module.

Returns:
true if dev is a known value, otherwise false.

Definition at line 690 of file UbloxCellularBase.cpp.

bool set_functionality_mode ( FunctionalityMode  mode )

Sets the modem to specified functionality mode.

Returns:
true if successful, otherwise false.
bool set_idle_mode ( bool  enable = false )

Enable or disable the UPSV Power Saving Mode.

Parameters:
idle_mode_value1: enable idle mode 0: disable idle mode
Returns:
true if successful, otherwise false.
bool set_mno_profile ( MNOProfile  profile = DEFAULT_MNO_PROFILE )

Reads the current MNO profile from modem and sets it to user specified profile.

User can also specify profile in mbed_lib.json file and call set_mno_profile without any arguments.

Note: MNO profile should only be set in detached state and a reboot is required for settings to take effect

Parameters:
profileMNO profile to use
Returns:
true if operation was successful, false if there was an error
bool set_modem_rat ( RAT  selected_rat,
RAT  preferred_rat = NOT_USED,
RAT  second_preferred_rat = NOT_USED 
)

Set Radio Access Technology on modem.

Note: RAT should only be set in detached state and a reboot is required for settings to take effect

Parameters:
selected_ratRadio Access Technology to use
preferred_ratRadio Access Technology to use if selected_rat is not available
second_preferred_ratRadio Access Technology to use if selected_rat and preferred_rat are not available
Returns:
true if successful, otherwise false.
void set_pin ( const char *  pin )

Set the PIN code for the SIM card.

Parameters:
pinPIN for the SIM card.
bool set_power_saving_mode ( int  periodic_tau,
int  active_time 
)

Enable or disable the 3GPP PSM.

Note: Application should reboot the module after enabling PSM in order to enter PSM state. (reboot_modem()) Note: Modem can be woken up by toggling the power-on signal. (wakeup_modem()) Note: When device enters PSM, all connections(PPP, sockets) and settings that are not saved in NV memory(ATE0, CREG etc) are lost. host application should be prepared to re-initialize the modem and re-establish the connections. Note: PSM is disabled if both periodic_time and active_time are 0. Note: Not all variants/firmware versions support PSM URCs and in that case function will return false.

PSM string encoding code is borrowed from AT_CellularPower.cpp

Parameters:
periodic_timerequested periodic TAU in seconds.
active_timerequested active time in seconds.
funccallback function to execute when modem goes to sleep
ptrparameter to callback function
Returns:
True if successful, otherwise false.
bool sim_pin_check_enable ( bool  enableNotDisable )

Enable or disable SIM pin checking.

Parameters:
enableNotDisabletrue if SIM PIN checking is to be enabled, otherwise false.
Returns:
true if successful, otherwise false.
void uint_to_binary_str ( uint32_t  num,
char *  str,
int  str_size,
int  bit_cnt 
) [protected]

Converts the given uint to binary string.

Fills the given str starting from [0] with the number of bits defined by bit_cnt For example uint_to_binary_string(9, str, 10) would fill str "0000001001" For example uint_to_binary_string(9, str, 3) would fill str "001"

Parameters:
numuint to converts to binary string
strbuffer for converted binary string
str_sizesize of the str buffer
bit_cntdefines how many bits are filled to buffer started from lsb
void unlock ( void   ) [protected]

Unlock the modem when done accessing it.

Definition at line 613 of file UbloxCellularBase.h.

void wakeup_modem (  )

Wake up the modem from PSM.

Ref to comment on set_power_saving_mode, application should call init() or connect() before making any other API calls.


Field Documentation

UbloxATCmdParser* _at [protected]

Point to the instance of the AT parser in use.

Definition at line 479 of file UbloxCellularBase.h.

int _at_timeout [protected]

The current AT parser timeout value.

Definition at line 486 of file UbloxCellularBase.h.

int _baud [protected]

The baud rate to the modem.

Definition at line 510 of file UbloxCellularBase.h.

bool _debug_trace_on [protected]

Set to true to spit out debug traces.

Definition at line 506 of file UbloxCellularBase.h.

DeviceInfo _dev_info [protected]

General info about the modem as a device.

Definition at line 498 of file UbloxCellularBase.h.

FileHandle* _fh [protected]

File handle used by the AT parser.

Definition at line 490 of file UbloxCellularBase.h.

bool _modem_initialised [protected]

True if the modem is ready register to the network, otherwise false.

Definition at line 515 of file UbloxCellularBase.h.

Mutex _mtx [protected]

The mutex resource.

Definition at line 494 of file UbloxCellularBase.h.

const char* _pin [protected]

The SIM PIN to use.

Definition at line 502 of file UbloxCellularBase.h.

bool _sim_pin_check_enabled [protected]

True it the SIM requires a PIN, otherwise false.

Definition at line 519 of file UbloxCellularBase.h.