Mistake on this page?
Report an issue in GitHub or email us
CellularNetwork.h
1 /* Copyright (c) 2017,2018 Arm Limited and affiliates.
2  * SPDX-License-Identifier: Apache-2.0
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef CELLULAR_NETWORK_H_
18 #define CELLULAR_NETWORK_H_
19 
20 #include "CellularList.h"
21 #include "Callback.h"
22 #include "nsapi_types.h"
23 
24 namespace mbed {
25 
26 /* Maximum length of IPV6 address in ipv4-like dotted format. More info in 3gpp 27007.*/
27 const int MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT = 63;
28 /* Maximum length of access point name */
29 const int MAX_ACCESSPOINT_NAME_LENGTH = 100;
30 const int MAX_OPERATOR_NAME_LONG = 16;
31 const int MAX_OPERATOR_NAME_SHORT = 8;
32 
33 /**
34  * @addtogroup cellular
35  * @{
36  */
37 
38 /// An abstract interface for connecting to a network and getting information from it.
40 protected:
41  // friend of CellularDevice so that it's the only way to close/delete this class.
42  friend class CellularDevice;
43 
44  virtual ~CellularNetwork() {}
45 
46 public:
47  /* Definition for Supported CIoT EPS optimizations type. */
48  enum CIoT_Supported_Opt {
49  CIOT_OPT_NO_SUPPORT = 0, /* No support. */
50  CIOT_OPT_CONTROL_PLANE, /* Support for control plane CIoT EPS optimization. */
51  CIOT_OPT_USER_PLANE, /* Support for user plane CIoT EPS optimization. */
52  CIOT_OPT_BOTH, /* Support for both control plane CIoT EPS optimization and user plane CIoT EPS
53  optimization. */
54  CIOT_OPT_MAX
55  };
56 
57  /* Definition for Preferred CIoT EPS optimizations type. */
58  enum CIoT_Preferred_UE_Opt {
59  PREFERRED_UE_OPT_NO_PREFERENCE = 0, /* No preference. */
60  PREFERRED_UE_OPT_CONTROL_PLANE, /* Preference for control plane CIoT EPS optimization. */
61  PREFERRED_UE_OPT_USER_PLANE, /* Preference for user plane CIoT EPS optimization. */
62  PREFERRED_UE_OPT_MAX
63  };
64 
65  /* Network registration status */
66  enum RegistrationStatus {
67  StatusNotAvailable = -1,
68  NotRegistered = 0,
69  RegisteredHomeNetwork,
70  SearchingNetwork,
71  RegistrationDenied,
72  Unknown,
73  RegisteredRoaming,
74  RegisteredSMSOnlyHome,
75  RegisteredSMSOnlyRoaming,
76  AttachedEmergencyOnly,
77  RegisteredCSFBNotPreferredHome,
78  RegisteredCSFBNotPreferredRoaming,
79  AlreadyRegistered = 11, // our definition when modem says that we are not registered but we have active PDP Context
80  RegistrationStatusMax
81  };
82 
83  /* Network registration type */
84  enum RegistrationType {
85  C_EREG = 0,
86  C_GREG,
87  C_REG,
88  C_MAX
89  };
90 
91  /* device attach status to network */
92  enum AttachStatus {
93  Detached = 0,
94  Attached,
95  };
96 
97  enum RadioAccessTechnology {
98  RAT_GSM,
99  RAT_GSM_COMPACT,
100  RAT_UTRAN,
101  RAT_EGPRS,
102  RAT_HSDPA,
103  RAT_HSUPA,
104  RAT_HSDPA_HSUPA,
105  RAT_E_UTRAN,
106  RAT_CATM1,
107  RAT_NB1,
108  RAT_UNKNOWN,
109  RAT_MAX = 11 // to reserve string array
110  };
111 
112  /// 3GPP TS 27.007 - 7.3 PLMN selection +COPS
113  struct operator_t {
114  enum Status {
115  Unknown,
116  Available,
117  Current,
118  Forbiden
119  };
120 
121  Status op_status;
122  char op_long[MAX_OPERATOR_NAME_LONG + 1];
123  char op_short[MAX_OPERATOR_NAME_SHORT + 1];
124  char op_num[MAX_OPERATOR_NAME_SHORT + 1];
125  RadioAccessTechnology op_rat;
126  operator_t *next;
127 
128  operator_t()
129  {
130  op_status = Unknown;
131  op_rat = RAT_UNKNOWN;
132  next = NULL;
133  op_long[0] = '\0';
134  op_short[0] = '\0';
135  op_num[0] = '\0';
136  }
137  };
138 
140 
141  /// Cellular operator names in numeric and alpha format
143  char numeric[MAX_OPERATOR_NAME_SHORT + 1];
144  char alpha[MAX_OPERATOR_NAME_LONG + 1];
145  operator_names_t *next;
147  {
148  numeric[0] = '\0';
149  alpha[0] = '\0';
150  next = NULL;
151  }
152  };
154 
155  /// Network registering mode
157  NWModeAutomatic = 0, // automatic registering
158  NWModeManual, // manual registering with plmn
159  NWModeDeRegister, // deregister from network
160  NWModeSetOnly, // set only <format> (for read command +COPS?), do not attempt registration/deregistration
161  NWModeManualAutomatic // if manual fails, fallback to automatic
162  };
163 
164  /// Network registration information
166  RegistrationType _type;
167  RegistrationStatus _status;
168  RadioAccessTechnology _act;
169  int _cell_id;
170  int _lac;
171  int _active_time;
172  int _periodic_tau;
173 
175  {
176  _type = C_MAX;
177  _status = StatusNotAvailable;
178  _act = RAT_UNKNOWN;
179  _cell_id = -1;
180  _lac = -1;
181  _active_time = -1;
182  _periodic_tau = -1;
183  }
184  };
185 
186  /** Request registering to network.
187  *
188  * @param plmn format is in numeric format or 0 for automatic network registration
189  * @return NSAPI_ERROR_OK on success
190  * NSAPI_ERROR_DEVICE_ERROR on failure
191  */
192  virtual nsapi_error_t set_registration(const char *plmn = 0) = 0;
193 
194  /** Get the current network registering mode
195  *
196  * @param mode on successful return contains the current network registering mode
197  * @return NSAPI_ERROR_OK on success
198  * NSAPI_ERROR_DEVICE_ERROR on failure
199  */
201 
202  /** Activate/deactivate listening of network events for the given RegistrationType.
203  * This should be called after network class is created and ready to receive AT commands.
204  * After successful call network class starts to get information about network changes like
205  * registration statue, access technology, cell id...
206  *
207  * @param type RegistrationType to set urc on/off
208  * @param on Controls are urc active or not
209  * @return NSAPI_ERROR_OK on success
210  * NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
211  * NSAPI_ERROR_DEVICE_ERROR on failure
212  */
213  virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0;
214 
215 
216  /** Request attach to network.
217  *
218  * @return NSAPI_ERROR_OK on success
219  * NSAPI_ERROR_DEVICE_ERROR on failure
220  */
221  virtual nsapi_error_t set_attach() = 0;
222 
223  /** Request attach status from network.
224  *
225  * @param status see AttachStatus values
226  * @return NSAPI_ERROR_OK on success
227  * NSAPI_ERROR_DEVICE_ERROR on failure
228  */
229  virtual nsapi_error_t get_attach(AttachStatus &status) = 0;
230 
231  /** Request detach and deregister from a network.
232  *
233  * @return NSAPI_ERROR_OK on success
234  * NSAPI_ERROR_DEVICE_ERROR on failure
235  */
236  virtual nsapi_error_t detach() = 0;
237 
238  /** Sets radio access technology.
239  *
240  * @param rat Radio access technology
241  * @return NSAPI_ERROR_OK on success
242  * NSAPI_ERROR_UNSUPPORTED if the given rat is RAT_UNKNOWN or inheriting target class
243  * has not implemented method set_access_technology_impl(...)
244  * OR return value of the inheriting target class set_access_technology_impl(...)
245  */
246  virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0;
247 
248  /** Scans for operators module can reach.
249  *
250  * @param operators Container of reachable operators and their access technologies
251  * @param ops_count Number of found operators
252  * @return NSAPI_ERROR_OK on success
253  * NSAPI_ERROR_NO_MEMORY on memory failure
254  * NSAPI_ERROR_DEVICE_ERROR on other failures
255  */
256  virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0;
257 
258  /** Set CIoT optimizations.
259  *
260  * @param supported_opt Supported CIoT EPS optimizations
261  * (the HW support can be checked with get_ciot_ue_optimization_config).
262  * @param preferred_opt Preferred CIoT EPS optimizations.
263  * @param network_support_cb This callback will be called when CIoT network optimization support is known
264  * @return NSAPI_ERROR_OK on success
265  * NSAPI_ERROR_DEVICE_ERROR on failure
266  */
267  virtual nsapi_error_t set_ciot_optimization_config(CIoT_Supported_Opt supported_opt,
268  CIoT_Preferred_UE_Opt preferred_opt,
269  Callback<void(CIoT_Supported_Opt)> network_support_cb) = 0;
270 
271  /** Get UE CIoT optimizations.
272  *
273  * @param supported_opt Supported CIoT EPS optimizations.
274  * @param preferred_opt Preferred CIoT EPS optimizations.
275  * @return NSAPI_ERROR_OK on success
276  * NSAPI_ERROR_DEVICE_ERROR on failure
277  */
278  virtual nsapi_error_t get_ciot_ue_optimization_config(CIoT_Supported_Opt &supported_opt,
279  CIoT_Preferred_UE_Opt &preferred_opt) = 0;
280 
281  /** Get Network CIoT optimizations.
282  *
283  * @param supported_network_opt Supported CIoT EPS optimizations. CIOT_OPT_MAX will be returned,
284  * if the support is not known
285  * @return NSAPI_ERROR_OK on success
286  * NSAPI_ERROR_DEVICE_ERROR on failure
287  */
288  virtual nsapi_error_t get_ciot_network_optimization_config(CIoT_Supported_Opt &supported_network_opt) = 0;
289 
290  /** Get signal quality parameters.
291  *
292  * @param rssi signal strength level as defined in 3GPP TS 27.007, range -113..-51 dBm or SignalQualityUnknown
293  * @param ber bit error rate as RXQUAL as defined in 3GPP TS 45.008, range 0..7 or SignalQualityUnknown
294  * @return NSAPI_ERROR_OK on success
295  * NSAPI_ERROR_DEVICE_ERROR on other failures
296  */
298  SignalQualityUnknown = 99
299  };
300  virtual nsapi_error_t get_signal_quality(int &rssi, int *ber = NULL) = 0;
301 
302  /** Get the last 3GPP error code
303  * @return see 3GPP TS 27.007 error codes
304  */
305  virtual int get_3gpp_error() = 0;
306 
307  /** Get the operator parameters.
308  *
309  * @param format format of the operator field
310  * @param operator_params applicable operator param fields filled
311  * @return NSAPI_ERROR_OK on success
312  * NSAPI_ERROR_DEVICE_ERROR on case of other failures
313  */
314  virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0;
315 
316  /** Register callback for status reporting
317  *
318  * The specified status callback function will be called on status changes
319  * on the network. The parameters on the callback are the event type and
320  * event-type dependent reason parameter.
321  *
322  * @remark Application should not call attach if using CellularContext class. Call instead CellularContext::attach
323  * as CellularDevice is dependent of this attach if CellularContext/CellularDevice is used to get
324  * device/sim ready, registered, attached, connected.
325  *
326  * @param status_cb The callback for status changes
327  */
328  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
329 
330  /** Read operator names
331  *
332  * @param op_names on successful return contains linked list of operator names.
333  * @return NSAPI_ERROR_OK on success
334  * NSAPI_ERROR_NO_MEMORY on memory failure
335  * NSAPI_ERROR_DEVICE_ERROR on other failures
336  */
337  virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0;
338 
339  /** Check if there is any PDP context active. If cid is given, then check is done only for that cid.
340  *
341  * @param number_of_active_contexts If given then in return contains the number of active contexts
342  * @param cid If given then active contexts are checked only against this cid
343  *
344  * @return true if any (or the given cid) context is active, false otherwise or in case of error
345  */
346  virtual bool is_active_context(int *number_of_active_contexts = NULL, int cid = -1) = 0;
347 
348  /** Gets the latest received registration parameters from the network:
349  * type, status, access technology, cell_id, lac, active_time, periodic_tau.
350  *
351  * @param reg_params see registration_params_t
352  * @return NSAPI_ERROR_OK on success
353  * NSAPI_ERROR_DEVICE_ERROR on failure
354  */
356 
357  /** Gets the current network registration parameters from the network with type:
358  * status, access technology, cell_id, lac, active_time, periodic_tau.
359  *
360  * @param type see RegistrationType values
361  * @param reg_params see registration_params_t
362  * @return NSAPI_ERROR_OK on success
363  * NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
364  * NSAPI_ERROR_DEVICE_ERROR on failure
365  */
366  virtual nsapi_error_t get_registration_params(RegistrationType type, registration_params_t &reg_params) = 0;
367 
368  /** Set discontinuous reception time on cellular device.
369  *
370  * @remark See 3GPP TS 27.007 eDRX for details.
371  *
372  * @param mode disable or enable the use of eDRX
373  * @param act_type type of access technology
374  * @param edrx_value requested edxr value. Extended DRX parameters information element.
375  *
376  * @return NSAPI_ERROR_OK on success
377  * NSAPI_ERROR_DEVICE_ERROR on failure
378  */
380  EDRXGSM_EC_GSM_IoT_mode = 1,
381  EDRXGSM_A_Gb_mode,
382  EDRXUTRAN_Iu_mode,
383  EDRXEUTRAN_WB_S1_mode,
384  EDRXEUTRAN_NB_S1_mode
385  };
386  virtual nsapi_error_t set_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0;
387 
388  /** Sets the packet domain network reporting. Useful for getting events when detached from the
389  * network. When detach event arrives it is propagated as NSAPI_STATUS_DISCONNECTED to callback set
390  * with attach(...).
391  *
392  * @param on true for enabling event reporting, false for disabling
393  * @return NSAPI_ERROR_OK on success
394  * NSAPI_ERROR_UNSUPPORTED is command is not supported by the modem
395  * NSAPI_ERROR_DEVICE_ERROR on failure
396  */
398  {
400  }
401 };
402 
403 /**
404  * @}
405  */
406 
407 } // namespace mbed
408 
409 #endif // CELLULAR_NETWORK_H_
virtual nsapi_error_t get_ciot_network_optimization_config(CIoT_Supported_Opt &supported_network_opt)=0
Get Network CIoT optimizations.
virtual nsapi_error_t get_ciot_ue_optimization_config(CIoT_Supported_Opt &supported_opt, CIoT_Preferred_UE_Opt &preferred_opt)=0
Get UE CIoT optimizations.
virtual int get_3gpp_error()=0
Get the last 3GPP error code.
virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode &mode)=0
Get the current network registering mode.
Class CellularList.
Definition: CellularList.h:30
virtual nsapi_error_t set_attach()=0
Request attach to network.
virtual nsapi_error_t set_registration(const char *plmn=0)=0
Request registering to network.
Class CellularDevice.
NWRegisteringMode
Network registering mode.
SignalQuality
Get signal quality parameters.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count)=0
Scans for operators module can reach.
virtual void attach(mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)=0
Register callback for status reporting.
virtual nsapi_error_t get_operator_names(operator_names_list &op_names)=0
Read operator names.
Cellular operator names in numeric and alpha format.
Network registration information.
virtual nsapi_error_t set_ciot_optimization_config(CIoT_Supported_Opt supported_opt, CIoT_Preferred_UE_Opt preferred_opt, Callback< void(CIoT_Supported_Opt)> network_support_cb)=0
Set CIoT optimizations.
virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params)=0
Get the operator parameters.
An abstract interface for connecting to a network and getting information from it.
virtual nsapi_error_t detach()=0
Request detach and deregister from a network.
virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat)=0
Sets radio access technology.
EDRXAccessTechnology
Set discontinuous reception time on cellular device.
virtual nsapi_error_t set_packet_domain_event_reporting(bool on)
Sets the packet domain network reporting.
3GPP TS 27.007 - 7.3 PLMN selection +COPS
virtual bool is_active_context(int *number_of_active_contexts=NULL, int cid=-1)=0
Check if there is any PDP context active.
virtual nsapi_error_t get_registration_params(registration_params_t &reg_params)=0
Gets the latest received registration parameters from the network: type, status, access technology...
virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on)=0
Activate/deactivate listening of network events for the given RegistrationType.
Callback class based on template specialization.
Definition: Callback.h:39
virtual nsapi_error_t get_attach(AttachStatus &status)=0
Request attach status from 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.