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 
00020 #define EASY_CELLULAR_CONNECTION_H
00021 
00022 #include "CellularConnectionFSM.h"
00023 #if defined(CELLULAR_DEVICE) || defined(DOXYGEN_ONLY)
00024 
00025 #include "netsocket/CellularBase.h"
00026 
00027 #define USE_APN_LOOKUP (MBED_CONF_CELLULAR_USE_APN_LOOKUP || (NSAPI_PPP_AVAILABLE && MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP))
00028 
00029 namespace mbed
00030 {
00031 
00032 /** EasyCellularConnection class
00033  *
00034  *  Simplified adapter for cellular connection
00035  */
00036 class EasyCellularConnection: public CellularBase
00037 {
00038 
00039 public:
00040     EasyCellularConnection(bool debug = false);
00041     virtual ~EasyCellularConnection();
00042 
00043 public:
00044     /** Set the Cellular network credentials
00045      *
00046      *  Please check documentation of connect() for default behaviour of APN settings.
00047      *
00048      *  @param apn      Access point name
00049      *  @param uname    optionally, Username
00050      *  @param pwd      optionally, password
00051      */
00052     virtual void set_credentials(const char *apn, const char *uname = 0,
00053                                  const char *pwd = 0);
00054 
00055     /** Set the pin code for SIM card
00056      *
00057      *  @param sim_pin      PIN for the SIM card
00058      */
00059     virtual void set_sim_pin(const char *sim_pin);
00060 
00061     /** Start the interface
00062      *
00063      *  Attempts to connect to a Cellular network.
00064      *
00065      *  @param sim_pin     PIN for the SIM card
00066      *  @param apn         optionally, access point name
00067      *  @param uname       optionally, Username
00068      *  @param pwd         optionally, password
00069      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00070      */
00071     virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
00072                                   const char *uname = 0,
00073                                   const char *pwd = 0);
00074 
00075     /** Start the interface
00076      *
00077      *  Attempts to connect to a Cellular network.
00078      *  If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
00079      *
00080      *  @return            NSAPI_ERROR_OK on success, or negative error code on failure
00081      */
00082     virtual nsapi_error_t connect();
00083 
00084     /** Stop the interface
00085      *
00086      *  @return         0 on success, or error code on failure
00087      */
00088     virtual nsapi_error_t disconnect();
00089 
00090     /** Check if the connection is currently established or not
00091      *
00092      * @return true/false   If the cellular module have successfully acquired a carrier and is
00093      *                      connected to an external packet data network using PPP, isConnected()
00094      *                      API returns true and false otherwise.
00095      */
00096     virtual bool is_connected();
00097 
00098     /** Get the local IP address
00099      *
00100      *  @return         Null-terminated representation of the local IP address
00101      *                  or null if no IP address has been received
00102      */
00103     virtual const char *get_ip_address();
00104 
00105     /** Get the local network mask
00106      *
00107      *  @return         Null-terminated representation of the local network mask
00108      *                  or null if no network mask has been received
00109      */
00110     virtual const char *get_netmask();
00111 
00112     /** Get the local gateways
00113      *
00114      *  @return         Null-terminated representation of the local gateway
00115      *                  or null if no network mask has been received
00116      */
00117     virtual const char *get_gateway();
00118 
00119     /** Register callback for status reporting
00120      *
00121      *  @param status_cb The callback for status changes
00122      */
00123     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00124 
00125     /** Turn modem debug traces on
00126      *
00127      *  @param on         set true to enable debug traces
00128      */
00129     void modem_debug_on(bool on);
00130 
00131 protected:
00132 
00133     /** Provide access to the NetworkStack object
00134      *
00135      *  @return The underlying NetworkStack object
00136      */
00137     virtual NetworkStack *get_stack();
00138 
00139 private:
00140     /** Callback for cellular status changes
00141      *
00142      *  @return true to continue state machine
00143      */
00144     bool cellular_status(int state, int next_state);
00145     nsapi_error_t init();
00146     nsapi_error_t check_connect();
00147 
00148     bool _is_connected;
00149     bool _is_initialized;
00150 #if USE_APN_LOOKUP
00151     bool _credentials_set;
00152 #endif // #if USE_APN_LOOKUP
00153     CellularConnectionFSM::CellularState _target_state;
00154 
00155     UARTSerial _cellularSerial;
00156     rtos::Semaphore _cellularSemaphore;
00157     CellularConnectionFSM _cellularConnectionFSM;
00158     nsapi_error_t _credentials_err;
00159 };
00160 
00161 } // namespace
00162 
00163 #endif // CELLULAR_DEVICE || DOXYGEN
00164 
00165 #endif // EASY_CELLULAR_CONNECTION_H
00166 
00167 /** @}*/