PPPCellularInterface.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 PPP_CELLULAR_INTERFACE_
00017 #define PPP_CELLULAR_INTERFACE_
00018 
00019 #include "CellularBase.h"
00020 #include "platform/ATCmdParser.h"
00021 #include "mbed.h"
00022 
00023 #if NSAPI_PPP_AVAILABLE
00024 
00025 // Forward declaration
00026 class NetworkStack;
00027 
00028 /**
00029  * Network registration status
00030  * UBX-13001820 - AT Commands Example Application Note (Section 4.1.4.5)
00031  */
00032 typedef enum {
00033    GSM=0,
00034    COMPACT_GSM=1,
00035    UTRAN=2,
00036    EDGE=3,
00037    HSDPA=4,
00038    HSUPA=5,
00039    HSDPA_HSUPA=6,
00040    LTE=7
00041 } radio_access_nwk_type;
00042 
00043 /**
00044  * Used in registration process to tell which type of network
00045  * to connect.
00046  */
00047 typedef enum {
00048     CIRCUIT_SWITCHED=0,
00049     PACKET_SWITCHED
00050 } nwk_type;
00051 
00052 /**
00053  * Circuit Switched network registration status (CREG Usage)
00054  * UBX-13001820 - AT Commands Example Application Note (Section 7.10.3)
00055  */
00056 typedef enum {
00057     CSD_NOT_REGISTERED_NOT_SEARCHING=0,
00058     CSD_REGISTERED=1,
00059     CSD_NOT_REGISTERED_SEARCHING=2,
00060     CSD_REGISTRATION_DENIED=3,
00061     CSD_UNKNOWN_COVERAGE=4,
00062     CSD_REGISTERED_ROAMING=5,
00063     CSD_SMS_ONLY=6,
00064     CSD_SMS_ONLY_ROAMING=7,
00065     CSD_CSFB_NOT_PREFERRED=9
00066 } nwk_registration_status_csd;
00067 
00068 /**
00069  * Packet Switched network registration status (CGREG Usage)
00070  * UBX-13001820 - AT Commands Example Application Note (Section 18.27.3)
00071  */
00072 typedef enum {
00073     PSD_NOT_REGISTERED_NOT_SEARCHING=0,
00074     PSD_REGISTERED=1,
00075     PSD_NOT_REGISTERED_SEARCHING=2,
00076     PSD_REGISTRATION_DENIED=3,
00077     PSD_UNKNOWN_COVERAGE=4,
00078     PSD_REGISTERED_ROAMING=5,
00079     PSD_EMERGENCY_SERVICES_ONLY=8
00080 } nwk_registration_status_psd;
00081 
00082 typedef struct {
00083     char ccid[20+1];    //!< Integrated Circuit Card ID
00084     char imsi[15+1];    //!< International Mobile Station Identity
00085     char imei[15+1];    //!< International Mobile Equipment Identity
00086     char meid[18+1];    //!< Mobile Equipment IDentifier
00087     int flags;
00088     radio_access_nwk_type rat;
00089     nwk_registration_status_csd reg_status_csd;
00090     nwk_registration_status_psd reg_status_psd;
00091 } device_info;
00092 
00093 /** PPPCellularInterface class
00094  *
00095  *  This interface serves as the controller/driver for the Cellular
00096  *  modems (tested with UBLOX_C027 and MTS_DRAGONFLY_F411RE).
00097  *
00098  *  The driver will work with any generic FileHandle, and can be
00099  *  derived from in order to provide forms for specific interfaces, as well as
00100  *  adding extra power and reset controls alongside the FileHandle.
00101  */
00102 class PPPCellularInterface : public CellularBase {
00103 
00104 public:
00105 
00106     /** Constructor for a generic modem, using a single FileHandle for commands and PPP data.
00107      *
00108      * The file handle pointer is not accessed within the constructor, only recorded for later
00109      * use - this permits a derived class to pass a pointer to a not-yet-constructed member object.
00110      */
00111     PPPCellularInterface(FileHandle *fh, bool debug = false);
00112 
00113     virtual ~PPPCellularInterface();
00114 
00115     /** Set the Cellular network credentials
00116      *
00117      *  Please check documentation of connect() for default behaviour of APN settings.
00118      *
00119      *  @param apn      Access point name
00120      *  @param uname    optionally, Username
00121      *  @param pwd      optionally, password
00122      */
00123     virtual void set_credentials(const char *apn, const char *uname = 0,
00124                                                   const char *pwd = 0);
00125 
00126     /** Set the pin code for SIM card
00127      *
00128      *  @param sim_pin      PIN for the SIM card
00129      */
00130     virtual void set_sim_pin(const char *sim_pin);
00131 
00132     /** Start the interface
00133      *
00134      *  Attempts to connect to a Cellular network.
00135      *  This driver is written mainly for data network connections as CellularInterface
00136      *  is NetworkInterface. That's why connect() call internally calls nwk_registration()
00137      *  method with parameter PACKET_SWITCHED network. Circuit switched hook and registration
00138      *  process is implemented and left in the driver for future extension/subclass support,e.g.,
00139      *  an SMS or GPS extension.
00140      *
00141      *  @param sim_pin     PIN for the SIM card
00142      *  @param apn         optionally, access point name
00143      *  @param uname       optionally, Username
00144      *  @param pwd         optionally, password
00145      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00146      */
00147     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00148                                   const char *uname = 0, const char *pwd = 0);
00149 
00150     /** Attempt to connect to the Cellular network
00151      *
00152      *  Brings up the network interface. Connects to the Cellular Radio
00153      *  network and then brings up the underlying network stack to be used
00154      *  by the cellular modem over PPP interface.
00155      *
00156      *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00157      *  For APN setup, default behaviour is to use 'internet' as APN string and assuming no authentication
00158      *  is required, i.e., username and password are not set. Optionally, a database lookup can be requested
00159      *  by turning on the APN database lookup feature. In order to do so, add 'MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP'
00160      *  in your mbed_app.json. APN database is by no means exhaustive. It contains a short list of some public
00161      *  APNs with publicly available usernames and passwords (if required) in some particular countries only.
00162      *  Lookup is done using IMSI (International mobile subscriber identifier).
00163      *  Please note that even if 'MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP' config option is set, 'set_credentials()' api still
00164      *  gets the precedence. If the aforementioned API is not used and the config option is set but no match is found in
00165      *  the lookup table then the driver tries to resort to default APN settings.
00166      *
00167      *  Preferred method is to setup APN using 'set_credentials()' API.
00168      *  @return         0 on success, negative error code on failure
00169      */
00170     virtual nsapi_error_t connect();
00171 
00172     /** Attempt to disconnect from the network
00173      *
00174      *  Brings down the network interface. Shuts down the PPP interface
00175      *  of the underlying network stack. Does not bring down the Radio network
00176      *
00177      *  @return         0 on success, negative error code on failure
00178      */
00179     virtual nsapi_error_t disconnect();
00180 
00181     /** Adds or removes a SIM facility lock
00182      *
00183      * Can be used to enable or disable SIM pin check at device startup.
00184      * This API sets up flags for the driver which would either enable or disable
00185      * SIM pin checking depending upon the user provided argument while establishing
00186      * connection. It doesn't do anything immediately other than setting up flags.
00187      *
00188      * @param set        can be set to true if the SIM pin check is supposed to be enabled
00189      *                   and vice versa.
00190      */
00191     void set_sim_pin_check(bool set);
00192 
00193     /** Change the pin for the SIM card
00194      *
00195      * Provide the new pin for your SIM card with this API. Old pin code will be assumed to
00196      * be set using set_SIM_pin() API. This API have no immediate effect. While establishing
00197      * connection, driver will change the SIM pin for the next boot.
00198      *
00199      * @param new_pin     new pin to be used in string format
00200      */
00201     void set_new_sim_pin(const char *new_pin);
00202 
00203     /** Check if the connection is currently established or not
00204      *
00205      * @return true/false   If the cellular module have successfully acquired a carrier and is
00206      *                      connected to an external packet data network using PPP, isConnected()
00207      *                      API returns true and false otherwise.
00208      */
00209     virtual bool is_connected();
00210 
00211     /** Get the local IP address
00212      *
00213      *  @return         Null-terminated representation of the local IP address
00214      *                  or null if no IP address has been recieved
00215      */
00216     virtual const char *get_ip_address();
00217 
00218     /** Get the local network mask
00219      *
00220      *  @return         Null-terminated representation of the local network mask
00221      *                  or null if no network mask has been recieved
00222      */
00223     virtual const char *get_netmask();
00224 
00225     /** Get the local gateways
00226      *
00227      *  @return         Null-terminated representation of the local gateway
00228      *                  or null if no network mask has been recieved
00229      */
00230     virtual const char *get_gateway();
00231 
00232 
00233     /** Turn modem debug traces on
00234      *
00235      *  @param on         set true to enable debug traces
00236      */
00237     void modem_debug_on(bool on);
00238 
00239     /** Register callback for status reporting
00240      *
00241      *  @param status_cb The callback for status changes
00242      */
00243     virtual void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
00244 
00245     /** Get the connection status
00246      *
00247      *  @return         The connection status according to nsapi_connection_status_t
00248      */
00249     virtual nsapi_connection_status_t get_connection_status() const;
00250 
00251     /** Set blocking status of connect() which by default should be blocking
00252      *
00253      *  @param blocking true if connect is blocking
00254      *  @return         0 on success, negative error code on failure
00255      */
00256     virtual nsapi_error_t set_blocking(bool blocking);
00257 
00258 private:
00259     FileHandle *_fh;
00260     ATCmdParser *_at;
00261     const char *_new_pin;
00262     const char *_pin;
00263     const char *_apn;
00264     const char *_uname;
00265     const char *_pwd;
00266     bool _debug_trace_on;
00267     nsapi_ip_stack_t _stack;
00268     Callback<void(nsapi_event_t, intptr_t)> _connection_status_cb;
00269     nsapi_connection_status_t _connect_status;
00270     bool _connect_is_blocking;
00271     void base_initialization();
00272     void setup_at_parser();
00273     void shutdown_at_parser();
00274     nsapi_error_t initialize_sim_card();
00275     nsapi_error_t setup_context_and_credentials();
00276     bool power_up();
00277     void power_down(); 
00278     void ppp_status_cb(nsapi_event_t, intptr_t);
00279 
00280 protected:
00281     /** Enable or disable hang-up detection
00282      *
00283      * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
00284      * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
00285      * signaling is not desired. enable_hup() controls whether this function should be
00286      * active.
00287      *
00288      * Meant to be overridden.
00289      */
00290     virtual void enable_hup(bool enable);
00291 
00292     /** Sets the modem up for powering on
00293      *
00294      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00295      *  It is meant to be overridden.
00296      *  If the modem is on-board, an implementation of onboard_modem_api.h
00297      *  will override this.
00298      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00299      *  class will override.
00300      */
00301     virtual void modem_init();
00302 
00303     /** Sets the modem in unplugged state
00304      *
00305      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00306      *  and serial port. This puts the modem in lowest power state.
00307      *  It is meant to be overridden.
00308      *  If the modem is on-board, an implementation of onboard_modem_api.h
00309      *  will override this.
00310      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00311      *  class will override.
00312      */
00313     virtual void modem_deinit();
00314 
00315     /** Powers up the modem
00316      *
00317      *  modem_power_up() is equivalent to pressing the soft power button.
00318      *  The driver may repeat this if the modem is not responsive to AT commands.
00319      *  It is meant to be overridden.
00320      *  If the modem is on-board, an implementation of onboard_modem_api.h
00321      *  will override this.
00322      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00323      *  class will override.
00324      */
00325     virtual void modem_power_up();
00326 
00327     /** Powers down the modem
00328      *
00329      *  modem_power_down() is equivalent to turning off the modem by button press.
00330      *  It is meant to be overridden.
00331      *  If the modem is on-board, an implementation of onboard_modem_api.h
00332      *  will override this.
00333      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00334      *  class will override.
00335      */
00336     virtual void modem_power_down();
00337 
00338     /** Provide access to the underlying stack
00339      *
00340      *  @return The underlying network stack
00341      */
00342     virtual NetworkStack *get_stack();
00343 
00344     /** Starts network registration process.
00345      *
00346      * Potential users could be subclasses who are not network interface
00347      * but would like to use CellularInterface infrastructure to register
00348      * with a cellular network, e.g., an SMS extension to CellularInterface.
00349      *
00350      * @param nwk_type type of network to connect, defaults to packet switched network
00351      *
00352      * @return true if registration is successful
00353      */
00354     bool nwk_registration(uint8_t nwk_type=PACKET_SWITCHED);
00355 
00356 };
00357 
00358 #endif //NSAPI_PPP_AVAILABLE
00359 
00360 #endif //PPP_CELLULAR_INTERFACE_