UbloxCellularBase.h

00001 /* Copyright (c) 2019 ARM Limited
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef _UBLOX_CELLULAR_BASE_
00017 #define _UBLOX_CELLULAR_BASE_
00018 
00019 #include "mbed.h"
00020 #include "mbed_toolchain.h" // for MBED_DEPRECATED
00021 #include "ubloxATCmdParser.h"
00022 #include "FileHandle.h"
00023 
00024 #ifdef TARGET_UBLOX_C030_R410M
00025 #define MAX_NUM_PROFILES 12 //ref to enum MNOProfile
00026 #elif TARGET_UBLOX_C030_R412M
00027 #define MAX_NUM_PROFILES 7
00028 #endif
00029 
00030 /**********************************************************************
00031  * CLASSES
00032  **********************************************************************/
00033 
00034 /** UbloxCellularBase class.
00035  *
00036  *  This class provides all the base support for generic u-blox modems
00037  *  on C030 and C027 boards: module identification, power-up, network
00038  *  registration, etc.
00039  */
00040 class UbloxCellularBase {
00041 
00042 public:
00043     /** Circuit Switched network registration status (CREG Usage).
00044      * UBX-13001820 - AT Commands Example Application Note (Section 7.10.3).
00045      */
00046     typedef enum {
00047         CSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00048         CSD_REGISTERED = 1,
00049         CSD_NOT_REGISTERED_SEARCHING = 2,
00050         CSD_REGISTRATION_DENIED = 3,
00051         CSD_UNKNOWN_COVERAGE = 4,
00052         CSD_REGISTERED_ROAMING = 5,
00053         CSD_SMS_ONLY = 6,
00054         CSD_SMS_ONLY_ROAMING = 7,
00055         CSD_CSFB_NOT_PREFERRED = 9
00056     } NetworkRegistrationStatusCsd;
00057 
00058     /** Packet Switched network registration status (CGREG Usage).
00059      * UBX-13001820 - AT Commands Example Application Note (Section 18.27.3).
00060      */
00061     typedef enum {
00062         PSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00063         PSD_REGISTERED = 1,
00064         PSD_NOT_REGISTERED_SEARCHING = 2,
00065         PSD_REGISTRATION_DENIED = 3,
00066         PSD_UNKNOWN_COVERAGE = 4,
00067         PSD_REGISTERED_ROAMING = 5,
00068         PSD_EMERGENCY_SERVICES_ONLY = 8
00069     } NetworkRegistrationStatusPsd;
00070 
00071     /** EPS network registration status (CEREG Usage).
00072      * UBX-13001820 - AT Commands Example Application Note (Section 18.36.3).
00073      */
00074     typedef enum {
00075         EPS_NOT_REGISTERED_NOT_SEARCHING = 0,
00076         EPS_REGISTERED = 1,
00077         EPS_NOT_REGISTERED_SEARCHING = 2,
00078         EPS_REGISTRATION_DENIED = 3,
00079         EPS_UNKNOWN_COVERAGE = 4,
00080         EPS_REGISTERED_ROAMING = 5,
00081         EPS_EMERGENCY_SERVICES_ONLY = 8
00082     } NetworkRegistrationStatusEps;
00083 
00084     /** modem PSM states.
00085      *
00086      */
00087     typedef enum {
00088         AWAKE = 0,
00089         ASLEEP = 1
00090     } ModemPSMState;
00091 
00092     /**
00093      * edrx access technology
00094      */
00095     typedef enum {
00096         EDRXGSM_EC_GSM_IoT_mode = 1,
00097         EDRXGSM_A_Gb_mode,
00098         EDRXUTRAN_Iu_mode,
00099         EDRXEUTRAN_WB_S1_mode,
00100         EDRXEUTRAN_NB_S1_mode
00101     }tEDRXAccessTechnology;
00102 
00103 #ifdef TARGET_UBLOX_C030_R41XM
00104     /** Supported MNO profiles for SARA-R4.
00105      */
00106     typedef enum {
00107         SW_DEFAULT = 0,
00108         SIM_ICCID = 1,
00109         ATT = 2,
00110         TMO = 5,
00111         VODAFONE = 19,
00112         DT = 31,
00113         STANDARD_EU = 100
00114 #ifdef TARGET_UBLOX_C030_R410M
00115         , VERIZON = 3,
00116         TELSTRA = 4,
00117         CT = 6,
00118         SPRINT = 8,
00119         TELUS = 21
00120 #endif
00121     } MNOProfile;
00122 
00123     typedef enum {
00124         UBANDMASK_RAT_LTE_CATM1 = 0,
00125         UBANDMASK_RAT_LTE_CATNB1 = 1
00126 
00127     } UBandmaskRAT;
00128 #endif
00129 
00130     /** Initialise the modem, ready for use.
00131      *
00132      *  @param pin     PIN for the SIM card.
00133      *  @return        true if successful, otherwise false.
00134      */
00135     bool init(const char *pin = 0);
00136 
00137     /** Perform registration with the network.
00138      *
00139      * @return true if successful, otherwise false.
00140      */
00141     bool nwk_registration();
00142 
00143     /** True if the modem is registered for circuit
00144      * switched data, otherwise false.
00145      */
00146     bool is_registered_csd();
00147 
00148     /** True if the modem is registered for packet
00149      * switched data, otherwise false.
00150      */
00151     bool is_registered_psd();
00152 
00153     /** True if the modem is registered for enhanced
00154      * packet switched data (i.e. LTE and beyond),
00155      * otherwise false.
00156      */
00157     bool is_registered_eps();
00158 
00159     /** Perform deregistration from the network.
00160      *
00161      * @return true if successful, otherwise false.
00162      */
00163     bool nwk_deregistration();
00164 
00165     /** Put the modem into its lowest power state.
00166      */
00167     void deinit();
00168 
00169     /** Set the PIN code for the SIM card.
00170      *
00171      *  @param pin PIN for the SIM card.
00172      */
00173     void set_pin(const char *pin);
00174 
00175     /** Enable or disable SIM pin checking.
00176      *
00177      * @param enableNotDisable true if SIM PIN checking is to be enabled,
00178      *                         otherwise false.
00179      * @return                 true if successful, otherwise false.
00180      */
00181     bool sim_pin_check_enable(bool enableNotDisable);
00182 
00183     /** Change the SIM pin.
00184      *
00185      * @param new_pin the new PIN to use.
00186      * @return        true if successful, otherwise false.
00187      */
00188     bool change_sim_pin(const char *new_pin);
00189 
00190     /** Get the IMEI.
00191      *
00192      * @return true if successful, otherwise false.
00193      */
00194     MBED_DEPRECATED("This method is now replaced by const char * imei(), please use that instead")
00195     bool get_imei(char *imei_to_send, int size);
00196 
00197     /** Get the IMEI of the module.
00198      *
00199      * @return a pointer to the IMEI as a null-terminated string.
00200      */
00201     const char *imei();
00202 
00203     /** Get the Mobile Equipment ID (which may be the same as the IMEI).
00204      *
00205      * @return a pointer to the Mobile Equipment ID as a null-terminated string.
00206      */
00207     const char *meid();
00208 
00209     /** Get the IMSI of the SIM.
00210      *
00211      * @return a pointer to the IMSI as a null-terminated string.
00212      */
00213     const char *imsi();
00214 
00215     /** Get the ICCID of the SIM.
00216      *
00217      * @return a pointer to the ICCID as a null-terminated string.
00218      */
00219     const char *iccid();
00220 
00221     /** Get the RSSI.
00222      *
00223      * @return the RSSI in dBm. If it is not possible to obtain an
00224      *         RSSI reading at the time (e.g. because the modem is in
00225      *         data mode rather than AT command mode) then 0 is returned.
00226      */
00227     int rssi();
00228 
00229     /** RAT values for +URAT command
00230      * R412M only supports value 7 (CatM1), 8 (NB1), and 9 (GPRS)
00231      */
00232     typedef enum {
00233         GSM_GPRS_EGPRS = 0,
00234         GSM_UMTS = 1,
00235         UMTS = 2,
00236         URAT_LTE = 3,
00237         GSM_UMTS_LTE = 4,
00238         GSM_LTE = 5,
00239         UMTS_LTE = 6,
00240         LTE_CATM1 = 7,
00241         LTE_CATNB1 = 8,
00242         GPRS_EGPRS = 9,
00243         NOT_USED = -1
00244     } RAT;
00245 
00246     /** Module functionality modes. Ref to section 5.3.3 of UBX-13002752 for details.
00247      */
00248     typedef enum {
00249         FUNC_MIN = 0,
00250         FUNC_FULL = 1,
00251         FUNC_AIRPLANE = 4,
00252         FUNC_EN_SIM_TLKT_DEDICATED = 6,
00253         FUNC_DS_SIM_TLKT = 7,
00254         FUNC_EN_SIM_TLKT_RAW = 9,
00255         FUNC_RESET = 15,
00256         FUNC_RESET_WITH_SIM = 16,
00257         FUNC_MIN_WITH_SIM = 19,
00258         FUNC_HALT = 127
00259     } FunctionalityMode;
00260 
00261 #ifdef TARGET_UBLOX_C030_R41XM
00262 
00263     #if MBED_CONF_UBLOX_CELL_DEFAULT_MNO_PROFILE
00264     #define DEFAULT_MNO_PROFILE     (MNOProfile)MBED_CONF_UBLOX_CELL_DEFAULT_MNO_PROFILE
00265     #else
00266     #define DEFAULT_MNO_PROFILE     STANDARD_EU
00267     #endif
00268 
00269     /** Reads the current MNO profile from modem and sets it to user specified profile.
00270      * User can also specify profile in mbed_lib.json file and call set_mno_profile without any arguments.
00271      *
00272      * Note: MNO profile should only be set in detached state and a reboot is required for settings to take effect
00273      * Note 2: ref to UBX-17003787 B.5, setting MNO profile can change other parameters such as PSM, Band mask, URAT etc.
00274      *         Application must always set a profile first and if required, change parameters afterwards.
00275      * Note 3: ref to UBX-17003787 B.5, some profiles have locked parameters and modem will return ERROR if you try to change those.
00276      *         It is suggested to switch to a profile e.g. STANDARD_EU (100) and then change the parameters as required.
00277      * @param profile MNO profile to use
00278      * @return    true if operation was successful, false if there was an error
00279      */
00280     bool set_mno_profile(MNOProfile profile = DEFAULT_MNO_PROFILE);
00281 
00282     /** Get current MNO profile.
00283      *
00284      * @param profile pointer to variable that can hold the value for returned profile
00285      * @return    true if operation was successful, false if there was an error
00286      */
00287     bool get_mno_profile(int *profile);
00288 
00289     /** Enable or disable the UPSV Power Saving Mode.
00290      *
00291      * @param idle_mode_value  1: enable idle mode
00292      *                         0: disable idle mode
00293      * @return                 true if successful, otherwise false.
00294      */
00295     bool set_idle_mode(bool enable = false);
00296 
00297     /** Queries the modem for idle mode status.
00298      *
00299      * @param status pointer to variable that can hold the value for idle mode status
00300      *                         1: enabled
00301      *                         0: disabled
00302      * @return                 true if successful, otherwise false.
00303      */
00304     bool get_idle_mode(int *status);
00305 #endif
00306 
00307     /** Set Radio Access Technology on modem.
00308      *
00309      * Note: RAT should only be set in detached state and a reboot is required for settings to take effect
00310      *
00311      * @param selected_rat Radio Access Technology to use
00312      * @param preferred_rat Radio Access Technology to use if selected_rat is not available
00313      * @param second_preferred_rat Radio Access Technology to use if selected_rat and preferred_rat are not available
00314      *
00315      * @return        true if successful, otherwise false.
00316      */
00317     bool set_modem_rat(RAT selected_rat, RAT preferred_rat = NOT_USED, RAT second_preferred_rat = NOT_USED);
00318 
00319     /** Get last saved values for RAT using +URAT read command. Note: The current selected RAT is indicated by DeviceInfo.rat
00320      *
00321      * @param selected_rat pointer to variable that can hold the value for selected_rat
00322      * @param preferred_rat pointer to variable that can hold the value for preferred_rat
00323      * @param second_preferred_rat pointer to variable that can hold the value for second_preferred_rat
00324      *
00325      * Note: NOT_USED will be returned in the variables if dual or tri modes are not enabled.
00326      *
00327      * @return        true if successful, otherwise false.
00328      */
00329     bool get_modem_rat(int *selected_rat, int *preferred_rat, int *second_preferred_rat);
00330 
00331     /** Sets the modem to specified functionality mode.
00332      *
00333      * @return true if successful, otherwise false.
00334      */
00335     bool set_functionality_mode(FunctionalityMode mode);
00336 
00337     /** Get the modem functionality mode
00338      *
00339      * @return true if successful, otherwise false.
00340      */
00341     bool get_functionality_mode(int *mode);
00342 
00343     /** reboot the modem using AT+CFUN=15. Application should call init() or connect() before making any other API calls.
00344      *
00345      * @return        true if successful, otherwise false.
00346      */
00347     bool reboot_modem();
00348 
00349 #ifdef TARGET_UBLOX_C030_R412M
00350     /** Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
00351      * 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
00352      *
00353      * application callback for modem going in to PSM sleep
00354      *
00355      * @param func     callback function to be executed when modem is going in to PSM sleep
00356      * @param param    parameter to be passed to callback function.
00357      */
00358     void attach_cb_psm_going_in(Callback<void(void*)> func, void *param)
00359     {
00360         _func_psm_going_in = func;
00361         _cb_param_psm_going_in = param;
00362     }
00363 
00364     /** Important: Callback function is executed in context of AT parser so a user should not issue any AT commands from inside the callback.
00365      * 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
00366      *
00367      * application callback for modem coming out of PSM sleep
00368      *
00369      * @param func     callback function to be executed when modem is coming out of PSM sleep.
00370      * @param param    parameter to be passed to callback function.
00371      */
00372     void attach_cb_psm_coming_out(Callback<void(void*)> func, void *param)
00373     {
00374         _func_psm_coming_out = func;
00375         _cb_param_psm_coming_out = param;
00376     }
00377 
00378     /** de-register the application callback for modem going in to PSM sleep
00379      *
00380      */
00381     void detach_cb_psm_going_in()
00382     {
00383         _func_psm_going_in = NULL;
00384         _cb_param_psm_going_in = NULL;
00385     }
00386 
00387     /** de-register application callback for modem coming out of PSM sleep
00388      *
00389      */
00390     void detach_cb_psm_coming_out()
00391     {
00392         _func_psm_coming_out = NULL;
00393         _cb_param_psm_coming_out = NULL;
00394     }
00395 
00396     /** Enable or disable the 3GPP PSM.
00397      *
00398      *  Note: Application should reboot the module after enabling PSM in order to enter PSM state. (reboot_modem())
00399      *  Note: Modem can be woken up by toggling the power-on signal. (wakeup_modem())
00400      *  Note: When device enters PSM, all connections(PPP, sockets) and settings that are not saved in NV memory(ATE0, CREG etc) are lost.
00401      *        host application should be prepared to re-initialize the modem and re-establish the connections.
00402      *  Note: PSM is disabled if both periodic_time and active_time are 0.
00403      *  Note: Not all variants/firmware versions support PSM URCs and in that case function will return false.
00404      *
00405      *  PSM string encoding code is borrowed from AT_CellularPower.cpp
00406      *
00407      * @param periodic_time    requested periodic TAU in seconds.
00408      * @param active_time      requested active time in seconds.
00409      * @param func             callback function to execute when modem goes to sleep
00410      * @param ptr              parameter to callback function
00411      * @return         True if successful, otherwise false.
00412      */
00413     bool set_power_saving_mode(int periodic_tau, int active_time);
00414 
00415     /** Reads the 3GPP PSM status (enabled or disabled) and returns assigned periodic tau and active time values.
00416      *
00417      * @param status           0: PSM disabled, 1: PSM enabled
00418      * @param periodic_tau     assigned periodic TAU in seconds.
00419      * @param active_time      assigned active time in seconds
00420      * @return         True if command successful, otherwise false.
00421      */
00422     bool get_power_saving_mode(int *status, int *periodic_tau, int *active_time);
00423 
00424     /** Wake up the modem from PSM. Ref to comment on set_power_saving_mode, application should call init() or connect()
00425      * before making any other API calls.
00426      */
00427     void wakeup_modem();
00428 
00429     /** True if the modem is not in PSM sleep
00430      * otherwise false.
00431      */
00432     bool is_modem_awake();
00433 #endif
00434 
00435 #ifdef TARGET_UBLOX_C030_R41XM
00436     /** Set discontinuous reception time on cellular device.
00437      * SARA-R404M / SARA-R410M-02B / SARA-R410M-52B / SARA-R412M / SARA-N4 : The <Paging_time_window> parameter cannot be set by means of the set command.
00438      *
00439      *
00440      *  @remark See 3GPP TS 27.007 eDRX for details.
00441      *
00442      *  @param mode          disable or enable the use of eDRX
00443      *  @param act_type      type of access technology
00444      *  @param edrx_value    requested edxr value. Extended DRX parameters information element.
00445      *
00446      *  @return              0 on success
00447      *                       1 on failure
00448      */
00449     int set_receive_period(int mode, tEDRXAccessTechnology act_type, uint8_t edrx_value);
00450 
00451     /** Set discontinuous reception time on cellular device.
00452      *
00453      *  @remark See 3GPP TS 27.007 eDRX for details.
00454      *
00455      *  @param mode          disable or enable the use of eDRX
00456      *  @param act_type      type of access technology
00457      *
00458      *  @return              0 on success
00459      *                       1 on failure
00460      */
00461     int set_receive_period(int mode, tEDRXAccessTechnology act_type);
00462 
00463     /** Set discontinuous reception time on cellular device. (Disable)
00464      *
00465      *  @remark See 3GPP TS 27.007 eDRX for details.
00466      *
00467      *  @param mode          disable or enable the use of eDRX
00468      *
00469      *  @return              0 on success
00470      *                       1 on failure
00471      */
00472     int set_receive_period(int mode);
00473 
00474     /** get discontinuous reception time on cellular device.
00475      *
00476      *  @remark See 3GPP TS 27.007 eDRX for details.
00477      *
00478      *  @return              uint32_t
00479      */
00480     uint32_t get_receive_period();
00481 
00482     /** set band select bitmask
00483      *
00484      *  @param RAT        RAT type
00485      *  @param bitmask    bitmask
00486      *  @return           True if successful, otherwise false.
00487      */
00488     bool set_band_bitmask(RAT rat, uint64_t bitmask);
00489 
00490     /** get band select bitmasks
00491      *
00492      *  @param m1_bitmask     pointer to band select bitmask of M1
00493      *  @param nb1_bitmask    pointer to band select bitmask of NB1
00494      *  @return           True if successful, otherwise false.
00495      */
00496     bool get_band_bitmask(uint64_t *m1_bitmask, uint64_t *nb1_bitmask);
00497 
00498     /** disables the PSM
00499      *
00500      *  @return           True if successful, otherwise false.
00501      */
00502     bool disable_psm();
00503 #endif
00504 
00505 protected:
00506 
00507     #define OUTPUT_ENTER_KEY  "\r"
00508 
00509     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00510     #define AT_PARSER_BUFFER_SIZE   MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00511     #else
00512     #define AT_PARSER_BUFFER_SIZE   256
00513     #endif
00514 
00515     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00516     #define AT_PARSER_TIMEOUT       MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00517     #else
00518     #define AT_PARSER_TIMEOUT       8*1000 // Milliseconds
00519     #endif
00520 
00521     /** A string that would not normally be sent by the modem on the AT interface.
00522      */
00523     #define UNNATURAL_STRING "\x01"
00524 
00525     /** Supported u-blox modem variants.
00526      */
00527     typedef enum {
00528         DEV_TYPE_NONE = 0,
00529         DEV_SARA_G35,
00530         DEV_LISA_U2,
00531         DEV_LISA_U2_03S,
00532         DEV_SARA_U2,
00533         DEV_SARA_R4,
00534         DEV_LEON_G2,
00535         DEV_TOBY_L2,
00536         DEV_MPCI_L2
00537     } DeviceType;
00538 
00539     /** Network registration status.
00540      * UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5).
00541      */
00542     typedef enum {
00543        GSM = 0,
00544        COMPACT_GSM = 1,
00545        UTRAN = 2,
00546        EDGE = 3,
00547        HSDPA = 4,
00548        HSUPA = 5,
00549        HSDPA_HSUPA = 6,
00550        LTE = 7,
00551        EC_GSM_IoT = 8,
00552        E_UTRAN_NB_S1 = 9
00553     } RadioAccessNetworkType;
00554 
00555     /** Info about the modem.
00556      */
00557     typedef struct {
00558         DeviceType dev;
00559         char iccid[20 + 1];   //!< Integrated Circuit Card ID.
00560         char imsi[15 + 1];    //!< International Mobile Station Identity.
00561         char imei[15 + 1];    //!< International Mobile Equipment Identity.
00562         char meid[18 + 1];    //!< Mobile Equipment IDentifier.
00563         volatile RadioAccessNetworkType rat;  //!< Type of network (e.g. 2G, 3G, LTE).
00564         volatile NetworkRegistrationStatusCsd reg_status_csd; //!< Circuit switched attach status.
00565         volatile NetworkRegistrationStatusPsd reg_status_psd; //!< Packet switched attach status.
00566         volatile NetworkRegistrationStatusEps reg_status_eps; //!< Evolved Packet Switched (e.g. LTE) attach status.
00567 #ifdef TARGET_UBLOX_C030_R412M
00568         volatile ModemPSMState modem_psm_state; //!< last known modem PSM state
00569 #endif
00570     } DeviceInfo;
00571 
00572     /* IMPORTANT: the variables below are available to
00573      * classes that inherit this in order to keep things
00574      * simple. However, ONLY this class should free
00575      * any of the pointers, or there will be havoc.
00576      */
00577 
00578     /** Point to the instance of the AT parser in use.
00579      */
00580 #ifdef TARGET_UBLOX_C030_R41XM
00581     UbloxATCmdParser *_at;
00582 #else
00583     ATCmdParser *_at;
00584 #endif
00585 
00586     /** The current AT parser timeout value.
00587      */
00588     int _at_timeout;
00589 
00590     /** File handle used by the AT parser.
00591      */
00592     FileHandle *_fh;
00593 
00594     /** The mutex resource.
00595      */
00596     Mutex _mtx;
00597 
00598     /** General info about the modem as a device.
00599      */
00600     DeviceInfo _dev_info;
00601 
00602     /** The SIM PIN to use.
00603      */
00604     const char *_pin;
00605 
00606     /** Set to true to spit out debug traces.
00607      */
00608     bool _debug_trace_on;
00609     
00610     /** The baud rate to the modem.
00611      */
00612     int _baud;
00613 
00614     /** True if the modem is ready register to the network,
00615      * otherwise false.
00616      */
00617     bool _modem_initialised;
00618 
00619     /** True it the SIM requires a PIN, otherwise false.
00620      */
00621     bool _sim_pin_check_enabled;
00622 
00623     /** Sets the modem up for powering on
00624      *
00625      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00626      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00627      */
00628     virtual void modem_init();
00629 
00630     /** Sets the modem in unplugged state
00631      *
00632      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00633      *  and serial port. This puts the modem in lowest power state.
00634      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00635      */
00636     virtual void modem_deinit();
00637 
00638     /** Powers up the modem
00639      *
00640      *  modem_power_up() is equivalent to pressing the soft power button.
00641      *  The driver may repeat this if the modem is not responsive to AT commands.
00642      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00643      */
00644     virtual void modem_power_up();
00645 
00646     /** Powers down the modem
00647      *
00648      *  modem_power_down() is equivalent to turning off the modem by button press.
00649      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00650      */
00651     virtual void modem_power_down();
00652 
00653     /* Note: constructor and destructor protected so that this
00654     * class can only ever be inherited, never used directly.
00655     */
00656     UbloxCellularBase();
00657     ~UbloxCellularBase();
00658 
00659     /** Initialise this class.
00660      *
00661      * @param tx       the UART TX data pin to which the modem is attached.
00662      * @param rx       the UART RX data pin to which the modem is attached.
00663      * @param baud     the UART baud rate.
00664      * @param debug_on true to switch AT interface debug on, otherwise false.
00665      *
00666      * Note: it would be more natural to do this in the constructor
00667      * however, to avoid the diamond of death, this class is only
00668      * every inherited virtually.  Classes that are inherited virtually
00669      * do not get passed parameters in their constructor and hence
00670      * classInit() must be called separately by the first one to wake
00671      * the beast.
00672      */
00673     void baseClassInit(PinName tx = MDMTXD,
00674                        PinName rx = MDMRXD,
00675                        int baud = MBED_CONF_UBLOX_CELL_BAUD_RATE,
00676                        bool debug_on = false);
00677 
00678     /** Set the AT parser timeout.
00679      */
00680     void at_set_timeout(int timeout);
00681 
00682     /** Read up to size characters from buf
00683      * or until the character "end" is reached, overwriting
00684      * the newline with 0 and ensuring a terminator
00685      * in all cases.
00686      *
00687      * @param buf  the buffer to write to.
00688      * @param size the size of the buffer.
00689      * @param end  the character to stop at.
00690      * @return     the number of characters read,
00691      *             not including the terminator.
00692      */
00693     int read_at_to_char(char * buf, int size, char end);
00694 
00695     /** Powers up the modem.
00696      *
00697      * @return true if successful, otherwise false.
00698      */
00699     bool power_up();
00700 
00701     /** Power down the modem.
00702      */
00703     void power_down();
00704 
00705     /** Lock a mutex when accessing the modem.
00706      */
00707     void lock(void)     { _mtx.lock(); }
00708 
00709     /** Helper to make sure that lock unlock pair is always balanced
00710      */
00711     #define LOCK()         { lock()
00712 
00713     /** Unlock the modem when done accessing it.
00714      */
00715     void unlock(void)   { _mtx.unlock(); }
00716 
00717     /** Helper to make sure that lock unlock pair is always balanced
00718      */
00719     #define UNLOCK()       } unlock()
00720 
00721     /** Set the device identity in _dev_info
00722      * based on the ATI string returned by
00723      * the module.
00724      *
00725      * @return true if dev is a known value,
00726      *         otherwise false.
00727      */
00728     bool set_device_identity(DeviceType *dev);
00729 
00730     /** Perform any modem initialisation that is
00731      * specialised by device type.
00732      *
00733      * @return true if successful, otherwise false.
00734      */
00735     bool device_init(DeviceType dev);
00736 
00737     /** Set up the SIM.
00738      *
00739      * @return true if successful, otherwiss false.
00740      */
00741     bool initialise_sim_card();
00742 
00743 #ifdef TARGET_UBLOX_C030_R41XM
00744     /** Converts the given uint to binary string. Fills the given str starting from [0] with the number of bits defined by bit_cnt
00745      *  For example uint_to_binary_string(9, str, 10) would fill str "0000001001"
00746      *  For example uint_to_binary_string(9, str, 3) would fill str "001"
00747      *
00748      *  @param num       uint to converts to binary string
00749      *  @param str       buffer for converted binary string
00750      *  @param str_size  size of the str buffer
00751      *  @param bit_cnt   defines how many bits are filled to buffer started from lsb
00752      */
00753     void uint_to_binary_str(uint32_t num, char* str, int str_size, int bit_cnt);
00754 
00755     /** Converts the given binary string to uint.
00756      *  For example binary_str_to_uint("0000001001", 10) would return 9
00757      *
00758      *  @param binary_string           binary string from where chars are converted to uint
00759      *  @param binary_string_length    length of the param binary_string
00760      *  @return                        uint represented by the binary string
00761      */
00762     uint32_t binary_str_to_uint(const char *binary_string, int binary_string_length);
00763 
00764 #endif
00765 
00766 private:
00767 
00768     void set_nwk_reg_status_csd(int status);
00769     void set_nwk_reg_status_psd(int status);
00770     void set_nwk_reg_status_eps(int status);
00771     void set_rat(int AcTStatus);
00772     bool get_iccid();
00773     bool get_imsi();
00774     bool get_imei();
00775     bool get_meid();
00776     bool set_sms();
00777     void parser_abort_cb();
00778     void CMX_ERROR_URC();
00779     void CREG_URC();
00780     void CGREG_URC();
00781     void CEREG_URC();
00782     void UMWI_URC();
00783 #ifdef TARGET_UBLOX_C030_R412M
00784     typedef enum {
00785        DISABLED = 0,
00786        ENABLED = 1,
00787        UNKNOWN = 2
00788     } PSMStatus;
00789     bool set_psm_urcs(bool enable);
00790     void UUPSMR_URC();
00791     PSMStatus _psm_status;
00792     void *_cb_param_psm_going_in;
00793     Callback<void(void*)>    _func_psm_going_in;  /**< Callback. */
00794     void *_cb_param_psm_coming_out;
00795     Callback<void(void*)>    _func_psm_coming_out;  /**< Callback. */
00796     void set_modem_psm_state(int state);
00797 #endif
00798 #ifdef TARGET_UBLOX_C030_R41XM
00799     bool _default_profile_is_set;
00800 #endif
00801 };
00802 
00803 #endif // _UBLOX_CELLULAR_BASE_
00804