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 "netsocket/NetworkStack.h"
21 #include "netsocket/CellularInterface.h"
22 #include "CellularDevice.h"
23 #include "CellularUtil.h"
25 #include "PinNames.h"
26 
27 /** @file CellularContext.h
28  * @brief Cellular PDP context class
29  *
30  */
31 
32 namespace mbed {
33 
34 /**
35  * @addtogroup cellular
36  * @{
37  */
38 
39 /// CellularContext is CellularInterface/NetworkInterface with extensions for cellular connectivity
41 
42 public:
43 
44  // max simultaneous PDP contexts active
45  static const int PDP_CONTEXT_COUNT = 4;
46 
47  /* authentication type when activating or modifying the pdp context */
48  enum AuthenticationType {
49  NOAUTH = 0,
50  PAP,
51  CHAP,
52  AUTOMATIC
53  };
54 
55  /* whether the additional exception reports are allowed to be sent when the maximum uplink rate is reached */
56  enum RateControlExceptionReports {
57  NotAllowedToBeSent = 0,
58  AllowedToBeSent
59  };
60 
61  /* specifies the time unit to be used for the maximum uplink rate */
62  enum RateControlUplinkTimeUnit {
63  Unrestricted = 0,
64  Minute,
65  Hour,
66  Day,
67  Week
68  };
69 
70  /// PDP Context information
72  char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
73  char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
74  char local_subnet_mask[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
75  char gateway_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
76  char dns_primary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
77  char dns_secondary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
78  char p_cscf_prim_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
79  char p_cscf_sec_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
80  int cid;
81  int bearer_id;
82  int im_signalling_flag;
83  int lipa_indication;
84  int ipv4_mtu;
85  int wlan_offload;
86  int local_addr_ind;
87  int non_ip_mtu;
88  int serving_plmn_rate_control_value;
89  pdpcontext_params_t *next;
90 
92  {
93  apn[0] = '\0';
94  local_addr[0] = '\0';
95  local_subnet_mask[0] = '\0';
96  gateway_addr[0] = '\0';
97  dns_primary_addr[0] = '\0';
98  dns_secondary_addr[0] = '\0';
99  p_cscf_prim_addr[0] = '\0';
100  p_cscf_sec_addr[0] = '\0';
101  cid = -1;
102  bearer_id = -1;
103  im_signalling_flag = -1;
104  lipa_indication = -1;
105  ipv4_mtu = -1;
106  wlan_offload = -1;
107  local_addr_ind = -1;
108  non_ip_mtu = -1;
109  serving_plmn_rate_control_value = -1;
110  next = NULL;
111  }
112  };
114 
115  // pointer for next item when used as a linked list
116  CellularContext *_next;
117 protected:
118  // friend of CellularDevice, so it's the only way to close or delete this class.
119  friend class CellularDevice;
120  CellularContext();
121  virtual ~CellularContext()
122  {
123 #if !NSAPI_PPP_AVAILABLE
124  if (_stack) {
125  delete _stack;
126  }
127 #endif
128  }
129 
130 public: // from NetworkInterface
131  virtual nsapi_error_t set_blocking(bool blocking) = 0;
132  virtual NetworkStack *get_stack() = 0;
133  virtual nsapi_error_t get_ip_address(SocketAddress *address) = 0;
134 
135  /** Register callback for status reporting.
136  *
137  * The specified status callback function is called on the network, and the cellular device status changes.
138  * The parameters on the callback are the event type and event type dependent reason parameter.
139  *
140  * @remark deleting CellularDevice/CellularContext in callback is not allowed.
141  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
142  * is now 2048. You can change to main thread for example via EventQueue.
143  *
144  * @param status_cb The callback for status changes.
145  */
146  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
147  virtual nsapi_error_t connect() = 0;
148  virtual nsapi_error_t disconnect() = 0;
149 
150  // from CellularInterface
151  virtual void set_plmn(const char *plmn) = 0;
152  virtual void set_sim_pin(const char *sim_pin) = 0;
153  virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,
154  const char *pwd = 0) = 0;
155  virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0;
156  virtual bool is_connected() = 0;
157 
158  /** Same as NetworkInterface::get_default_instance()
159  *
160  * @note not to be used if get_default_nonip_instance() was already used
161  *
162  */
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 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
266 
267  /** Enable or disable hang-up detection.
268  *
269  * This method will use data carrier detect to be able to detect disconnection much faster in PPP mode.
270  *
271  * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
272  * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
273  * signaling is not desired.
274  *
275  * @param dcd_pin Pin used to set data carrier detect on/off for the given UART. NC if feature is disabled.
276  * @param active_high a boolean set to true if DCD polarity is active low
277  *
278  * @return NSAPI_ERROR_OK if success,
279  * NSAPI_ERROR_UNSUPPORTED if modem does not support this feature
280  */
281  virtual nsapi_error_t configure_hup(PinName dcd_pin = NC, bool active_high = false) = 0;
282 #endif // #if DEVICE_SERIAL
283 
284  /** Returns the control plane AT command interface
285  */
286  virtual ControlPlane_netif *get_cp_netif() = 0;
287 
288  /** Get the pdp context id associated with this context.
289  *
290  * @return cid
291  */
292  int get_cid() const;
293 
294  /** Set the authentication type to be used in user authentication if user name and password are defined
295  *
296  * @param type enum AuthenticationType
297  */
298  void set_authentication_type(AuthenticationType type);
299 
300 protected: // Device specific implementations might need these so protected
301  enum ContextOperation {
302  OP_INVALID = -1,
303  OP_DEVICE_READY = 0,
304  OP_SIM_READY = 1,
305  OP_REGISTER = 2,
306  OP_ATTACH = 3,
307  OP_CONNECT = 4,
308  OP_MAX = 5
309  };
310 
311  enum pdp_type_t {
312  DEFAULT_PDP_TYPE = DEFAULT_STACK,
313  IPV4_PDP_TYPE = IPV4_STACK,
314  IPV6_PDP_TYPE = IPV6_STACK,
315  IPV4V6_PDP_TYPE = IPV4V6_STACK,
316  NON_IP_PDP_TYPE
317  };
318 
319  /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
320  *
321  * @param ev event type
322  * @param ptr event-type dependent reason parameter
323  */
324  virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr) = 0;
325 
326  /** Return PDP type string for Non-IP if modem uses other than standard "Non-IP"
327  *
328  * Some modems uses a non-standard PDP type string for non-ip (e.g. "NONIP").
329  * In those cases modem driver must implement this method to return the PDP type string
330  * used by the modem.
331  *
332  * @return PDP type string used by the modem or NULL if standard ("Non-IP")
333  */
334  virtual const char *get_nonip_context_type_str() = 0;
335 
336  /** Triggers control plane's operations needed when control plane data is received,
337  * like socket event, for example.
338  */
339  void cp_data_received();
340 
341  /** Retry logic after device attached to network. Retry to find and activate pdp context or in case
342  * of PPP find correct pdp context and open data channel. Retry logic is the same which is used in
343  * CellularStateMachine.
344  */
345  virtual void do_connect_with_retry();
346 
347  /** Helper method to call callback function if it is provided
348  *
349  * @param status connection status which is parameter in callback function
350  */
351  void call_network_cb(nsapi_connection_status_t status);
352 
353  /** Find and activate pdp context or in case of PPP find correct pdp context and open data channel.
354  */
355  virtual void do_connect();
356 
357  /** After we have connected successfully we must check that we have a valid IP address.
358  * Some modems/networks don't give IP address right after connect so we must poll it for a while.
359  */
360  void validate_ip_address();
361 
362  /** Converts the given pdp type in char format to enum pdp_type_t
363  *
364  * @param pdp_type pdp type in string format
365  * @return converted pdp_type_t enum
366  */
367  CellularContext::pdp_type_t string_to_pdp_type(const char *pdp_type);
368 
369 protected:
370  // member variables needed in target override methods
371  NetworkStack *_stack; // must be pointer because of PPP
372  pdp_type_t _pdp_type;
373  CellularContext::AuthenticationType _authentication_type;
374  nsapi_connection_status_t _connect_status;
375  cell_callback_data_t _cb_data;
377  int _cid;
378  bool _new_context_set;
379  bool _is_context_active;
380  bool _is_context_activated; // did we activate the context
381  const char *_apn;
382  const char *_uname;
383  const char *_pwd;
384 
385  ControlPlane_netif *_cp_netif;
386  uint16_t _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
387  int _retry_array_length;
388  int _retry_count;
389  CellularDevice *_device;
390  CellularNetwork *_nw;
391  bool _is_blocking;
392  // flag indicating if Non-IP context was requested to be setup
393  bool _nonip_req;
394  // tells if CCIOTOPTI received green from network for CP optimization use
395  bool _cp_in_use;
396 };
397 
398 /**
399  * @}
400  */
401 
402 } // namespace mbed
403 
404 
405 #endif /* _CELLULARCONTEXT_H_ */
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:41
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
virtual nsapi_error_t connect()=0
Attempt to connect to a cellular network.
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.
virtual nsapi_error_t configure_hup(PinName dcd_pin=NC, bool active_high=false)=0
Enable or disable hang-up detection.
virtual const char * get_nonip_context_type_str()=0
Return PDP type string for Non-IP if modem uses other than standard "Non-IP".
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:36
void cp_data_received()
Triggers control plane&#39;s operations needed when control plane data is received, like socket event...
virtual nsapi_error_t get_ip_address(SocketAddress *address)=0
Get the local IP address.
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...
NetworkStack class.
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.
CellularContext::pdp_type_t string_to_pdp_type(const char *pdp_type)
Converts the given pdp type in char format to enum pdp_type_t.
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:53
Definition: ATHandler.h:46
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.
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.