UbloxCellularBase.h

00001 /* Copyright (c) 2017 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 "ATCmdParser.h"
00022 #include "FileHandle.h"
00023 
00024 /**********************************************************************
00025  * CLASSES
00026  **********************************************************************/
00027 
00028 /** UbloxCellularBase class.
00029  *
00030  *  This class provides all the base support for generic u-blox modems
00031  *  on C030 and C027 boards: module identification, power-up, network
00032  *  registration, etc.
00033  */
00034 class UbloxCellularBase {
00035 
00036 public:
00037     /** Circuit Switched network registration status (CREG Usage).
00038      * UBX-13001820 - AT Commands Example Application Note (Section 7.10.3).
00039      */
00040     typedef enum {
00041         CSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00042         CSD_REGISTERED = 1,
00043         CSD_NOT_REGISTERED_SEARCHING = 2,
00044         CSD_REGISTRATION_DENIED = 3,
00045         CSD_UNKNOWN_COVERAGE = 4,
00046         CSD_REGISTERED_ROAMING = 5,
00047         CSD_SMS_ONLY = 6,
00048         CSD_SMS_ONLY_ROAMING = 7,
00049         CSD_CSFB_NOT_PREFERRED = 9
00050     } NetworkRegistrationStatusCsd;
00051 
00052     /** Packet Switched network registration status (CGREG Usage).
00053      * UBX-13001820 - AT Commands Example Application Note (Section 18.27.3).
00054      */
00055     typedef enum {
00056         PSD_NOT_REGISTERED_NOT_SEARCHING = 0,
00057         PSD_REGISTERED = 1,
00058         PSD_NOT_REGISTERED_SEARCHING = 2,
00059         PSD_REGISTRATION_DENIED = 3,
00060         PSD_UNKNOWN_COVERAGE = 4,
00061         PSD_REGISTERED_ROAMING = 5,
00062         PSD_EMERGENCY_SERVICES_ONLY = 8
00063     } NetworkRegistrationStatusPsd;
00064 
00065     /** EPS network registration status (CEREG Usage).
00066      * UBX-13001820 - AT Commands Example Application Note (Section 18.36.3).
00067      */
00068     typedef enum {
00069         EPS_NOT_REGISTERED_NOT_SEARCHING = 0,
00070         EPS_REGISTERED = 1,
00071         EPS_NOT_REGISTERED_SEARCHING = 2,
00072         EPS_REGISTRATION_DENIED = 3,
00073         EPS_UNKNOWN_COVERAGE = 4,
00074         EPS_REGISTERED_ROAMING = 5,
00075         EPS_EMERGENCY_SERVICES_ONLY = 8
00076     } NetworkRegistrationStatusEps;
00077 
00078     /** Initialise the modem, ready for use.
00079      *
00080      *  @param pin     PIN for the SIM card.
00081      *  @return        true if successful, otherwise false.
00082      */
00083     bool init(const char *pin = 0);
00084 
00085     /** Perform registration with the network.
00086      *
00087      * @return true if successful, otherwise false.
00088      */
00089     bool nwk_registration();
00090 
00091     /** True if the modem is registered for circuit
00092      * switched data, otherwise false.
00093      */
00094     bool is_registered_csd();
00095 
00096     /** True if the modem is registered for packet
00097      * switched data, otherwise false.
00098      */
00099     bool is_registered_psd();
00100 
00101     /** True if the modem is registered for enhanced
00102      * packet switched data (i.e. LTE and beyond),
00103      * otherwise false.
00104      */
00105     bool is_registered_eps();
00106 
00107     /** Perform deregistration from the network.
00108      *
00109      * @return true if successful, otherwise false.
00110      */
00111     bool nwk_deregistration();
00112 
00113     /** Put the modem into its lowest power state.
00114      */
00115     void deinit();
00116 
00117     /** Set the PIN code for the SIM card.
00118      *
00119      *  @param pin PIN for the SIM card.
00120      */
00121     void set_pin(const char *pin);
00122 
00123     /** Enable or disable SIM pin checking.
00124      *
00125      * @param enableNotDisable true if SIM PIN checking is to be enabled,
00126      *                         otherwise false.
00127      * @return                 true if successful, otherwise false.
00128      */
00129     bool sim_pin_check_enable(bool enableNotDisable);
00130 
00131     /** Change the SIM pin.
00132      *
00133      * @param new_pin the new PIN to use.
00134      * @return        true if successful, otherwise false.
00135      */
00136     bool change_sim_pin(const char *new_pin);
00137 
00138     /** Get the IMEI.
00139      *
00140      * @return true if successful, otherwise false.
00141      */
00142     MBED_DEPRECATED("This method is now replaced by const char * imei(), please use that instead")
00143     bool get_imei(char *imei_to_send, int size);
00144 
00145     /** Get the IMEI of the module.
00146      *
00147      * @return a pointer to the IMEI as a null-terminated string.
00148      */
00149     const char *imei();
00150 
00151     /** Get the Mobile Equipment ID (which may be the same as the IMEI).
00152      *
00153      * @return a pointer to the Mobile Equipment ID as a null-terminated string.
00154      */
00155     const char *meid();
00156 
00157     /** Get the IMSI of the SIM.
00158      *
00159      * @return a pointer to the IMSI as a null-terminated string.
00160      */
00161     const char *imsi();
00162 
00163     /** Get the ICCID of the SIM.
00164      *
00165      * @return a pointer to the ICCID as a null-terminated string.
00166      */
00167     const char *iccid();
00168 
00169     /** Get the RSSI.
00170      *
00171      * @return the RSSI in dBm. If it is not possible to obtain an
00172      *         RSSI reading at the time (e.g. because the modem is in
00173      *         data mode rather than AT command mode) then 0 is returned.
00174      */
00175     int rssi();
00176 
00177 protected:
00178 
00179     #define OUTPUT_ENTER_KEY  "\r"
00180 
00181     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00182     #define AT_PARSER_BUFFER_SIZE   MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_BUFFER_SIZE
00183     #else
00184     #define AT_PARSER_BUFFER_SIZE   256
00185     #endif
00186 
00187     #if MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00188     #define AT_PARSER_TIMEOUT       MBED_CONF_UBLOX_CELL_GEN_DRV_AT_PARSER_TIMEOUT
00189     #else
00190     #define AT_PARSER_TIMEOUT       55*1000 // Milliseconds
00191     #endif
00192 
00193     /** A string that would not normally be sent by the modem on the AT interface.
00194      */
00195     #define UNNATURAL_STRING "\x01"
00196 
00197     /** Supported u-blox modem variants.
00198      */
00199     typedef enum {
00200         DEV_TYPE_NONE = 0,
00201         DEV_SARA_G35,
00202         DEV_LISA_U2,
00203         DEV_LISA_U2_03S,
00204         DEV_SARA_U2,
00205         DEV_SARA_R4,
00206         DEV_LEON_G2,
00207         DEV_TOBY_L2,
00208         DEV_MPCI_L2,
00209         DEV_LARA_R2
00210     } DeviceType;
00211 
00212     /** Network registration status.
00213      * UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5).
00214      */
00215     typedef enum {
00216        GSM = 0,
00217        COMPACT_GSM = 1,
00218        UTRAN = 2,
00219        EDGE = 3,
00220        HSDPA = 4,
00221        HSUPA = 5,
00222        HSDPA_HSUPA = 6,
00223        LTE = 7,
00224        EC_GSM_IoT = 8,
00225        E_UTRAN_NB_S1 = 9
00226     } RadioAccessNetworkType;
00227 
00228     /** Info about the modem.
00229      */
00230     typedef struct {
00231         DeviceType dev;
00232         char iccid[20 + 1];   //!< Integrated Circuit Card ID.
00233         char imsi[15 + 1];    //!< International Mobile Station Identity.
00234         char imei[15 + 1];    //!< International Mobile Equipment Identity.
00235         char meid[18 + 1];    //!< Mobile Equipment IDentifier.
00236         volatile RadioAccessNetworkType rat;  //!< Type of network (e.g. 2G, 3G, LTE).
00237         volatile NetworkRegistrationStatusCsd reg_status_csd; //!< Circuit switched attach status.
00238         volatile NetworkRegistrationStatusPsd reg_status_psd; //!< Packet switched attach status.
00239         volatile NetworkRegistrationStatusEps reg_status_eps; //!< Evolved Packet Switched (e.g. LTE) attach status.
00240     } DeviceInfo;
00241 
00242     /* IMPORTANT: the variables below are available to
00243      * classes that inherit this in order to keep things
00244      * simple. However, ONLY this class should free
00245      * any of the pointers, or there will be havoc.
00246      */
00247 
00248     /** Point to the instance of the AT parser in use.
00249      */
00250     ATCmdParser *_at;
00251 
00252     /** The current AT parser timeout value.
00253      */
00254     int _at_timeout;
00255 
00256     /** File handle used by the AT parser.
00257      */
00258     FileHandle *_fh;
00259 
00260     /** The mutex resource.
00261      */
00262     Mutex _mtx;
00263 
00264     /** General info about the modem as a device.
00265      */
00266     DeviceInfo _dev_info;
00267 
00268     /** The SIM PIN to use.
00269      */
00270     const char *_pin;
00271 
00272     /** Set to true to spit out debug traces.
00273      */
00274     bool _debug_trace_on;
00275     
00276     /** The baud rate to the modem.
00277      */
00278     int _baud;
00279 
00280     /** True if the modem is ready register to the network,
00281      * otherwise false.
00282      */
00283     bool _modem_initialised;
00284 
00285     /** True it the SIM requires a PIN, otherwise false.
00286      */
00287     bool _sim_pin_check_enabled;
00288 
00289     /** Sets the modem up for powering on
00290      *
00291      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00292      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00293      */
00294     virtual void modem_init();
00295 
00296     /** Sets the modem in unplugged state
00297      *
00298      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00299      *  and serial port. This puts the modem in lowest power state.
00300      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00301      */
00302     virtual void modem_deinit();
00303 
00304     /** Powers up the modem
00305      *
00306      *  modem_power_up() is equivalent to pressing the soft power button.
00307      *  The driver may repeat this if the modem is not responsive to AT commands.
00308      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00309      */
00310     virtual void modem_power_up();
00311 
00312     /** Powers down the modem
00313      *
00314      *  modem_power_down() is equivalent to turning off the modem by button press.
00315      *  Uses onboard_modem_api.h where the implementation of onboard_modem_api is provided by the target.
00316      */
00317     virtual void modem_power_down();
00318 
00319     /* Note: constructor and destructor protected so that this
00320     * class can only ever be inherited, never used directly.
00321     */
00322     UbloxCellularBase();
00323     ~UbloxCellularBase();
00324 
00325     /** Initialise this class.
00326      *
00327      * @param tx       the UART TX data pin to which the modem is attached.
00328      * @param rx       the UART RX data pin to which the modem is attached.
00329      * @param baud     the UART baud rate.
00330      * @param debug_on true to switch AT interface debug on, otherwise false.
00331      *
00332      * Note: it would be more natural to do this in the constructor
00333      * however, to avoid the diamond of death, this class is only
00334      * every inherited virtually.  Classes that are inherited virtually
00335      * do not get passed parameters in their constructor and hence
00336      * classInit() must be called separately by the first one to wake
00337      * the beast.
00338      */
00339     void baseClassInit(PinName tx = MDMTXD,
00340                        PinName rx = MDMRXD,
00341                        int baud = MBED_CONF_UBLOX_CELL_BAUD_RATE,
00342                        bool debug_on = false);
00343 
00344     /** Set the AT parser timeout.
00345      */
00346     void at_set_timeout(int timeout);
00347 
00348     /** Read up to size characters from buf
00349      * or until the character "end" is reached, overwriting
00350      * the newline with 0 and ensuring a terminator
00351      * in all cases.
00352      *
00353      * @param buf  the buffer to write to.
00354      * @param size the size of the buffer.
00355      * @param end  the character to stop at.
00356      * @return     the number of characters read,
00357      *             not including the terminator.
00358      */
00359     int read_at_to_char(char * buf, int size, char end);
00360 
00361     /** Powers up the modem.
00362      *
00363      * @return true if successful, otherwise false.
00364      */
00365     bool power_up();
00366 
00367     /** Power down the modem.
00368      */
00369     void power_down();
00370 
00371     /** Lock a mutex when accessing the modem.
00372      */
00373     void lock(void)     { _mtx.lock(); }
00374 
00375     /** Helper to make sure that lock unlock pair is always balanced
00376      */
00377     #define LOCK()         { lock()
00378 
00379     /** Unlock the modem when done accessing it.
00380      */
00381     void unlock(void)   { _mtx.unlock(); }
00382 
00383     /** Helper to make sure that lock unlock pair is always balanced
00384      */
00385     #define UNLOCK()       } unlock()
00386 
00387     /** Set the device identity in _dev_info
00388      * based on the ATI string returned by
00389      * the module.
00390      *
00391      * @return true if dev is a known value,
00392      *         otherwise false.
00393      */
00394     bool set_device_identity(DeviceType *dev);
00395 
00396     /** Perform any modem initialisation that is
00397      * specialised by device type.
00398      *
00399      * @return true if successful, otherwise false.
00400      */
00401     bool device_init(DeviceType dev);
00402 
00403     /** Set up the SIM.
00404      *
00405      * @return true if successful, otherwiss false.
00406      */
00407     bool initialise_sim_card();
00408 
00409 private:
00410 
00411     void set_nwk_reg_status_csd(int status);
00412     void set_nwk_reg_status_psd(int status);
00413     void set_nwk_reg_status_eps(int status);
00414     void set_rat(int AcTStatus);
00415     bool get_iccid();
00416     bool get_imsi();
00417     bool get_imei();
00418     bool get_meid();
00419     bool set_sms();
00420     void parser_abort_cb();
00421     void CMX_ERROR_URC();
00422     void CREG_URC();
00423     void CGREG_URC();
00424     void CEREG_URC();
00425     void UMWI_URC();
00426 };
00427 
00428 #endif // _UBLOX_CELLULAR_BASE_
00429