EasyCellularConnection.h

00001 /*
00002  * Copyright (c) 2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef EASY_CELLULAR_CONNECTION_H
00019 #define EASY_CELLULAR_CONNECTION_H
00020 
00021 #include "CellularConnectionFSM.h"
00022 #if defined(CELLULAR_DEVICE) || defined(DOXYGEN_ONLY)
00023 
00024 #include "netsocket/CellularBase.h"
00025 
00026 #define USE_APN_LOOKUP (MBED_CONF_CELLULAR_USE_APN_LOOKUP || (NSAPI_PPP_AVAILABLE && MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP))
00027 
00028 namespace mbed {
00029 
00030 /** EasyCellularConnection class
00031  *
00032  *  Simplified adapter for cellular connection
00033  */
00034 class EasyCellularConnection: public CellularBase {
00035 
00036 public:
00037     EasyCellularConnection(bool debug = false);
00038     virtual ~EasyCellularConnection();
00039 
00040 public:
00041     /** Set the Cellular network credentials
00042      *
00043      *  Please check documentation of connect() for default behaviour of APN settings.
00044      *
00045      *  @param apn      Access point name
00046      *  @param uname    optionally, Username
00047      *  @param pwd      optionally, password
00048      */
00049     virtual void set_credentials(const char *apn, const char *uname = 0,
00050                                  const char *pwd = 0);
00051 
00052     /** Set the pin code for SIM card
00053      *
00054      *  @param sim_pin      PIN for the SIM card
00055      */
00056     virtual void set_sim_pin(const char *sim_pin);
00057 
00058     /** Start the interface
00059      *
00060      *  Attempts to connect to a Cellular network.
00061      *
00062      *  @param sim_pin     PIN for the SIM card
00063      *  @param apn         optionally, access point name
00064      *  @param uname       optionally, Username
00065      *  @param pwd         optionally, password
00066      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00067      */
00068     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00069                                   const char *uname = 0,
00070                                   const char *pwd = 0);
00071 
00072     /** Start the interface
00073      *
00074      *  Attempts to connect to a Cellular network.
00075      *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00076      *
00077      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00078      */
00079     virtual nsapi_error_t connect();
00080 
00081     /** Stop the interface
00082      *
00083      *  @return         0 on success, or error code on failure
00084      */
00085     virtual nsapi_error_t disconnect();
00086 
00087     /** Check if the connection is currently established or not
00088      *
00089      * @return true/false   If the cellular module have successfully acquired a carrier and is
00090      *                      connected to an external packet data network using PPP, isConnected()
00091      *                      API returns true and false otherwise.
00092      */
00093     virtual bool is_connected();
00094 
00095     /** Get the local IP address
00096      *
00097      *  @return         Null-terminated representation of the local IP address
00098      *                  or null if no IP address has been received
00099      */
00100     virtual const char *get_ip_address();
00101 
00102     /** Get the local network mask
00103      *
00104      *  @return         Null-terminated representation of the local network mask
00105      *                  or null if no network mask has been received
00106      */
00107     virtual const char *get_netmask();
00108 
00109     /** Get the local gateways
00110      *
00111      *  @return         Null-terminated representation of the local gateway
00112      *                  or null if no network mask has been received
00113      */
00114     virtual const char *get_gateway();
00115 
00116     /** Register callback for status reporting
00117      *
00118      *  The specified status callback function will be called on status changes
00119      *  on the network. The parameters on the callback are the event type and
00120      *  event-type dependent reason parameter.
00121      *
00122      *  @param status_cb The callback for status changes
00123      */
00124     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00125 
00126     /** Turn modem debug traces on
00127      *
00128      *  @param on         set true to enable debug traces
00129      */
00130     void modem_debug_on(bool on);
00131 
00132     /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
00133      *  registering is used when registering to a cellular network.
00134      *
00135      *  @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
00136      */
00137     void set_plmn(const char *plmn);
00138 
00139     /** Get the cellular device from the cellular state machine
00140      *
00141      * @return cellular device
00142      */
00143     CellularDevice *get_device();
00144 
00145     /** Get the UART serial file handle used by cellular subsystem
00146      *
00147      * @return address of cellular UART serial
00148      */
00149     UARTSerial *get_serial();
00150 
00151 protected:
00152 
00153     /** Provide access to the NetworkStack object
00154      *
00155      *  @return The underlying NetworkStack object
00156      */
00157     virtual NetworkStack *get_stack();
00158 
00159 private:
00160     /** Callback for cellular status changes
00161      *
00162      *  @return true to continue state machine
00163      */
00164     bool cellular_status(int state, int next_state);
00165     void network_callback(nsapi_event_t ev, intptr_t ptr);
00166     nsapi_error_t init();
00167     nsapi_error_t check_connect();
00168 
00169     bool _is_connected;
00170     bool _is_initialized;
00171     bool _stm_error;
00172 #if USE_APN_LOOKUP
00173     bool _credentials_set;
00174 #endif // #if USE_APN_LOOKUP
00175     CellularConnectionFSM::CellularState _target_state;
00176 
00177     UARTSerial _cellularSerial;
00178     rtos::Semaphore _cellularSemaphore;
00179     CellularConnectionFSM *_cellularConnectionFSM;
00180     nsapi_error_t _credentials_err;
00181     Callback<void(nsapi_event_t, intptr_t)> _status_cb;
00182 };
00183 
00184 } // namespace
00185 
00186 #endif // CELLULAR_DEVICE || DOXYGEN
00187 
00188 #endif // EASY_CELLULAR_CONNECTION_H
00189 
00190 /** @}*/