Library that implements the CellularInterface using PPP and LWIP on the mbed MCU. May be used on the C027 and C030 (non-N2xx flavour) boards from mbed 5.5 onwards.
Dependents: example-ublox-cellular-interface HelloMQTT example-ublox-cellular-interface_r410M example-ublox-mbed-client
UbloxPPPCellularInterface.h@2:4c533665168c, 2017-06-30 (annotated)
- Committer:
- rob.meades@u-blox.com
- Date:
- Fri Jun 30 13:30:20 2017 +0100
- Revision:
- 2:4c533665168c
- Parent:
- 1:80ec3fccad9e
- Child:
- 3:9863dcade75d
Connect now fails correctly if it cannot achieve a connection, rather than trying for ever.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
RobMeades | 0:44dd95724bc2 | 1 | /* Copyright (c) 2017 ARM Limited |
RobMeades | 0:44dd95724bc2 | 2 | * |
RobMeades | 0:44dd95724bc2 | 3 | * Licensed under the Apache License, Version 2.0 (the "License"); |
RobMeades | 0:44dd95724bc2 | 4 | * you may not use this file except in compliance with the License. |
RobMeades | 0:44dd95724bc2 | 5 | * You may obtain a copy of the License at |
RobMeades | 0:44dd95724bc2 | 6 | * |
RobMeades | 0:44dd95724bc2 | 7 | * http://www.apache.org/licenses/LICENSE-2.0 |
RobMeades | 0:44dd95724bc2 | 8 | * |
RobMeades | 0:44dd95724bc2 | 9 | * Unless required by applicable law or agreed to in writing, software |
RobMeades | 0:44dd95724bc2 | 10 | * distributed under the License is distributed on an "AS IS" BASIS, |
RobMeades | 0:44dd95724bc2 | 11 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
RobMeades | 0:44dd95724bc2 | 12 | * See the License for the specific language governing permissions and |
RobMeades | 0:44dd95724bc2 | 13 | * limitations under the License. |
RobMeades | 0:44dd95724bc2 | 14 | */ |
RobMeades | 0:44dd95724bc2 | 15 | |
RobMeades | 0:44dd95724bc2 | 16 | #ifndef _UBLOX_PPP_CELLULAR_INTERFACE_ |
RobMeades | 0:44dd95724bc2 | 17 | #define _UBLOX_PPP_CELLULAR_INTERFACE_ |
RobMeades | 0:44dd95724bc2 | 18 | |
RobMeades | 0:44dd95724bc2 | 19 | #include "nsapi.h" |
RobMeades | 0:44dd95724bc2 | 20 | #include "CellularBase.h" |
RobMeades | 0:44dd95724bc2 | 21 | #include "NetworkStack.h" |
RobMeades | 0:44dd95724bc2 | 22 | #include "InterruptIn.h" |
RobMeades | 0:44dd95724bc2 | 23 | #include "UbloxCellularBase.h" |
RobMeades | 0:44dd95724bc2 | 24 | |
RobMeades | 0:44dd95724bc2 | 25 | #if NSAPI_PPP_AVAILABLE |
RobMeades | 0:44dd95724bc2 | 26 | |
RobMeades | 0:44dd95724bc2 | 27 | /********************************************************************** |
RobMeades | 0:44dd95724bc2 | 28 | * CLASSES |
RobMeades | 0:44dd95724bc2 | 29 | **********************************************************************/ |
RobMeades | 0:44dd95724bc2 | 30 | |
RobMeades | 0:44dd95724bc2 | 31 | /* Forward declaration */ |
RobMeades | 0:44dd95724bc2 | 32 | class NetworkStack; |
RobMeades | 0:44dd95724bc2 | 33 | |
RobMeades | 0:44dd95724bc2 | 34 | /* |
RobMeades | 0:44dd95724bc2 | 35 | * NOTE: order is important in the inheritance below! PAL takes this class |
RobMeades | 0:44dd95724bc2 | 36 | * and casts it to CellularInterface and so CellularInterface has to be first |
RobMeades | 0:44dd95724bc2 | 37 | * in the last for that to work. |
RobMeades | 0:44dd95724bc2 | 38 | */ |
RobMeades | 0:44dd95724bc2 | 39 | |
RobMeades | 0:44dd95724bc2 | 40 | /** UbloxPPPCellularInterface class. |
RobMeades | 0:44dd95724bc2 | 41 | * |
RobMeades | 0:44dd95724bc2 | 42 | * This class implements the network stack interface into the cellular |
RobMeades | 0:44dd95724bc2 | 43 | * modems on the C030 and C027 boards for 2G/3G/4G modules using |
RobMeades | 0:44dd95724bc2 | 44 | * LWIP running on the mbed MCU, connected to the modem via PPP. |
RobMeades | 0:44dd95724bc2 | 45 | */ |
RobMeades | 0:44dd95724bc2 | 46 | class UbloxPPPCellularInterface : public CellularBase, |
rob.meades@u-blox.com | 1:80ec3fccad9e | 47 | virtual public UbloxCellularBase { |
RobMeades | 0:44dd95724bc2 | 48 | |
RobMeades | 0:44dd95724bc2 | 49 | public: |
RobMeades | 0:44dd95724bc2 | 50 | /** Constructor. |
RobMeades | 0:44dd95724bc2 | 51 | * |
RobMeades | 0:44dd95724bc2 | 52 | * @param tx the UART TX data pin to which the modem is attached. |
RobMeades | 0:44dd95724bc2 | 53 | * @param rx the UART RX data pin to which the modem is attached. |
RobMeades | 0:44dd95724bc2 | 54 | * @param baud the UART baud rate. |
RobMeades | 0:44dd95724bc2 | 55 | * @param debug_on true to switch AT interface debug on, otherwise false. |
RobMeades | 0:44dd95724bc2 | 56 | */ |
RobMeades | 0:44dd95724bc2 | 57 | UbloxPPPCellularInterface(PinName tx = MDMTXD, |
rob.meades@u-blox.com | 1:80ec3fccad9e | 58 | PinName rx = MDMRXD, |
rob.meades@u-blox.com | 1:80ec3fccad9e | 59 | int baud = MBED_CONF_UBLOX_CELL_BAUD_RATE, |
rob.meades@u-blox.com | 1:80ec3fccad9e | 60 | bool debug_on = false); |
RobMeades | 0:44dd95724bc2 | 61 | |
RobMeades | 0:44dd95724bc2 | 62 | /* Destructor. |
RobMeades | 0:44dd95724bc2 | 63 | */ |
RobMeades | 0:44dd95724bc2 | 64 | virtual ~UbloxPPPCellularInterface(); |
RobMeades | 0:44dd95724bc2 | 65 | |
RobMeades | 0:44dd95724bc2 | 66 | /** Set the cellular network credentials. |
RobMeades | 0:44dd95724bc2 | 67 | * |
RobMeades | 0:44dd95724bc2 | 68 | * Please check documentation of connect() for default behaviour of APN settings. |
RobMeades | 0:44dd95724bc2 | 69 | * |
RobMeades | 0:44dd95724bc2 | 70 | * @param apn Access point name. |
RobMeades | 0:44dd95724bc2 | 71 | * @param uname optionally, username. |
RobMeades | 0:44dd95724bc2 | 72 | * @param pwd optionally, password. |
RobMeades | 0:44dd95724bc2 | 73 | */ |
RobMeades | 0:44dd95724bc2 | 74 | virtual void set_credentials(const char *apn, const char *uname = 0, |
RobMeades | 0:44dd95724bc2 | 75 | const char *pwd = 0); |
RobMeades | 0:44dd95724bc2 | 76 | |
RobMeades | 0:44dd95724bc2 | 77 | /** Set the PIN code for the SIM card. |
RobMeades | 0:44dd95724bc2 | 78 | * |
RobMeades | 0:44dd95724bc2 | 79 | * @param sim_pin PIN for the SIM card. |
RobMeades | 0:44dd95724bc2 | 80 | */ |
RobMeades | 0:44dd95724bc2 | 81 | virtual void set_sim_pin(const char *sim_pin); |
RobMeades | 0:44dd95724bc2 | 82 | |
RobMeades | 0:44dd95724bc2 | 83 | /** Connect to the cellular network and start the interface. |
RobMeades | 0:44dd95724bc2 | 84 | * |
RobMeades | 0:44dd95724bc2 | 85 | * Attempts to connect to a cellular network. Note: if init() has |
RobMeades | 0:44dd95724bc2 | 86 | * not been called beforehand, connect() will call it first. |
RobMeades | 0:44dd95724bc2 | 87 | * |
RobMeades | 0:44dd95724bc2 | 88 | * @param sim_pin PIN for the SIM card. |
RobMeades | 0:44dd95724bc2 | 89 | * @param apn optionally, access point name. |
RobMeades | 0:44dd95724bc2 | 90 | * @param uname optionally, username. |
RobMeades | 0:44dd95724bc2 | 91 | * @param pwd optionally, password. |
RobMeades | 0:44dd95724bc2 | 92 | * @return NSAPI_ERROR_OK on success, or negative error code on failure. |
RobMeades | 0:44dd95724bc2 | 93 | */ |
RobMeades | 0:44dd95724bc2 | 94 | virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, |
RobMeades | 0:44dd95724bc2 | 95 | const char *uname = 0, const char *pwd = 0); |
RobMeades | 0:44dd95724bc2 | 96 | |
RobMeades | 0:44dd95724bc2 | 97 | /** Attempt to connect to the cellular network. |
RobMeades | 0:44dd95724bc2 | 98 | * |
RobMeades | 0:44dd95724bc2 | 99 | * Brings up the network interface. Connects to the cellular radio |
RobMeades | 0:44dd95724bc2 | 100 | * network and then brings up the underlying network stack to be used |
RobMeades | 0:44dd95724bc2 | 101 | * by the cellular modem over PPP interface. Note: if init() has |
RobMeades | 0:44dd95724bc2 | 102 | * not been called beforehand, connect() will call it first. |
RobMeades | 0:44dd95724bc2 | 103 | * NOTE: even a failed attempt to connect will cause the modem to remain |
RobMeades | 0:44dd95724bc2 | 104 | * powered up. To power it down, call deinit(). |
RobMeades | 0:44dd95724bc2 | 105 | * |
RobMeades | 0:44dd95724bc2 | 106 | * For APN setup, default behaviour is to use 'internet' as APN string and |
RobMeades | 0:44dd95724bc2 | 107 | * assuming no authentication is required, i.e., user name and password are |
RobMeades | 0:44dd95724bc2 | 108 | * not set. Optionally, a database lookup can be requested by turning on |
RobMeades | 0:44dd95724bc2 | 109 | * the APN database lookup feature. The APN database is by no means exhaustive. |
RobMeades | 0:44dd95724bc2 | 110 | * It contains a short list of some public APNs with publicly available |
RobMeades | 0:44dd95724bc2 | 111 | * user names and passwords (if required) in some particular countries only. |
RobMeades | 0:44dd95724bc2 | 112 | * Lookup is done using IMSI (International mobile subscriber identifier). |
RobMeades | 0:44dd95724bc2 | 113 | * |
RobMeades | 0:44dd95724bc2 | 114 | * The preferred method is to setup APN using 'set_credentials()' API. |
RobMeades | 0:44dd95724bc2 | 115 | * |
RobMeades | 0:44dd95724bc2 | 116 | * If you find that the AT interface returns "CONNECT" but shortly afterwards drops the connection |
RobMeades | 0:44dd95724bc2 | 117 | * then 99% of the time this will be because the APN is incorrect. |
RobMeades | 0:44dd95724bc2 | 118 | * |
RobMeades | 0:44dd95724bc2 | 119 | * @return 0 on success, negative error code on failure. |
RobMeades | 0:44dd95724bc2 | 120 | */ |
RobMeades | 0:44dd95724bc2 | 121 | virtual nsapi_error_t connect(); |
RobMeades | 0:44dd95724bc2 | 122 | |
RobMeades | 0:44dd95724bc2 | 123 | /** Attempt to disconnect from the network. |
RobMeades | 0:44dd95724bc2 | 124 | * |
RobMeades | 0:44dd95724bc2 | 125 | * Brings down the network interface. Shuts down the PPP interface |
RobMeades | 0:44dd95724bc2 | 126 | * of the underlying network stack. Does not bring down the Radio network. |
RobMeades | 0:44dd95724bc2 | 127 | * |
RobMeades | 0:44dd95724bc2 | 128 | * @return 0 on success, negative error code on failure. |
RobMeades | 0:44dd95724bc2 | 129 | */ |
RobMeades | 0:44dd95724bc2 | 130 | virtual nsapi_error_t disconnect(); |
RobMeades | 0:44dd95724bc2 | 131 | |
RobMeades | 0:44dd95724bc2 | 132 | /** Adds or removes a SIM facility lock. |
RobMeades | 0:44dd95724bc2 | 133 | * |
RobMeades | 0:44dd95724bc2 | 134 | * Can be used to enable or disable SIM PIN check at device startup. |
RobMeades | 0:44dd95724bc2 | 135 | * |
RobMeades | 0:44dd95724bc2 | 136 | * @param set can be set to true if the SIM PIN check is supposed |
RobMeades | 0:44dd95724bc2 | 137 | * to be enabled and vice versa. |
RobMeades | 0:44dd95724bc2 | 138 | * @param immediate if true, change the SIM PIN now, else set a flag |
RobMeades | 0:44dd95724bc2 | 139 | * and make the change only when connect() is called. |
RobMeades | 0:44dd95724bc2 | 140 | * If this is true and init() has not been called previously, |
RobMeades | 0:44dd95724bc2 | 141 | * it will be called first. |
RobMeades | 0:44dd95724bc2 | 142 | * @param sim_pin the current SIM PIN, must be a const. If this is not |
RobMeades | 0:44dd95724bc2 | 143 | * provided, the SIM PIN must have previously been set by a |
RobMeades | 0:44dd95724bc2 | 144 | * call to set_sim_pin(). |
RobMeades | 0:44dd95724bc2 | 145 | * @return 0 on success, negative error code on failure. |
RobMeades | 0:44dd95724bc2 | 146 | */ |
RobMeades | 0:44dd95724bc2 | 147 | nsapi_error_t set_sim_pin_check(bool set, bool immediate = false, |
RobMeades | 0:44dd95724bc2 | 148 | const char *sim_pin = NULL); |
RobMeades | 0:44dd95724bc2 | 149 | |
RobMeades | 0:44dd95724bc2 | 150 | /** Change the PIN for the SIM card. |
RobMeades | 0:44dd95724bc2 | 151 | * |
RobMeades | 0:44dd95724bc2 | 152 | * Provide the new PIN for your SIM card with this API. It is ONLY possible to |
RobMeades | 0:44dd95724bc2 | 153 | * change the SIM PIN when SIM PIN checking is ENABLED. |
RobMeades | 0:44dd95724bc2 | 154 | * |
RobMeades | 0:44dd95724bc2 | 155 | * @param new_pin new PIN to be used in string format, must be a const. |
RobMeades | 0:44dd95724bc2 | 156 | * @param immediate if true, change the SIM PIN now, else set a flag |
RobMeades | 0:44dd95724bc2 | 157 | * and make the change only when connect() is called. |
RobMeades | 0:44dd95724bc2 | 158 | * If this is true and init() has not been called previously, |
RobMeades | 0:44dd95724bc2 | 159 | * it will be called first. |
RobMeades | 0:44dd95724bc2 | 160 | * @param old_pin old PIN, must be a const. If this is not provided, the SIM PIN |
RobMeades | 0:44dd95724bc2 | 161 | * must have previously been set by a call to set_sim_pin(). |
RobMeades | 0:44dd95724bc2 | 162 | * @return 0 on success, negative error code on failure. |
RobMeades | 0:44dd95724bc2 | 163 | */ |
RobMeades | 0:44dd95724bc2 | 164 | nsapi_error_t set_new_sim_pin(const char *new_pin, bool immediate = false, |
RobMeades | 0:44dd95724bc2 | 165 | const char *old_pin = NULL); |
RobMeades | 0:44dd95724bc2 | 166 | |
RobMeades | 0:44dd95724bc2 | 167 | /** Check if the connection is currently established or not. |
RobMeades | 0:44dd95724bc2 | 168 | * |
RobMeades | 0:44dd95724bc2 | 169 | * @return true/false If the cellular module have successfully acquired a carrier and is |
RobMeades | 0:44dd95724bc2 | 170 | * connected to an external packet data network using PPP, true |
RobMeades | 0:44dd95724bc2 | 171 | * is returned, otherwise false is returned. |
RobMeades | 0:44dd95724bc2 | 172 | */ |
RobMeades | 0:44dd95724bc2 | 173 | virtual bool is_connected(); |
RobMeades | 0:44dd95724bc2 | 174 | |
RobMeades | 0:44dd95724bc2 | 175 | /** Get the local IP address |
RobMeades | 0:44dd95724bc2 | 176 | * |
RobMeades | 0:44dd95724bc2 | 177 | * @return Null-terminated representation of the local IP address |
RobMeades | 0:44dd95724bc2 | 178 | * or null if no IP address has been received. |
RobMeades | 0:44dd95724bc2 | 179 | */ |
RobMeades | 0:44dd95724bc2 | 180 | virtual const char *get_ip_address(); |
RobMeades | 0:44dd95724bc2 | 181 | |
RobMeades | 0:44dd95724bc2 | 182 | /** Get the local network mask. |
RobMeades | 0:44dd95724bc2 | 183 | * |
RobMeades | 0:44dd95724bc2 | 184 | * @return Null-terminated representation of the local network mask |
RobMeades | 0:44dd95724bc2 | 185 | * or null if no network mask has been received. |
RobMeades | 0:44dd95724bc2 | 186 | */ |
RobMeades | 0:44dd95724bc2 | 187 | virtual const char *get_netmask(); |
RobMeades | 0:44dd95724bc2 | 188 | |
RobMeades | 0:44dd95724bc2 | 189 | /** Get the local gateways. |
RobMeades | 0:44dd95724bc2 | 190 | * |
RobMeades | 0:44dd95724bc2 | 191 | * @return Null-terminated representation of the local gateway |
RobMeades | 0:44dd95724bc2 | 192 | * or null if no network mask has been received. |
RobMeades | 0:44dd95724bc2 | 193 | */ |
RobMeades | 0:44dd95724bc2 | 194 | virtual const char *get_gateway(); |
RobMeades | 0:44dd95724bc2 | 195 | |
RobMeades | 0:44dd95724bc2 | 196 | /** Call back in case connection is lost. |
RobMeades | 0:44dd95724bc2 | 197 | * |
RobMeades | 0:44dd95724bc2 | 198 | * @param fptr the function to call. |
RobMeades | 0:44dd95724bc2 | 199 | */ |
RobMeades | 0:44dd95724bc2 | 200 | void connection_status_cb(Callback<void(nsapi_error_t)> cb); |
RobMeades | 0:44dd95724bc2 | 201 | |
RobMeades | 0:44dd95724bc2 | 202 | protected: |
RobMeades | 0:44dd95724bc2 | 203 | |
RobMeades | 0:44dd95724bc2 | 204 | /** The APN to use. |
RobMeades | 0:44dd95724bc2 | 205 | */ |
RobMeades | 0:44dd95724bc2 | 206 | const char *_apn; |
RobMeades | 0:44dd95724bc2 | 207 | |
RobMeades | 0:44dd95724bc2 | 208 | /** The user name to use. |
RobMeades | 0:44dd95724bc2 | 209 | */ |
RobMeades | 0:44dd95724bc2 | 210 | const char *_uname; |
RobMeades | 0:44dd95724bc2 | 211 | |
RobMeades | 0:44dd95724bc2 | 212 | /** The password to use. |
RobMeades | 0:44dd95724bc2 | 213 | */ |
RobMeades | 0:44dd95724bc2 | 214 | const char *_pwd; |
RobMeades | 0:44dd95724bc2 | 215 | |
RobMeades | 0:44dd95724bc2 | 216 | /** True if the PPP connection is active, otherwise false. |
RobMeades | 0:44dd95724bc2 | 217 | */ |
RobMeades | 0:44dd95724bc2 | 218 | bool _ppp_connection_up; |
RobMeades | 0:44dd95724bc2 | 219 | |
RobMeades | 0:44dd95724bc2 | 220 | /** Provide access to the underlying stack. |
RobMeades | 0:44dd95724bc2 | 221 | * |
RobMeades | 0:44dd95724bc2 | 222 | * @return The underlying network stack. |
RobMeades | 0:44dd95724bc2 | 223 | */ |
RobMeades | 0:44dd95724bc2 | 224 | virtual NetworkStack *get_stack(); |
RobMeades | 0:44dd95724bc2 | 225 | |
RobMeades | 0:44dd95724bc2 | 226 | /** Get the next set of credentials from the database. |
RobMeades | 0:44dd95724bc2 | 227 | */ |
rob.meades@u-blox.com | 2:4c533665168c | 228 | void get_next_credentials(const char ** config); |
RobMeades | 0:44dd95724bc2 | 229 | |
RobMeades | 0:44dd95724bc2 | 230 | private: |
RobMeades | 0:44dd95724bc2 | 231 | bool _sim_pin_check_change_pending; |
RobMeades | 0:44dd95724bc2 | 232 | bool _sim_pin_check_change_pending_enabled_value; |
RobMeades | 0:44dd95724bc2 | 233 | bool _sim_pin_change_pending; |
RobMeades | 0:44dd95724bc2 | 234 | const char *_sim_pin_change_pending_new_pin_value; |
RobMeades | 0:44dd95724bc2 | 235 | Callback<void(nsapi_error_t)> _connection_status_cb; |
RobMeades | 0:44dd95724bc2 | 236 | nsapi_error_t setup_context_and_credentials(); |
RobMeades | 0:44dd95724bc2 | 237 | bool set_atd(); |
RobMeades | 0:44dd95724bc2 | 238 | }; |
RobMeades | 0:44dd95724bc2 | 239 | |
rob.meades@u-blox.com | 1:80ec3fccad9e | 240 | #endif // NSAPI_PPP_AVAILABLE |
rob.meades@u-blox.com | 1:80ec3fccad9e | 241 | #endif // _UBLOX_PPP_CELLULAR_INTERFACE_ |
RobMeades | 0:44dd95724bc2 | 242 |