Kev Mann / mbed-dev-OS5_10_4

features/cellular/easy_cellular/EasyCellularConnection.h@2:7aab896b1a3b, 2019-03-13 (annotated)

Committer:
kevman
Date:
Wed Mar 13 11:03:24 2019 +0000
Revision:
2:7aab896b1a3b
Parent:
0:38ceb79fef03 
2019-03-13

Who changed what in which revision?

UserRevisionLine numberNew contents of line
kevman 0:38ceb79fef03 1 /*
kevman 0:38ceb79fef03 2 * Copyright (c) 2017, Arm Limited and affiliates.
kevman 0:38ceb79fef03 3 * SPDX-License-Identifier: Apache-2.0
kevman 0:38ceb79fef03 4 *
kevman 0:38ceb79fef03 5 * Licensed under the Apache License, Version 2.0 (the "License");
kevman 0:38ceb79fef03 6 * you may not use this file except in compliance with the License.
kevman 0:38ceb79fef03 7 * You may obtain a copy of the License at
kevman 0:38ceb79fef03 8 *
kevman 0:38ceb79fef03 9 * http://www.apache.org/licenses/LICENSE-2.0
kevman 0:38ceb79fef03 10 *
kevman 0:38ceb79fef03 11 * Unless required by applicable law or agreed to in writing, software
kevman 0:38ceb79fef03 12 * distributed under the License is distributed on an "AS IS" BASIS,
kevman 0:38ceb79fef03 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
kevman 0:38ceb79fef03 14 * See the License for the specific language governing permissions and
kevman 0:38ceb79fef03 15 * limitations under the License.
kevman 0:38ceb79fef03 16 */
kevman 0:38ceb79fef03 17
kevman 0:38ceb79fef03 18 #ifndef EASY_CELLULAR_CONNECTION_H
kevman 0:38ceb79fef03 19 #define EASY_CELLULAR_CONNECTION_H
kevman 0:38ceb79fef03 20
kevman 0:38ceb79fef03 21 #include "CellularConnectionFSM.h"
kevman 0:38ceb79fef03 22 #if defined(CELLULAR_DEVICE) || defined(DOXYGEN_ONLY)
kevman 0:38ceb79fef03 23
kevman 0:38ceb79fef03 24 #include "netsocket/CellularBase.h"
kevman 0:38ceb79fef03 25
kevman 0:38ceb79fef03 26 #define USE_APN_LOOKUP (MBED_CONF_CELLULAR_USE_APN_LOOKUP || (NSAPI_PPP_AVAILABLE && MBED_CONF_PPP_CELL_IFACE_APN_LOOKUP))
kevman 0:38ceb79fef03 27
kevman 0:38ceb79fef03 28 namespace mbed {
kevman 0:38ceb79fef03 29
kevman 0:38ceb79fef03 30 /** EasyCellularConnection class
kevman 0:38ceb79fef03 31 *
kevman 0:38ceb79fef03 32 * Simplified adapter for cellular connection
kevman 0:38ceb79fef03 33 */
kevman 0:38ceb79fef03 34 class EasyCellularConnection: public CellularBase {
kevman 0:38ceb79fef03 35
kevman 0:38ceb79fef03 36 public:
kevman 0:38ceb79fef03 37 EasyCellularConnection(bool debug = false);
kevman 0:38ceb79fef03 38 virtual ~EasyCellularConnection();
kevman 0:38ceb79fef03 39
kevman 0:38ceb79fef03 40 public:
kevman 0:38ceb79fef03 41 /** Set the Cellular network credentials
kevman 0:38ceb79fef03 42 *
kevman 0:38ceb79fef03 43 * Please check documentation of connect() for default behaviour of APN settings.
kevman 0:38ceb79fef03 44 *
kevman 0:38ceb79fef03 45 * @param apn Access point name
kevman 0:38ceb79fef03 46 * @param uname optionally, Username
kevman 0:38ceb79fef03 47 * @param pwd optionally, password
kevman 0:38ceb79fef03 48 */
kevman 0:38ceb79fef03 49 virtual void set_credentials(const char *apn, const char *uname = 0,
kevman 0:38ceb79fef03 50 const char *pwd = 0);
kevman 0:38ceb79fef03 51
kevman 0:38ceb79fef03 52 /** Set the pin code for SIM card
kevman 0:38ceb79fef03 53 *
kevman 0:38ceb79fef03 54 * @param sim_pin PIN for the SIM card
kevman 0:38ceb79fef03 55 */
kevman 0:38ceb79fef03 56 virtual void set_sim_pin(const char *sim_pin);
kevman 0:38ceb79fef03 57
kevman 0:38ceb79fef03 58 /** Start the interface
kevman 0:38ceb79fef03 59 *
kevman 0:38ceb79fef03 60 * Attempts to connect to a Cellular network.
kevman 0:38ceb79fef03 61 *
kevman 0:38ceb79fef03 62 * @param sim_pin PIN for the SIM card
kevman 0:38ceb79fef03 63 * @param apn optionally, access point name
kevman 0:38ceb79fef03 64 * @param uname optionally, Username
kevman 0:38ceb79fef03 65 * @param pwd optionally, password
kevman 0:38ceb79fef03 66 * @return NSAPI_ERROR_OK on success, or negative error code on failure
kevman 0:38ceb79fef03 67 */
kevman 0:38ceb79fef03 68 virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0,
kevman 0:38ceb79fef03 69 const char *uname = 0,
kevman 0:38ceb79fef03 70 const char *pwd = 0);
kevman 0:38ceb79fef03 71
kevman 0:38ceb79fef03 72 /** Start the interface
kevman 0:38ceb79fef03 73 *
kevman 0:38ceb79fef03 74 * Attempts to connect to a Cellular network.
kevman 0:38ceb79fef03 75 * If the SIM requires a PIN, and it is not set/invalid, NSAPI_ERROR_AUTH_ERROR is returned.
kevman 0:38ceb79fef03 76 *
kevman 0:38ceb79fef03 77 * @return NSAPI_ERROR_OK on success, or negative error code on failure
kevman 0:38ceb79fef03 78 */
kevman 0:38ceb79fef03 79 virtual nsapi_error_t connect();
kevman 0:38ceb79fef03 80
kevman 0:38ceb79fef03 81 /** Stop the interface
kevman 0:38ceb79fef03 82 *
kevman 0:38ceb79fef03 83 * @return 0 on success, or error code on failure
kevman 0:38ceb79fef03 84 */
kevman 0:38ceb79fef03 85 virtual nsapi_error_t disconnect();
kevman 0:38ceb79fef03 86
kevman 0:38ceb79fef03 87 /** Check if the connection is currently established or not
kevman 0:38ceb79fef03 88 *
kevman 0:38ceb79fef03 89 * @return true/false If the cellular module have successfully acquired a carrier and is
kevman 0:38ceb79fef03 90 * connected to an external packet data network using PPP, isConnected()
kevman 0:38ceb79fef03 91 * API returns true and false otherwise.
kevman 0:38ceb79fef03 92 */
kevman 0:38ceb79fef03 93 virtual bool is_connected();
kevman 0:38ceb79fef03 94
kevman 0:38ceb79fef03 95 /** Get the local IP address
kevman 0:38ceb79fef03 96 *
kevman 0:38ceb79fef03 97 * @return Null-terminated representation of the local IP address
kevman 0:38ceb79fef03 98 * or null if no IP address has been received
kevman 0:38ceb79fef03 99 */
kevman 0:38ceb79fef03 100 virtual const char *get_ip_address();
kevman 0:38ceb79fef03 101
kevman 0:38ceb79fef03 102 /** Get the local network mask
kevman 0:38ceb79fef03 103 *
kevman 0:38ceb79fef03 104 * @return Null-terminated representation of the local network mask
kevman 0:38ceb79fef03 105 * or null if no network mask has been received
kevman 0:38ceb79fef03 106 */
kevman 0:38ceb79fef03 107 virtual const char *get_netmask();
kevman 0:38ceb79fef03 108
kevman 0:38ceb79fef03 109 /** Get the local gateways
kevman 0:38ceb79fef03 110 *
kevman 0:38ceb79fef03 111 * @return Null-terminated representation of the local gateway
kevman 0:38ceb79fef03 112 * or null if no network mask has been received
kevman 0:38ceb79fef03 113 */
kevman 0:38ceb79fef03 114 virtual const char *get_gateway();
kevman 0:38ceb79fef03 115
kevman 0:38ceb79fef03 116 /** Register callback for status reporting
kevman 0:38ceb79fef03 117 *
kevman 0:38ceb79fef03 118 * The specified status callback function will be called on status changes
kevman 0:38ceb79fef03 119 * on the network. The parameters on the callback are the event type and
kevman 0:38ceb79fef03 120 * event-type dependent reason parameter.
kevman 0:38ceb79fef03 121 *
kevman 0:38ceb79fef03 122 * @param status_cb The callback for status changes
kevman 0:38ceb79fef03 123 */
kevman 0:38ceb79fef03 124 virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
kevman 0:38ceb79fef03 125
kevman 0:38ceb79fef03 126 /** Turn modem debug traces on
kevman 0:38ceb79fef03 127 *
kevman 0:38ceb79fef03 128 * @param on set true to enable debug traces
kevman 0:38ceb79fef03 129 */
kevman 0:38ceb79fef03 130 void modem_debug_on(bool on);
kevman 0:38ceb79fef03 131
kevman 0:38ceb79fef03 132 /** Sets the operator plmn which is used when registering to a network specified by plmn. If plmn is not set then automatic
kevman 0:38ceb79fef03 133 * registering is used when registering to a cellular network.
kevman 0:38ceb79fef03 134 *
kevman 0:38ceb79fef03 135 * @param plmn operator in numeric format. See more from 3GPP TS 27.007 chapter 7.3.
kevman 0:38ceb79fef03 136 */
kevman 0:38ceb79fef03 137 void set_plmn(const char *plmn);
kevman 0:38ceb79fef03 138
kevman 0:38ceb79fef03 139 /** Get the cellular device from the cellular state machine
kevman 0:38ceb79fef03 140 *
kevman 0:38ceb79fef03 141 * @return cellular device
kevman 0:38ceb79fef03 142 */
kevman 0:38ceb79fef03 143 CellularDevice *get_device();
kevman 0:38ceb79fef03 144
kevman 0:38ceb79fef03 145 /** Get the UART serial file handle used by cellular subsystem
kevman 0:38ceb79fef03 146 *
kevman 0:38ceb79fef03 147 * @return address of cellular UART serial
kevman 0:38ceb79fef03 148 */
kevman 0:38ceb79fef03 149 UARTSerial *get_serial();
kevman 0:38ceb79fef03 150
kevman 0:38ceb79fef03 151 protected:
kevman 0:38ceb79fef03 152
kevman 0:38ceb79fef03 153 /** Provide access to the NetworkStack object
kevman 0:38ceb79fef03 154 *
kevman 0:38ceb79fef03 155 * @return The underlying NetworkStack object
kevman 0:38ceb79fef03 156 */
kevman 0:38ceb79fef03 157 virtual NetworkStack *get_stack();
kevman 0:38ceb79fef03 158
kevman 0:38ceb79fef03 159 private:
kevman 0:38ceb79fef03 160 /** Callback for cellular status changes
kevman 0:38ceb79fef03 161 *
kevman 0:38ceb79fef03 162 * @return true to continue state machine
kevman 0:38ceb79fef03 163 */
kevman 0:38ceb79fef03 164 bool cellular_status(int state, int next_state);
kevman 0:38ceb79fef03 165 void network_callback(nsapi_event_t ev, intptr_t ptr);
kevman 0:38ceb79fef03 166 nsapi_error_t init();
kevman 0:38ceb79fef03 167 nsapi_error_t check_connect();
kevman 0:38ceb79fef03 168
kevman 0:38ceb79fef03 169 bool _is_connected;
kevman 0:38ceb79fef03 170 bool _is_initialized;
kevman 0:38ceb79fef03 171 bool _stm_error;
kevman 0:38ceb79fef03 172 #if USE_APN_LOOKUP
kevman 0:38ceb79fef03 173 bool _credentials_set;
kevman 0:38ceb79fef03 174 #endif // #if USE_APN_LOOKUP
kevman 0:38ceb79fef03 175 CellularConnectionFSM::CellularState _target_state;
kevman 0:38ceb79fef03 176
kevman 0:38ceb79fef03 177 UARTSerial _cellularSerial;
kevman 0:38ceb79fef03 178 rtos::Semaphore _cellularSemaphore;
kevman 0:38ceb79fef03 179 CellularConnectionFSM *_cellularConnectionFSM;
kevman 0:38ceb79fef03 180 nsapi_error_t _credentials_err;
kevman 0:38ceb79fef03 181 Callback<void(nsapi_event_t, intptr_t)> _status_cb;
kevman 0:38ceb79fef03 182 };
kevman 0:38ceb79fef03 183
kevman 0:38ceb79fef03 184 } // namespace
kevman 0:38ceb79fef03 185
kevman 0:38ceb79fef03 186 #endif // CELLULAR_DEVICE || DOXYGEN
kevman 0:38ceb79fef03 187
kevman 0:38ceb79fef03 188 #endif // EASY_CELLULAR_CONNECTION_H
kevman 0:38ceb79fef03 189
kevman 0:38ceb79fef03 190 /** @}*/