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 
00103 class PPPCellularInterface : public CellularBase {
00104 
00105 public:
00106 
00107     /** Constructor for a generic modem, using a single FileHandle for commands and PPP data.
00108      *
00109      * The file handle pointer is not accessed within the constructor, only recorded for later
00110      * use - this permits a derived class to pass a pointer to a not-yet-constructed member object.
00111      */
00112     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00113     PPPCellularInterface(FileHandle *fh, bool debug = false);
00114 
00115     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00116     virtual ~PPPCellularInterface();
00117 
00118     /** Set the Cellular network credentials
00119      *
00120      *  Please check documentation of connect() for default behaviour of APN settings.
00121      *
00122      *  @param apn      Access point name
00123      *  @param uname    optionally, Username
00124      *  @param pwd      optionally, password
00125      */
00126     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00127     virtual void set_credentials(const char *apn, const char *uname = 0,
00128                                                   const char *pwd = 0);
00129 
00130     /** Set the pin code for SIM card
00131      *
00132      *  @param sim_pin      PIN for the SIM card
00133      */
00134     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00135     virtual void set_sim_pin(const char *sim_pin);
00136 
00137     /** Start the interface
00138      *
00139      *  Attempts to connect to a Cellular network.
00140      *  This driver is written mainly for data network connections as CellularInterface
00141      *  is NetworkInterface. That's why connect() call internally calls nwk_registration()
00142      *  method with parameter PACKET_SWITCHED network. Circuit switched hook and registration
00143      *  process is implemented and left in the driver for future extension/subclass support,e.g.,
00144      *  an SMS or GPS extension.
00145      *
00146      *  @param sim_pin     PIN for the SIM card
00147      *  @param apn         optionally, access point name
00148      *  @param uname       optionally, Username
00149      *  @param pwd         optionally, password
00150      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00151      */
00152     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00153     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00154                                   const char *uname = 0, const char *pwd = 0);
00155 
00156     /** Attempt to connect to the Cellular network
00157      *
00158      *  Brings up the network interface. Connects to the Cellular Radio
00159      *  network and then brings up the underlying network stack to be used
00160      *  by the cellular modem over PPP interface.
00161      *
00162      *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00163      *  For APN setup, default behaviour is to use 'internet' as APN string and assuming no authentication
00164      *  is required, i.e., username and password are not set. Optionally, a database lookup can be requested
00165      *  by turning on the APN database lookup feature. In order to do so, add 'MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP'
00166      *  in your mbed_app.json. APN database is by no means exhaustive. It contains a short list of some public
00167      *  APNs with publicly available usernames and passwords (if required) in some particular countries only.
00168      *  Lookup is done using IMSI (International mobile subscriber identifier).
00169      *  Please note that even if 'MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP' config option is set, 'set_credentials()' api still
00170      *  gets the precedence. If the aforementioned API is not used and the config option is set but no match is found in
00171      *  the lookup table then the driver tries to resort to default APN settings.
00172      *
00173      *  Preferred method is to setup APN using 'set_credentials()' API.
00174      *  @return         0 on success, negative error code on failure
00175      */
00176     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00177     virtual nsapi_error_t connect();
00178 
00179     /** Attempt to disconnect from the network
00180      *
00181      *  Brings down the network interface. Shuts down the PPP interface
00182      *  of the underlying network stack. Does not bring down the Radio network
00183      *
00184      *  @return         0 on success, negative error code on failure
00185      */
00186     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00187     virtual nsapi_error_t disconnect();
00188 
00189     /** Adds or removes a SIM facility lock
00190      *
00191      * Can be used to enable or disable SIM pin check at device startup.
00192      * This API sets up flags for the driver which would either enable or disable
00193      * SIM pin checking depending upon the user provided argument while establishing
00194      * connection. It doesn't do anything immediately other than setting up flags.
00195      *
00196      * @param set        can be set to true if the SIM pin check is supposed to be enabled
00197      *                   and vice versa.
00198      */
00199     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00200     void set_sim_pin_check(bool set);
00201 
00202     /** Change the pin for the SIM card
00203      *
00204      * Provide the new pin for your SIM card with this API. Old pin code will be assumed to
00205      * be set using set_SIM_pin() API. This API have no immediate effect. While establishing
00206      * connection, driver will change the SIM pin for the next boot.
00207      *
00208      * @param new_pin     new pin to be used in string format
00209      */
00210     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00211     void set_new_sim_pin(const char *new_pin);
00212 
00213     /** Check if the connection is currently established or not
00214      *
00215      * @return true/false   If the cellular module have successfully acquired a carrier and is
00216      *                      connected to an external packet data network using PPP, isConnected()
00217      *                      API returns true and false otherwise.
00218      */
00219     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00220     virtual bool is_connected();
00221 
00222     /** Get the local IP address
00223      *
00224      *  @return         Null-terminated representation of the local IP address
00225      *                  or null if no IP address has been received
00226      */
00227     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00228     virtual const char *get_ip_address();
00229 
00230     /** Get the local network mask
00231      *
00232      *  @return         Null-terminated representation of the local network mask
00233      *                  or null if no network mask has been received
00234      */
00235     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00236     virtual const char *get_netmask();
00237 
00238     /** Get the local gateways
00239      *
00240      *  @return         Null-terminated representation of the local gateway
00241      *                  or null if no network mask has been received
00242      */
00243     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00244     virtual const char *get_gateway();
00245 
00246 
00247     /** Turn modem debug traces on
00248      *
00249      *  @param on         set true to enable debug traces
00250      */
00251     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00252     void modem_debug_on(bool on);
00253 
00254     /** Register callback for status reporting
00255      *
00256      *  @param status_cb The callback for status changes
00257      */
00258     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00259     virtual void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
00260 
00261     /** Get the connection status
00262      *
00263      *  @return         The connection status according to nsapi_connection_status_t
00264      */
00265     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00266     virtual nsapi_connection_status_t get_connection_status() const;
00267 
00268     /** Set blocking status of connect() which by default should be blocking
00269      *
00270      *  @param blocking true if connect is blocking
00271      *  @return         0 on success, negative error code on failure
00272      */
00273     MBED_DEPRECATED_SINCE("mbed-os-5.9", "This API will be deprecated, use mbed-os/features/cellular/easy_cellular/EasyCellularConnection.h instead.")
00274     virtual nsapi_error_t set_blocking(bool blocking);
00275 
00276 private:
00277     FileHandle *_fh;
00278     ATCmdParser *_at;
00279     const char *_new_pin;
00280     const char *_pin;
00281     const char *_apn;
00282     const char *_uname;
00283     const char *_pwd;
00284     bool _debug_trace_on;
00285     nsapi_ip_stack_t _stack;
00286     Callback<void(nsapi_event_t, intptr_t)> _connection_status_cb;
00287     nsapi_connection_status_t _connect_status;
00288     bool _connect_is_blocking;
00289     void base_initialization();
00290     void setup_at_parser();
00291     void shutdown_at_parser();
00292     nsapi_error_t initialize_sim_card();
00293     nsapi_error_t setup_context_and_credentials();
00294     bool power_up();
00295     void power_down();
00296     void ppp_status_cb(nsapi_event_t, intptr_t);
00297 
00298 protected:
00299     /** Enable or disable hang-up detection
00300      *
00301      * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
00302      * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
00303      * signaling is not desired. enable_hup() controls whether this function should be
00304      * active.
00305      *
00306      * Meant to be overridden.
00307      */
00308     virtual void enable_hup(bool enable);
00309 
00310     /** Sets the modem up for powering on
00311      *
00312      *  modem_init() is equivalent to plugging in the device, e.g., attaching power and serial port.
00313      *  It is meant to be overridden.
00314      *  If the modem is on-board, an implementation of onboard_modem_api.h
00315      *  will override this.
00316      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00317      *  class will override.
00318      */
00319     virtual void modem_init();
00320 
00321     /** Sets the modem in unplugged state
00322      *
00323      *  modem_deinit() will be equivalent to pulling the plug off of the device, i.e., detaching power
00324      *  and serial port. This puts the modem in lowest power state.
00325      *  It is meant to be overridden.
00326      *  If the modem is on-board, an implementation of onboard_modem_api.h
00327      *  will override this.
00328      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00329      *  class will override.
00330      */
00331     virtual void modem_deinit();
00332 
00333     /** Powers up the modem
00334      *
00335      *  modem_power_up() is equivalent to pressing the soft power button.
00336      *  The driver may repeat this if the modem is not responsive to AT commands.
00337      *  It is meant to be overridden.
00338      *  If the modem is on-board, an implementation of onboard_modem_api.h
00339      *  will override this.
00340      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00341      *  class will override.
00342      */
00343     virtual void modem_power_up();
00344 
00345     /** Powers down the modem
00346      *
00347      *  modem_power_down() is equivalent to turning off the modem by button press.
00348      *  It is meant to be overridden.
00349      *  If the modem is on-board, an implementation of onboard_modem_api.h
00350      *  will override this.
00351      *  If the the modem is a plugged-in device (i.e., a shield type component), the driver deriving from this
00352      *  class will override.
00353      */
00354     virtual void modem_power_down();
00355 
00356     /** Provide access to the underlying stack
00357      *
00358      *  @return The underlying network stack
00359      */
00360     virtual NetworkStack *get_stack();
00361 
00362     /** Starts network registration process.
00363      *
00364      * Potential users could be subclasses who are not network interface
00365      * but would like to use CellularInterface infrastructure to register
00366      * with a cellular network, e.g., an SMS extension to CellularInterface.
00367      *
00368      * @param nwk_type type of network to connect, defaults to packet switched network
00369      *
00370      * @return true if registration is successful
00371      */
00372     bool nwk_registration(uint8_t nwk_type=PACKET_SWITCHED);
00373 
00374 };
00375 
00376 #endif //NSAPI_PPP_AVAILABLE
00377 
00378 #endif //PPP_CELLULAR_INTERFACE_