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 "CellularUtil.h"
23 #include "ControlPlane_netif.h"
24 #include "PinNames.h"
25 
26 /** @file CellularContext.h
27  * @brief Cellular PDP context class
28  *
29  */
30 
31 namespace mbed {
32 
33 /**
34  * @addtogroup cellular
35  * @{
36  */
37 
38 /// CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity
40 
41 public:
42 
43  // max simultaneous PDP contexts active
44  static const int PDP_CONTEXT_COUNT = 4;
45 
46  /* authentication type when activating or modifying the pdp context */
47  enum AuthenticationType {
48  NOAUTH = 0,
49  PAP,
50  CHAP,
51  AUTOMATIC
52  };
53 
54  /* whether the additional exception reports are allowed to be sent when the maximum uplink rate is reached */
55  enum RateControlExceptionReports {
56  NotAllowedToBeSent = 0,
57  AllowedToBeSent
58  };
59 
60  /* specifies the time unit to be used for the maximum uplink rate */
61  enum RateControlUplinkTimeUnit {
62  Unrestricted = 0,
63  Minute,
64  Hour,
65  Day,
66  Week
67  };
68 
69  /// PDP Context information
71  char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
72  char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
73  char local_subnet_mask[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
74  char gateway_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
75  char dns_primary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
76  char dns_secondary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
77  char p_cscf_prim_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
78  char p_cscf_sec_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
79  int cid;
80  int bearer_id;
81  int im_signalling_flag;
82  int lipa_indication;
83  int ipv4_mtu;
84  int wlan_offload;
85  int local_addr_ind;
86  int non_ip_mtu;
87  int serving_plmn_rate_control_value;
88  pdpcontext_params_t *next;
89 
91  {
92  apn[0] = '\0';
93  local_addr[0] = '\0';
94  local_subnet_mask[0] = '\0';
95  gateway_addr[0] = '\0';
96  dns_primary_addr[0] = '\0';
97  dns_secondary_addr[0] = '\0';
98  p_cscf_prim_addr[0] = '\0';
99  p_cscf_sec_addr[0] = '\0';
100  cid = -1;
101  bearer_id = -1;
102  im_signalling_flag = -1;
103  lipa_indication = -1;
104  ipv4_mtu = -1;
105  wlan_offload = -1;
106  local_addr_ind = -1;
107  non_ip_mtu = -1;
108  serving_plmn_rate_control_value = -1;
109  next = NULL;
110  }
111  };
113 
114  // pointer for next item when used as a linked list
115  CellularContext *_next;
116 protected:
117  // friend of CellularDevice, so it's the only way to close or delete this class.
118  friend class CellularDevice;
119  CellularContext();
120  virtual ~CellularContext() {}
121 public: // from NetworkInterface
122  virtual nsapi_error_t set_blocking(bool blocking) = 0;
123  virtual NetworkStack *get_stack() = 0;
124  virtual nsapi_error_t get_ip_address(SocketAddress *address) = 0;
125  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
126  virtual const char *get_ip_address() = 0;
127 
128  /** Register callback for status reporting.
129  *
130  * The specified status callback function is called on the network, and the cellular device status changes.
131  * The parameters on the callback are the event type and event type dependent reason parameter.
132  *
133  * @remark deleting CellularDevice/CellularContext in callback is not allowed.
134  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
135  * is now 2048. You can change to main thread for example via EventQueue.
136  *
137  * @param status_cb The callback for status changes.
138  */
139  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
140  virtual nsapi_error_t connect() = 0;
141  virtual nsapi_error_t disconnect() = 0;
142 
143  // from CellularInterface
144  virtual void set_plmn(const char *plmn) = 0;
145  virtual void set_sim_pin(const char *sim_pin) = 0;
146  virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,
147  const char *pwd = 0) = 0;
148  virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0;
149  virtual nsapi_error_t get_netmask(SocketAddress *address) = 0;
150  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
151  virtual const char *get_netmask() = 0;
152  virtual nsapi_error_t get_gateway(SocketAddress *address) = 0;
153  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
154  virtual const char *get_gateway() = 0;
155  virtual bool is_connected() = 0;
156 
157  /** Same as NetworkInterface::get_default_instance()
158  *
159  * @note not to be used if get_default_nonip_instance() was already used
160  *
161  */
163 
164 
165  /** Instantiates a default Non-IP cellular interface
166  *
167  * This function creates a new Non-IP PDP context.
168  *
169  * @note not to be used if get_default_instance() was already used
170  *
171  * @return A Non-IP cellular PDP context
172  *
173  */
175 
176  /** Get pointer to CellularDevice instance. May be null if not AT-layer.
177  *
178  * @return pointer to CellularDevice instance
179  */
180  CellularDevice *get_device() const;
181 
182 // Operations, can be sync/async. Also Connect() is this kind of operation, inherited from NetworkInterface above.
183 
184  /** Start the interface
185  *
186  * Initializes the modem for communication.
187  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
188  * In synchronous and asynchronous mode application can get result in from callback which is set with
189  * attach(...)
190  *
191  * @return NSAPI_ERROR_OK on success
192  * NSAPI_ERROR_NO_MEMORY on case of memory failure
193  */
194  virtual nsapi_error_t set_device_ready() = 0;
195 
196  /** Start the interface
197  *
198  * Attempts to open the SIM.
199  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
200  * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
201  * attach(...)
202  *
203  * @return NSAPI_ERROR_OK on success
204  * NSAPI_ERROR_NO_MEMORY on case of memory failure
205  */
206  virtual nsapi_error_t set_sim_ready() = 0;
207 
208  /** Start the interface
209  *
210  * Attempts to register the device to cellular network.
211  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
212  * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
213  * attach(...)
214  *
215  * @return NSAPI_ERROR_OK on success
216  * NSAPI_ERROR_NO_MEMORY on case of memory failure
217  */
218  virtual nsapi_error_t register_to_network() = 0;
219 
220  /** Start the interface
221  *
222  * Attempts to attach the device to cellular network.
223  * By default, this API is synchronous. API can be set to asynchronous with method set_blocking(...).
224  * In synchronous and asynchronous mode, the application can get result in from callback, which is set with
225  * attach(...)
226  *
227  * @return NSAPI_ERROR_OK on success
228  * NSAPI_ERROR_NO_MEMORY on case of memory failure
229  */
230  virtual nsapi_error_t attach_to_network() = 0;
231 
232 // PDP Context specific functions
233 
234  /** Get APN rate control.
235  *
236  * @remark optional params are not updated if not received from network, so use good defaults
237  * @param reports Additional exception reports at maximum rate reached are allowed to be sent [optional]
238  * @param time_unit Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
239  * @param uplink_rate Maximum number of messages per timeUnit [optional]
240  * @return NSAPI_ERROR_OK on success
241  * NSAPI_ERROR_DEVICE_ERROR on case of failure
242  */
243  virtual nsapi_error_t get_rate_control(CellularContext::RateControlExceptionReports &reports,
244  CellularContext::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
245 
246  /** Get the relevant information for an active nonsecondary PDP context.
247  *
248  * @remark optional params are not updated if not received from network.
249  * @param params_list reference to linked list, which is filled on successful call
250  * @return NSAPI_ERROR_OK on success
251  * NSAPI_ERROR_NO_MEMORY on memory failure
252  * NSAPI_ERROR_DEVICE_ERROR on other failures
253  */
254  virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list) = 0;
255 
256  /** Get backoff timer value
257  *
258  * @param backoff_timer Backoff timer value associated with PDP APN in seconds
259  * @return NSAPI_ERROR_OK on success
260  * NSAPI_ERROR_PARAMETER if no access point is set or found when activating context
261  * NSAPI_ERROR_DEVICE_ERROR on failure
262  */
263  virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
264 
265  /** Set the file handle used to communicate with the modem. You can use this to change the default file handle.
266  *
267  * @param fh file handle for communicating with the modem
268  */
269  virtual void set_file_handle(FileHandle *fh) = 0;
270 
271 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
272  /** Set the UART serial used to communicate with the modem. Can be used to change default file handle.
273  * File handle set with this method will use data carrier detect to be able to detect disconnection much faster in PPP mode.
274  *
275  * @param serial UARTSerial used in communication to modem. If null then the default file handle is used.
276  * @param dcd_pin Pin used to set data carrier detect on/off for the given UART
277  * @param active_high a boolean set to true if DCD polarity is active low
278  */
279  virtual void set_file_handle(UARTSerial *serial, PinName dcd_pin = NC, bool active_high = false) = 0;
280 #endif // #if DEVICE_SERIAL
281 
282  /** Returns the control plane AT command interface
283  */
284  virtual ControlPlane_netif *get_cp_netif() = 0;
285 
286  /** Get the pdp context id associated with this context.
287  *
288  * @return cid
289  */
290  int get_cid() const;
291 
292  /** Set the authentication type to be used in user authentication if user name and password are defined
293  *
294  * @param type enum AuthenticationType
295  */
296  void set_authentication_type(AuthenticationType type);
297 
298 protected: // Device specific implementations might need these so protected
299  enum ContextOperation {
300  OP_INVALID = -1,
301  OP_DEVICE_READY = 0,
302  OP_SIM_READY = 1,
303  OP_REGISTER = 2,
304  OP_ATTACH = 3,
305  OP_CONNECT = 4,
306  OP_MAX = 5
307  };
308 
309  /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
310  *
311  * @param ev event type
312  * @param ptr event-type dependent reason parameter
313  */
314  virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr) = 0;
315 
316  /** Enable or disable hang-up detection
317  *
318  * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
319  * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
320  * signaling is not desired. enable_hup() controls whether this function should be
321  * active.
322  */
323  virtual void enable_hup(bool enable) = 0;
324 
325  /** Triggers control plane's operations needed when control plane data is received,
326  * like socket event, for example.
327  */
328  void cp_data_received();
329 
330  /** Retry logic after device attached to network. Retry to find and activate pdp context or in case
331  * of PPP find correct pdp context and open data channel. Retry logic is the same which is used in
332  * CellularStateMachine.
333  */
334  virtual void do_connect_with_retry();
335 
336  /** Helper method to call callback function if it is provided
337  *
338  * @param status connection status which is parameter in callback function
339  */
340  void call_network_cb(nsapi_connection_status_t status);
341 
342  /** Find and activate pdp context or in case of PPP find correct pdp context and open data channel.
343  */
344  virtual void do_connect();
345 
346  /** After we have connected successfully we must check that we have a valid IP address.
347  * Some modems/networks don't give IP address right after connect so we must poll it for a while.
348  */
349  void validate_ip_address();
350 
351  // member variables needed in target override methods
352  NetworkStack *_stack; // must be pointer because of PPP
353  pdp_type_t _pdp_type;
354  CellularContext::AuthenticationType _authentication_type;
355  nsapi_connection_status_t _connect_status;
356  cell_callback_data_t _cb_data;
358  int _cid;
359  bool _new_context_set;
360  bool _is_context_active;
361  bool _is_context_activated; // did we activate the context
362  const char *_apn;
363  const char *_uname;
364  const char *_pwd;
365  PinName _dcd_pin;
366  bool _active_high;
367 
368  ControlPlane_netif *_cp_netif;
369  uint16_t _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
370  int _retry_array_length;
371  int _retry_count;
372  CellularDevice *_device;
373  CellularNetwork *_nw;
374  bool _is_blocking;
375  // flag indicating if Non-IP context was requested to be setup
376  bool _nonip_req;
377  // tells if CCIOTOPTI received green from network for CP optimization use
378  bool _cp_in_use;
379 };
380 
381 /**
382  * @}
383  */
384 
385 } // namespace mbed
386 
387 
388 #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 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
Class CellularList.
Definition: CellularList.h:30
CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity...
void validate_ip_address()
After we have connected successfully we must check that we have a valid IP address.
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:51
int get_cid() const
Get the pdp context id associated with this context.
Class CellularDevice.
virtual void set_plmn(const char *plmn)=0
Set the plmn.
static CellularContext * get_default_instance()
Same as NetworkInterface::get_default_instance()
An abstract interface for connecting to a network and getting information from it.
SocketAddress class.
Definition: SocketAddress.h:35
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.
void call_network_cb(nsapi_connection_status_t status)
Helper method to call callback function if it is provided.
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 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.
virtual void do_connect()
Find and activate pdp context or in case of PPP find correct pdp context and open data channel...
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.
void set_authentication_type(AuthenticationType type)
Set the authentication type to be used in user authentication if user name and password are defined...
virtual nsapi_error_t disconnect()=0
Stop the interface.
Callback class based on template specialization.
Definition: Callback.h:39
CellularDevice * get_device() const
Get pointer to CellularDevice instance.
virtual nsapi_error_t attach_to_network()=0
Start the interface.
virtual void do_connect_with_retry()
Retry logic after device attached to network.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
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.