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  CellularContext();
126  virtual ~CellularContext() {}
127 public: // from NetworkInterface
128  virtual nsapi_error_t set_blocking(bool blocking) = 0;
129  virtual NetworkStack *get_stack() = 0;
130  virtual const char *get_ip_address() = 0;
131 
132  /** Register callback for status reporting.
133  *
134  * The specified status callback function is called on the network, and the cellular device status changes.
135  * The parameters on the callback are the event type and event type dependent reason parameter.
136  *
137  * @remark deleting CellularDevice/CellularContext in callback is not allowed.
138  * @remark Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
139  * is now 2048. You can change to main thread for example via EventQueue.
140  *
141  * @param status_cb The callback for status changes.
142  */
143  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
144  virtual nsapi_error_t connect() = 0;
145  virtual nsapi_error_t disconnect() = 0;
146 
147  // from CellularInterface
148  virtual void set_plmn(const char *plmn) = 0;
149  virtual void set_sim_pin(const char *sim_pin) = 0;
150  virtual nsapi_error_t connect(const char *sim_pin, const char *apn = 0, const char *uname = 0,
151  const char *pwd = 0) = 0;
152  virtual void set_credentials(const char *apn, const char *uname = 0, const char *pwd = 0) = 0;
153  virtual const char *get_netmask() = 0;
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 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  // member variables needed in target override methods
341  NetworkStack *_stack; // must be pointer because of PPP
342  pdp_type_t _pdp_type;
343  CellularContext::AuthenticationType _authentication_type;
344  nsapi_connection_status_t _connect_status;
345  cell_callback_data_t _cb_data;
347  int _cid;
348  bool _new_context_set;
349  bool _is_context_active;
350  bool _is_context_activated; // did we activate the context
351  const char *_apn;
352  const char *_uname;
353  const char *_pwd;
354  PinName _dcd_pin;
355  bool _active_high;
356 
357  ControlPlane_netif *_cp_netif;
358  uint16_t _retry_timeout_array[CELLULAR_RETRY_ARRAY_SIZE];
359  int _retry_array_length;
360  int _retry_count;
361  CellularDevice *_device;
362  CellularNetwork *_nw;
363  bool _is_blocking;
364 };
365 
366 /**
367  * @}
368  */
369 
370 } // namespace mbed
371 
372 
373 #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
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.
virtual nsapi_error_t disconnect()=0
Stop the interface.
Callback class based on template specialization.
Definition: Callback.h:39
Definition: AnalogIn.h:28
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.