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