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