Mistake on this page?
Report an issue in GitHub or email us
CellularContext.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2018, 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 #ifndef _CELLULARCONTEXT_H_
18 #define _CELLULARCONTEXT_H_
19 
20 #include "CellularInterface.h"
21 #include "CellularDevice.h"
22 #include "ControlPlane_netif.h"
23 #include "PinNames.h"
24 
25 /** @file CellularContext.h
26  * @brief Cellular PDP context class
27  *
28  */
29 
30 namespace mbed {
31 
32 typedef enum pdp_type {
33  DEFAULT_PDP_TYPE = DEFAULT_STACK,
34  IPV4_PDP_TYPE = IPV4_STACK,
35  IPV6_PDP_TYPE = IPV6_STACK,
36  IPV4V6_PDP_TYPE = IPV4V6_STACK,
37  NON_IP_PDP_TYPE
38 } pdp_type_t;
39 
40 /**
41  * @addtogroup cellular
42  * @{
43  */
44 
45 /// CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity
47 
48 public:
49 
50  // max simultaneous PDP contexts active
51  static const int PDP_CONTEXT_COUNT = 4;
52 
53  /* authentication type when activating or modifying the pdp context */
54  enum AuthenticationType {
55  NOAUTH = 0,
56  PAP,
57  CHAP
58  };
59 
60  /* whether the additional exception reports are allowed to be sent when the maximum uplink rate is reached */
61  enum RateControlExceptionReports {
62  NotAllowedToBeSent = 0,
63  AllowedToBeSent
64  };
65 
66  /* specifies the time unit to be used for the maximum uplink rate */
67  enum RateControlUplinkTimeUnit {
68  Unrestricted = 0,
69  Minute,
70  Hour,
71  Day,
72  Week
73  };
74 
75  /// PDP Context information
77  char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
78  char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
79  char local_subnet_mask[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
80  char gateway_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
81  char dns_primary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
82  char dns_secondary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
83  char p_cscf_prim_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
84  char p_cscf_sec_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
85  int cid;
86  int bearer_id;
87  int im_signalling_flag;
88  int lipa_indication;
89  int ipv4_mtu;
90  int wlan_offload;
91  int local_addr_ind;
92  int non_ip_mtu;
93  int serving_plmn_rate_control_value;
94  pdpcontext_params_t *next;
95 
97  {
98  apn[0] = '\0';
99  local_addr[0] = '\0';
100  local_subnet_mask[0] = '\0';
101  gateway_addr[0] = '\0';
102  dns_primary_addr[0] = '\0';
103  dns_secondary_addr[0] = '\0';
104  p_cscf_prim_addr[0] = '\0';
105  p_cscf_sec_addr[0] = '\0';
106  cid = -1;
107  bearer_id = -1;
108  im_signalling_flag = -1;
109  lipa_indication = -1;
110  ipv4_mtu = -1;
111  wlan_offload = -1;
112  local_addr_ind = -1;
113  non_ip_mtu = -1;
114  serving_plmn_rate_control_value = -1;
115  next = NULL;
116  }
117  };
119 
120  // pointer for next item when used as a linked list
121  CellularContext *_next;
122 protected:
123  // friend of CellularDevice, so it's the only way to close or delete this class.
124  friend class CellularDevice;
125  virtual ~CellularContext() {}
126 public: // from NetworkInterface
127  virtual nsapi_error_t set_blocking(bool blocking) = 0;
128  virtual NetworkStack *get_stack() = 0;
129  virtual const char *get_ip_address() = 0;
130 
131  /** Register callback for status reporting.
132  *
133  * The specified status callback function is called on the network, and the cellular device status changes.
134  * The parameters on the callback are the event type and event type dependent reason parameter.
135  *
136  * @remark deleting CellularDevice/CellularContext in callback is not allowed.
137  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
138  * is now 2048. You can change to main thread for example via EventQueue.
139  *
140  * @param status_cb The callback for status changes.
141  */
142  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
143  virtual nsapi_error_t connect() = 0;
144  virtual nsapi_error_t disconnect() = 0;
145 
146  // from CellularInterface
147  virtual void set_plmn(const char *plmn) = 0;
148  virtual void set_sim_pin(const char *sim_pin) = 0;
149  virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,
150  const char *pwd = 0) = 0;
151  virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0;
152  virtual const char *get_netmask() = 0;
153  virtual const char *get_gateway() = 0;
154  virtual bool is_connected() = 0;
155 
156  /** Same as NetworkInterface::get_default_instance()
157  *
158  * @note not to be used if get_default_nonip_instance() was already used
159  *
160  */
162 
163 
164  /** Instantiates a default Non-IP cellular interface
165  *
166  * This function creates a new Non-IP PDP context.
167  *
168  * @note not to be used if get_default_instance() was already used
169  *
170  * @return A Non-IP cellular PDP context
171  *
172  */
174 
175 
176 // Operations, can be sync/async. Also Connect() is this kind of operation, inherited from NetworkInterface above.
177 
178  /** Start the interface
179  *
180  * Initializes the modem for communication.
181  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
182  * In synchronous and asynchronous mode application can get result in from callback which is set with
183  * attach(...)
184  *
185  * @return NSAPI_ERROR_OK on success
186  * NSAPI_ERROR_NO_MEMORY on case of memory failure
187  */
188  virtual nsapi_error_t set_device_ready() = 0;
189 
190  /** Start the interface
191  *
192  * Attempts to open the SIM.
193  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
194  * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
195  * attach(...)
196  *
197  * @return NSAPI_ERROR_OK on success
198  * NSAPI_ERROR_NO_MEMORY on case of memory failure
199  */
200  virtual nsapi_error_t set_sim_ready() = 0;
201 
202  /** Start the interface
203  *
204  * Attempts to register the device to cellular network.
205  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
206  * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
207  * attach(...)
208  *
209  * @return NSAPI_ERROR_OK on success
210  * NSAPI_ERROR_NO_MEMORY on case of memory failure
211  */
212  virtual nsapi_error_t register_to_network() = 0;
213 
214  /** Start the interface
215  *
216  * Attempts to attach the device to cellular network.
217  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
218  * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
219  * attach(...)
220  *
221  * @return NSAPI_ERROR_OK on success
222  * NSAPI_ERROR_NO_MEMORY on case of memory failure
223  */
224  virtual nsapi_error_t attach_to_network() = 0;
225 
226 // PDP Context specific functions
227 
228  /** Get APN rate control.
229  *
230  * @remark optional params are not updated if not received from network, so use good defaults
231  * @param reports Additional exception reports at maximum rate reached are allowed to be sent [optional]
232  * @param time_unit Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
233  * @param uplink_rate Maximum number of messages per timeUnit [optional]
234  * @return NSAPI_ERROR_OK on success
235  * NSAPI_ERROR_DEVICE_ERROR on case of failure
236  */
237  virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports,
238  CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
239 
240  /** Get the relevant information for an active nonsecondary PDP context.
241  *
242  * @remark optional params are not updated if not received from network.
243  * @param params_list reference to linked list, which is filled on successful call
244  * @return NSAPI_ERROR_OK on success
245  * NSAPI_ERROR_NO_MEMORY on memory failure
246  * NSAPI_ERROR_DEVICE_ERROR on other failures
247  */
248  virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list) = 0;
249 
250  /** Get backoff timer value
251  *
252  * @param backoff_timer Backoff timer value associated with PDP APN in seconds
253  * @return NSAPI_ERROR_OK on success
254  * NSAPI_ERROR_PARAMETER if no access point is set or found when activating context
255  * NSAPI_ERROR_DEVICE_ERROR on failure
256  */
257  virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
258 
259  /** Set the file handle used to communicate with the modem. You can use this to change the default file handle.
260  *
261  * @param fh file handle for communicating with the modem
262  */
263  virtual void set_file_handle(FileHandle *fh) = 0;
264 
265 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
266  /** Set the UART serial used to communicate with the modem. Can be used to change default file handle.
267  * File handle set with this method will use data carrier detect to be able to detect disconnection much faster in PPP mode.
268  *
269  * @param serial UARTSerial used in communication to modem. If null then the default file handle is used.
270  * @param dcd_pin Pin used to set data carrier detect on/off for the given UART
271  * @param active_high a boolean set to true if DCD polarity is active low
272  */
273  virtual void set_file_handle(UARTSerial *serial, PinName dcd_pin = NC, bool active_high = false) = 0;
274 #endif // #if DEVICE_SERIAL
275 
276  /** Returns the control plane AT command interface
277  */
278  virtual ControlPlane_netif *get_cp_netif() = 0;
279 
280 protected: // Device specific implementations might need these so protected
281  enum ContextOperation {
282  OP_INVALID = -1,
283  OP_DEVICE_READY = 0,
284  OP_SIM_READY = 1,
285  OP_REGISTER = 2,
286  OP_ATTACH = 3,
287  OP_CONNECT = 4,
288  OP_MAX = 5
289  };
290 
291  /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
292  *
293  * @param ev event type
294  * @param ptr event-type dependent reason parameter
295  */
296  virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr) = 0;
297 
298  /** Enable or disable hang-up detection
299  *
300  * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
301  * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
302  * signaling is not desired. enable_hup() controls whether this function should be
303  * active.
304  */
305  virtual void enable_hup(bool enable) = 0;
306 
307  /** Triggers control plane's operations needed when control plane data is received,
308  * like socket event, for example.
309  */
310  void cp_data_received();
311 
312  // member variables needed in target override methods
313  NetworkStack *_stack; // must be pointer because of PPP
314  pdp_type_t _pdp_type;
315  CellularContext::AuthenticationType _authentication_type;
316  nsapi_connection_status_t _connect_status;
317  cell_callback_data_t _cb_data;
319  int _cid;
320  bool _new_context_set;
321  bool _is_context_active;
322  bool _is_context_activated; // did we activate the context
323  const char *_apn;
324  const char *_uname;
325  const char *_pwd;
326  PinName _dcd_pin;
327  bool _active_high;
328 
329  ControlPlane_netif *_cp_netif;
330 };
331 
332 /**
333  * @}
334  */
335 
336 } // namespace mbed
337 
338 
339 #endif /* _CELLULARCONTEXT_H_ */
virtual void enable_hup(bool enable)=0
Enable or disable hang-up detection.
virtual nsapi_error_t set_sim_ready()=0
Start the interface.
Implements support for data transfer using Control Plane CIoT EPS optimization specified in 3GPP 23...
virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports, CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate)=0
Get APN rate control.
virtual const char * get_netmask()=0
Get the local network mask.
virtual nsapi_error_t register_to_network()=0
Start the interface.
virtual nsapi_error_t set_blocking(bool blocking)=0
Set asynchronous operation of connect() and disconnect() calls.
virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr)=0
The CellularDevice calls the status callback function on status changes on the network or CellularDev...
NetworkStack class.
Definition: NetworkStack.h:40
virtual const char * get_ip_address()=0
Get the local IP address.
Class CellularList.
Definition: CellularList.h:30
CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity...
Implements support for data transfer using Control Plane CIoT EPS optimization.
Class CellularDevice.
virtual void set_sim_pin(const char *sim_pin)=0
Set the PIN code for SIM card.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
Class FileHandle.
Definition: FileHandle.h:46
virtual void set_file_handle(FileHandle *fh)=0
Set the file handle used to communicate with the modem.
virtual nsapi_error_t connect()=0
Attempt to connect to a cellular network.
Class providing buffered UART communication functionality using separate circular buffer for send and...
Definition: UARTSerial.h:50
Class CellularDevice.
virtual void set_plmn(const char *plmn)=0
Set the plmn.
static CellularContext * get_default_instance()
Same as NetworkInterface::get_default_instance()
void cp_data_received()
Triggers control plane&#39;s operations needed when control plane data is received, like socket event...
virtual void attach(mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)=0
Register callback for status reporting.
static CellularContext * get_default_nonip_instance()
Instantiates a default Non-IP cellular interface.
virtual bool is_connected()=0
Check if the connection is currently established.
virtual const char * get_gateway()=0
Get the local gateways.
virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer)=0
Get backoff timer value.
virtual ControlPlane_netif * get_cp_netif()=0
Returns the control plane AT command interface.
virtual void set_credentials(const char *apn, const char *uname=0, const char *pwd=0)=0
Set the cellular network credentials.
Common interface that is shared between cellular interfaces.
virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list)=0
Get the relevant information for an active nonsecondary PDP context.
virtual nsapi_error_t set_device_ready()=0
Start the interface.
virtual nsapi_error_t disconnect()=0
Stop the interface.
Callback class based on template specialization.
Definition: Callback.h:39
Definition: AnalogIn.h:28
virtual nsapi_error_t attach_to_network()=0
Start the interface.
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.