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 "netsocket/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  /// Operator name format
166  OperatorNameAlphaLong = 0, // alphanumeric long form
167  OperatorNameAlphaShort, // alphanumeric short form
168  OperatorNameNumeric // numeric digits
169  };
170 
171  /// Network registration information
173  RegistrationType _type;
174  RegistrationStatus _status;
175  RadioAccessTechnology _act;
176  int _cell_id;
177  int _lac;
178  int _active_time;
179  int _periodic_tau;
180 
182  {
183  _type = C_MAX;
184  _status = StatusNotAvailable;
185  _act = RAT_UNKNOWN;
186  _cell_id = -1;
187  _lac = -1;
188  _active_time = -1;
189  _periodic_tau = -1;
190  }
191  };
192 
193  /** Request registering to network.
194  *
195  * @param plmn format is in numeric format or 0 for automatic network registration
196  * @return NSAPI_ERROR_OK on success
197  * NSAPI_ERROR_DEVICE_ERROR on failure
198  */
199  virtual nsapi_error_t set_registration(const char *plmn = 0) = 0;
200 
201  /** Get the current network registering mode
202  *
203  * @param mode on success the current network registering mode, otherwise unchanged
204  * @return NSAPI_ERROR_OK on success
205  * NSAPI_ERROR_DEVICE_ERROR on failure
206  */
208 
209  /** Activate/deactivate listening of network events for the given RegistrationType.
210  * This should be called after network class is created and ready to receive AT commands.
211  * After successful call network class starts to get information about network changes like
212  * registration statue, access technology, cell id...
213  *
214  * @param type RegistrationType to set urc on/off
215  * @param on Controls are urc active or not
216  * @return NSAPI_ERROR_OK on success
217  * NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
218  * NSAPI_ERROR_DEVICE_ERROR on failure
219  */
220  virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0;
221 
222 
223  /** Request attach to network.
224  *
225  * @return NSAPI_ERROR_OK on success
226  * NSAPI_ERROR_DEVICE_ERROR on failure
227  */
228  virtual nsapi_error_t set_attach() = 0;
229 
230  /** Request attach status from network.
231  *
232  * @param status see AttachStatus values
233  * @return NSAPI_ERROR_OK on success
234  * NSAPI_ERROR_DEVICE_ERROR on failure
235  */
236  virtual nsapi_error_t get_attach(AttachStatus &status) = 0;
237 
238  /** Request detach and deregister from a network.
239  *
240  * @return NSAPI_ERROR_OK on success
241  * NSAPI_ERROR_DEVICE_ERROR on failure
242  */
243  virtual nsapi_error_t detach() = 0;
244 
245  /** Sets radio access technology.
246  *
247  * @param rat Radio access technology
248  * @return NSAPI_ERROR_OK on success
249  * NSAPI_ERROR_UNSUPPORTED if the given rat is RAT_UNKNOWN or inheriting target class
250  * has not implemented method set_access_technology_impl(...)
251  * OR return value of the inheriting target class set_access_technology_impl(...)
252  */
253  virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0;
254 
255  /** Scans for operators module can reach.
256  *
257  * @param operators Container of reachable operators and their access technologies
258  * @param ops_count Number of found operators
259  * @return NSAPI_ERROR_OK on success
260  * NSAPI_ERROR_NO_MEMORY on memory failure
261  * NSAPI_ERROR_DEVICE_ERROR on other failures
262  */
263  virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0;
264 
265  /** Set CIoT optimizations.
266  *
267  * @param supported_opt Supported CIoT EPS optimizations
268  * (the HW support can be checked with get_ciot_ue_optimization_config).
269  * @param preferred_opt Preferred CIoT EPS optimizations.
270  * @param network_support_cb This callback will be called when CIoT network optimization support is known
271  * @return NSAPI_ERROR_OK on success
272  * NSAPI_ERROR_DEVICE_ERROR on failure
273  */
274  virtual nsapi_error_t set_ciot_optimization_config(CIoT_Supported_Opt supported_opt,
275  CIoT_Preferred_UE_Opt preferred_opt,
276  Callback<void(CIoT_Supported_Opt)> network_support_cb) = 0;
277 
278  /** Get UE CIoT optimizations.
279  *
280  * @param supported_opt Supported CIoT EPS optimizations.
281  * @param preferred_opt Preferred CIoT EPS optimizations.
282  * @return NSAPI_ERROR_OK on success
283  * NSAPI_ERROR_DEVICE_ERROR on failure
284  */
285  virtual nsapi_error_t get_ciot_ue_optimization_config(CIoT_Supported_Opt &supported_opt,
286  CIoT_Preferred_UE_Opt &preferred_opt) = 0;
287 
288  /** Get Network CIoT optimizations.
289  *
290  * @param supported_network_opt Supported CIoT EPS optimizations. CIOT_OPT_MAX will be returned,
291  * if the support is not known
292  * @return NSAPI_ERROR_OK on success
293  * NSAPI_ERROR_DEVICE_ERROR on failure
294  */
295  virtual nsapi_error_t get_ciot_network_optimization_config(CIoT_Supported_Opt &supported_network_opt) = 0;
296 
297  /** Get signal quality parameters.
298  *
299  * @param rssi signal strength level as defined in 3GPP TS 27.007, range -113..-51 dBm or SignalQualityUnknown
300  * @param ber bit error rate as RXQUAL as defined in 3GPP TS 45.008, range 0..7 or SignalQualityUnknown
301  * @return NSAPI_ERROR_OK on success
302  * NSAPI_ERROR_DEVICE_ERROR on other failures
303  */
305  SignalQualityUnknown = 99
306  };
307  virtual nsapi_error_t get_signal_quality(int &rssi, int *ber = NULL) = 0;
308 
309  /** Get the last 3GPP error code
310  * @return see 3GPP TS 27.007 error codes
311  */
312  virtual int get_3gpp_error() = 0;
313 
314  /** Get the operator parameters.
315  *
316  * @param format format of the operator field
317  * @param operator_params applicable operator param fields filled
318  * @return NSAPI_ERROR_OK on success
319  * NSAPI_ERROR_DEVICE_ERROR on case of other failures
320  */
321  virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0;
322 
323  /** Register callback for status reporting
324  *
325  * The specified status callback function will be called on status changes
326  * on the network. The parameters on the callback are the event type and
327  * event-type dependent reason parameter.
328  *
329  * @remark Application should not call attach if using CellularContext class. Call instead CellularContext::attach
330  * as CellularDevice is dependent of this attach if CellularContext/CellularDevice is used to get
331  * device/sim ready, registered, attached, connected.
332  *
333  * @param status_cb The callback for status changes
334  */
335  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
336 
337  /** Read operator names
338  *
339  * @param op_names on successful return contains linked list of operator names.
340  * @return NSAPI_ERROR_OK on success
341  * NSAPI_ERROR_NO_MEMORY on memory failure
342  * NSAPI_ERROR_DEVICE_ERROR on other failures
343  */
344  virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0;
345 
346  /** Check if there is any PDP context active. If cid is given, then check is done only for that cid.
347  *
348  * @param number_of_active_contexts If given then in return contains the number of all active contexts
349  * @param cid If given then check if the context with this cid is active
350  *
351  * @return true if any (or the given cid) context is active, false otherwise or in case of error
352  */
353  virtual bool is_active_context(int *number_of_active_contexts = NULL, int cid = -1) = 0;
354 
355  /** Gets the latest received registration parameters from the network:
356  * type, status, access technology, cell_id, lac, active_time, periodic_tau.
357  *
358  * @param reg_params see registration_params_t
359  * @return NSAPI_ERROR_OK on success
360  * NSAPI_ERROR_DEVICE_ERROR on failure
361  */
363 
364  /** Gets the current network registration parameters from the network with type:
365  * status, access technology, cell_id, lac, active_time, periodic_tau.
366  *
367  * @param type see RegistrationType values
368  * @param reg_params see registration_params_t
369  * @return NSAPI_ERROR_OK on success
370  * NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
371  * NSAPI_ERROR_DEVICE_ERROR on failure
372  */
373  virtual nsapi_error_t get_registration_params(RegistrationType type, registration_params_t &reg_params) = 0;
374 
375  /** Set discontinuous reception time on cellular device.
376  *
377  * @remark See 3GPP TS 27.007 eDRX for details.
378  *
379  * @param mode disable or enable the use of eDRX
380  * @param act_type type of access technology
381  * @param edrx_value requested edxr value. Extended DRX parameters information element.
382  *
383  * @return NSAPI_ERROR_OK on success
384  * NSAPI_ERROR_DEVICE_ERROR on failure
385  */
387  EDRXGSM_EC_GSM_IoT_mode = 1,
388  EDRXGSM_A_Gb_mode,
389  EDRXUTRAN_Iu_mode,
390  EDRXEUTRAN_WB_S1_mode,
391  EDRXEUTRAN_NB_S1_mode
392  };
393  virtual nsapi_error_t set_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0;
394 
395  /** Sets the packet domain network reporting. Useful for getting events when detached from the
396  * network. When detach event arrives it is propagated as NSAPI_STATUS_DISCONNECTED to callback set
397  * with attach(...).
398  *
399  * @param on true for enabling event reporting, false for disabling
400  * @return NSAPI_ERROR_OK on success
401  * NSAPI_ERROR_UNSUPPORTED is command is not supported by the modem
402  * NSAPI_ERROR_DEVICE_ERROR on failure
403  */
405  {
407  }
408 };
409 
410 /**
411  * @}
412  */
413 
414 } // namespace mbed
415 
416 #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.
OperatorNameFormat
Operator name format.
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:53
Definition: ATHandler.h:46
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.