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 const char *get_ip_address() = 0;
125 
126  /** Register callback for status reporting.
127  *
128  * The specified status callback function is called on the network, and the cellular device status changes.
129  * The parameters on the callback are the event type and event type dependent reason parameter.
130  *
131  * @remark deleting CellularDevice/CellularContext in callback is not allowed.
132  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
133  * is now 2048. You can change to main thread for example via EventQueue.
134  *
135  * @param status_cb The callback for status changes.
136  */
137  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
138  virtual nsapi_error_t connect() = 0;
139  virtual nsapi_error_t disconnect() = 0;
140 
141  // from CellularInterface
142  virtual void set_plmn(const char *plmn) = 0;
143  virtual void set_sim_pin(const char *sim_pin) = 0;
144  virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,
145  const char *pwd = 0) = 0;
146  virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0;
147  virtual const char *get_netmask() = 0;
148  virtual const char *get_gateway() = 0;
149  virtual bool is_connected() = 0;
150 
151  /** Same as NetworkInterface::get_default_instance()
152  *
153  * @note not to be used if get_default_nonip_instance() was already used
154  *
155  */
157 
158 
159  /** Instantiates a default Non-IP cellular interface
160  *
161  * This function creates a new Non-IP PDP context.
162  *
163  * @note not to be used if get_default_instance() was already used
164  *
165  * @return A Non-IP cellular PDP context
166  *
167  */
169 
170  /** Get pointer to CellularDevice instance. May be null if not AT-layer.
171  *
172  * @return pointer to CellularDevice instance
173  */
174  CellularDevice *get_device() const;
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  /** Get the pdp context id associated with this context.
281  *
282  * @return cid
283  */
284  int get_cid() const;
285 
286  /** Set the authentication type to be used in user authentication if user name and password are defined
287  *
288  * @param type enum AuthenticationType
289  */
290  void set_authentication_type(AuthenticationType type);
291 
292 protected: // Device specific implementations might need these so protected
293  enum ContextOperation {
294  OP_INVALID = -1,
295  OP_DEVICE_READY = 0,
296  OP_SIM_READY = 1,
297  OP_REGISTER = 2,
298  OP_ATTACH = 3,
299  OP_CONNECT = 4,
300  OP_MAX = 5
301  };
302 
303  /** The CellularDevice calls the status callback function on status changes on the network or CellularDevice.
304  *
305  * @param ev event type
306  * @param ptr event-type dependent reason parameter
307  */
308  virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr) = 0;
309 
310  /** Enable or disable hang-up detection
311  *
312  * When in PPP data pump mode, it is helpful if the FileHandle will signal hang-up via
313  * POLLHUP, e.g., if the DCD line is deasserted on a UART. During command mode, this
314  * signaling is not desired. enable_hup() controls whether this function should be
315  * active.
316  */
317  virtual void enable_hup(bool enable) = 0;
318 
319  /** Triggers control plane's operations needed when control plane data is received,
320  * like socket event, for example.
321  */
322  void cp_data_received();
323 
324  /** Retry logic after device attached to network. Retry to find and activate pdp context or in case
325  * of PPP find correct pdp context and open data channel. Retry logic is the same which is used in
326  * CellularStateMachine.
327  */
328  virtual void do_connect_with_retry();
329 
330  /** Helper method to call callback function if it is provided
331  *
332  * @param status connection status which is parameter in callback function
333  */
334  void call_network_cb(nsapi_connection_status_t status);
335 
336  /** Find and activate pdp context or in case of PPP find correct pdp context and open data channel.
337  */
338  virtual void do_connect();
339 
340  /** After we have connected successfully we must check that we have a valid IP address.
341  * Some modems/networks don't give IP address right after connect so we must poll it for a while.
342  */
343  void validate_ip_address();
344 
345  // member variables needed in target override methods
346  NetworkStack *_stack; // must be pointer because of PPP
347  pdp_type_t _pdp_type;
348  CellularContext::AuthenticationType _authentication_type;
349  nsapi_connection_status_t _connect_status;
350  cell_callback_data_t _cb_data;
352  int _cid;
353  bool _new_context_set;
354  bool _is_context_active;
355  bool _is_context_activated; // did we activate the context
356  const char *_apn;
357  const char *_uname;
358  const char *_pwd;
359  PinName _dcd_pin;
360  bool _active_high;
361 
362  ControlPlane_netif *_cp_netif;
363  uint16_t _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
364  int _retry_array_length;
365  int _retry_count;
366  CellularDevice *_device;
367  CellularNetwork *_nw;
368  bool _is_blocking;
369  // flag indicating if Non-IP context was requested to be setup
370  bool _nonip_req;
371  // tells if CCIOTOPTI received green from network for CP optimization use
372  bool _cp_in_use;
373 };
374 
375 /**
376  * @}
377  */
378 
379 } // namespace mbed
380 
381 
382 #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...
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.
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 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.
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.
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.