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

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.