Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: TYBLE16_simple_data_logger TYBLE16_MP3_Air
CellularNetwork.h
00001 /* Copyright (c) 2017,2018 Arm Limited and affiliates. 00002 * SPDX-License-Identifier: Apache-2.0 00003 * 00004 * Licensed under the Apache License, Version 2.0 (the "License"); 00005 * you may not use this file except in compliance with the License. 00006 * You may obtain a copy of the License at 00007 * 00008 * http://www.apache.org/licenses/LICENSE-2.0 00009 * 00010 * Unless required by applicable law or agreed to in writing, software 00011 * distributed under the License is distributed on an "AS IS" BASIS, 00012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00013 * See the License for the specific language governing permissions and 00014 * limitations under the License. 00015 */ 00016 00017 #ifndef CELLULAR_NETWORK_H_ 00018 #define CELLULAR_NETWORK_H_ 00019 00020 #include "CellularList.h" 00021 #include "Callback.h" 00022 #include "nsapi_types.h" 00023 00024 namespace mbed { 00025 00026 /* Maximum length of IPV6 address in ipv4-like dotted format. More info in 3gpp 27007.*/ 00027 const int MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT = 63; 00028 /* Maximum length of access point name */ 00029 const int MAX_ACCESSPOINT_NAME_LENGTH = 100; 00030 const int MAX_OPERATOR_NAME_LONG = 16; 00031 const int MAX_OPERATOR_NAME_SHORT = 8; 00032 00033 /** 00034 * @addtogroup cellular 00035 * @{ 00036 */ 00037 00038 /// An abstract interface for connecting to a network and getting information from it. 00039 class CellularNetwork { 00040 protected: 00041 // friend of CellularDevice so that it's the only way to close/delete this class. 00042 friend class CellularDevice; 00043 00044 virtual ~CellularNetwork() {} 00045 00046 public: 00047 /* Definition for Supported CIoT EPS optimizations type. */ 00048 enum CIoT_Supported_Opt { 00049 CIOT_OPT_NO_SUPPORT = 0, /* No support. */ 00050 CIOT_OPT_CONTROL_PLANE, /* Support for control plane CIoT EPS optimization. */ 00051 CIOT_OPT_USER_PLANE, /* Support for user plane CIoT EPS optimization. */ 00052 CIOT_OPT_BOTH, /* Support for both control plane CIoT EPS optimization and user plane CIoT EPS 00053 optimization. */ 00054 CIOT_OPT_MAX 00055 }; 00056 00057 /* Definition for Preferred CIoT EPS optimizations type. */ 00058 enum CIoT_Preferred_UE_Opt { 00059 PREFERRED_UE_OPT_NO_PREFERENCE = 0, /* No preference. */ 00060 PREFERRED_UE_OPT_CONTROL_PLANE, /* Preference for control plane CIoT EPS optimization. */ 00061 PREFERRED_UE_OPT_USER_PLANE, /* Preference for user plane CIoT EPS optimization. */ 00062 PREFERRED_UE_OPT_MAX 00063 }; 00064 00065 /* Network registration status */ 00066 enum RegistrationStatus { 00067 StatusNotAvailable = -1, 00068 NotRegistered = 0, 00069 RegisteredHomeNetwork, 00070 SearchingNetwork, 00071 RegistrationDenied, 00072 Unknown, 00073 RegisteredRoaming, 00074 RegisteredSMSOnlyHome, 00075 RegisteredSMSOnlyRoaming, 00076 AttachedEmergencyOnly, 00077 RegisteredCSFBNotPreferredHome, 00078 RegisteredCSFBNotPreferredRoaming, 00079 AlreadyRegistered = 11, // our definition when modem says that we are not registered but we have active PDP Context 00080 RegistrationStatusMax 00081 }; 00082 00083 /* Network registration type */ 00084 enum RegistrationType { 00085 C_EREG = 0, 00086 C_GREG, 00087 C_REG, 00088 C_MAX 00089 }; 00090 00091 /* device attach status to network */ 00092 enum AttachStatus { 00093 Detached = 0, 00094 Attached, 00095 }; 00096 00097 enum RadioAccessTechnology { 00098 RAT_GSM, 00099 RAT_GSM_COMPACT, 00100 RAT_UTRAN, 00101 RAT_EGPRS, 00102 RAT_HSDPA, 00103 RAT_HSUPA, 00104 RAT_HSDPA_HSUPA, 00105 RAT_E_UTRAN, 00106 RAT_CATM1, 00107 RAT_NB1, 00108 RAT_UNKNOWN, 00109 RAT_MAX = 11 // to reserve string array 00110 }; 00111 00112 /// 3GPP TS 27.007 - 7.3 PLMN selection +COPS 00113 struct operator_t { 00114 enum Status { 00115 Unknown, 00116 Available, 00117 Current, 00118 Forbiden 00119 }; 00120 00121 Status op_status; 00122 char op_long[MAX_OPERATOR_NAME_LONG + 1]; 00123 char op_short[MAX_OPERATOR_NAME_SHORT + 1]; 00124 char op_num[MAX_OPERATOR_NAME_SHORT + 1]; 00125 RadioAccessTechnology op_rat; 00126 operator_t *next; 00127 00128 operator_t() 00129 { 00130 op_status = Unknown; 00131 op_rat = RAT_UNKNOWN; 00132 next = NULL; 00133 op_long[0] = '\0'; 00134 op_short[0] = '\0'; 00135 op_num[0] = '\0'; 00136 } 00137 }; 00138 00139 typedef CellularList<operator_t> operList_t; 00140 00141 /// Cellular operator names in numeric and alpha format 00142 struct operator_names_t { 00143 char numeric[MAX_OPERATOR_NAME_SHORT + 1]; 00144 char alpha[MAX_OPERATOR_NAME_LONG + 1]; 00145 operator_names_t *next; 00146 operator_names_t() 00147 { 00148 numeric[0] = '\0'; 00149 alpha[0] = '\0'; 00150 next = NULL; 00151 } 00152 }; 00153 typedef CellularList<operator_names_t> operator_names_list; 00154 00155 /// Network registering mode 00156 enum NWRegisteringMode { 00157 NWModeAutomatic = 0, // automatic registering 00158 NWModeManual, // manual registering with plmn 00159 NWModeDeRegister, // deregister from network 00160 NWModeSetOnly, // set only <format> (for read command +COPS?), do not attempt registration/deregistration 00161 NWModeManualAutomatic // if manual fails, fallback to automatic 00162 }; 00163 00164 /// Network registration information 00165 struct registration_params_t { 00166 RegistrationType _type; 00167 RegistrationStatus _status; 00168 RadioAccessTechnology _act; 00169 int _cell_id; 00170 int _lac; 00171 int _active_time; 00172 int _periodic_tau; 00173 00174 registration_params_t() 00175 { 00176 _type = C_MAX; 00177 _status = StatusNotAvailable; 00178 _act = RAT_UNKNOWN; 00179 _cell_id = -1; 00180 _lac = -1; 00181 _active_time = -1; 00182 _periodic_tau = -1; 00183 } 00184 }; 00185 00186 /** Request registering to network. 00187 * 00188 * @param plmn format is in numeric format or 0 for automatic network registration 00189 * @return NSAPI_ERROR_OK on success 00190 * NSAPI_ERROR_DEVICE_ERROR on failure 00191 */ 00192 virtual nsapi_error_t set_registration(const char *plmn = 0) = 0; 00193 00194 /** Get the current network registering mode 00195 * 00196 * @param mode on successful return contains the current network registering mode 00197 * @return NSAPI_ERROR_OK on success 00198 * NSAPI_ERROR_DEVICE_ERROR on failure 00199 */ 00200 virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode &mode) = 0; 00201 00202 /** Activate/deactivate listening of network events for the given RegistrationType. 00203 * This should be called after network class is created and ready to receive AT commands. 00204 * After successful call network class starts to get information about network changes like 00205 * registration statue, access technology, cell id... 00206 * 00207 * @param type RegistrationType to set urc on/off 00208 * @param on Controls are urc active or not 00209 * @return NSAPI_ERROR_OK on success 00210 * NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType 00211 * NSAPI_ERROR_DEVICE_ERROR on failure 00212 */ 00213 virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0; 00214 00215 00216 /** Request attach to network. 00217 * 00218 * @return NSAPI_ERROR_OK on success 00219 * NSAPI_ERROR_DEVICE_ERROR on failure 00220 */ 00221 virtual nsapi_error_t set_attach() = 0; 00222 00223 /** Request attach status from network. 00224 * 00225 * @param status see AttachStatus values 00226 * @return NSAPI_ERROR_OK on success 00227 * NSAPI_ERROR_DEVICE_ERROR on failure 00228 */ 00229 virtual nsapi_error_t get_attach(AttachStatus &status) = 0; 00230 00231 /** Request detach and deregister from a network. 00232 * 00233 * @return NSAPI_ERROR_OK on success 00234 * NSAPI_ERROR_DEVICE_ERROR on failure 00235 */ 00236 virtual nsapi_error_t detach() = 0; 00237 00238 /** Sets radio access technology. 00239 * 00240 * @param rat Radio access technology 00241 * @return NSAPI_ERROR_OK on success 00242 * NSAPI_ERROR_UNSUPPORTED if the given rat is RAT_UNKNOWN or inheriting target class 00243 * has not implemented method set_access_technology_impl(...) 00244 * OR return value of the inheriting target class set_access_technology_impl(...) 00245 */ 00246 virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0; 00247 00248 /** Scans for operators module can reach. 00249 * 00250 * @param operators Container of reachable operators and their access technologies 00251 * @param ops_count Number of found operators 00252 * @return NSAPI_ERROR_OK on success 00253 * NSAPI_ERROR_NO_MEMORY on memory failure 00254 * NSAPI_ERROR_DEVICE_ERROR on other failures 00255 */ 00256 virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0; 00257 00258 /** Set CIoT optimizations. 00259 * 00260 * @param supported_opt Supported CIoT EPS optimizations 00261 * (the HW support can be checked with get_ciot_ue_optimization_config). 00262 * @param preferred_opt Preferred CIoT EPS optimizations. 00263 * @param network_support_cb This callback will be called when CIoT network optimization support is known 00264 * @return NSAPI_ERROR_OK on success 00265 * NSAPI_ERROR_DEVICE_ERROR on failure 00266 */ 00267 virtual nsapi_error_t set_ciot_optimization_config(CIoT_Supported_Opt supported_opt, 00268 CIoT_Preferred_UE_Opt preferred_opt, 00269 Callback<void(CIoT_Supported_Opt)> network_support_cb) = 0; 00270 00271 /** Get UE CIoT optimizations. 00272 * 00273 * @param supported_opt Supported CIoT EPS optimizations. 00274 * @param preferred_opt Preferred CIoT EPS optimizations. 00275 * @return NSAPI_ERROR_OK on success 00276 * NSAPI_ERROR_DEVICE_ERROR on failure 00277 */ 00278 virtual nsapi_error_t get_ciot_ue_optimization_config(CIoT_Supported_Opt &supported_opt, 00279 CIoT_Preferred_UE_Opt &preferred_opt) = 0; 00280 00281 /** Get Network CIoT optimizations. 00282 * 00283 * @param supported_network_opt Supported CIoT EPS optimizations. CIOT_OPT_MAX will be returned, 00284 * if the support is not known 00285 * @return NSAPI_ERROR_OK on success 00286 * NSAPI_ERROR_DEVICE_ERROR on failure 00287 */ 00288 virtual nsapi_error_t get_ciot_network_optimization_config(CIoT_Supported_Opt &supported_network_opt) = 0; 00289 00290 /** Get signal quality parameters. 00291 * 00292 * @param rssi signal strength level as defined in 3GPP TS 27.007, range -113..-51 dBm or SignalQualityUnknown 00293 * @param ber bit error rate as RXQUAL as defined in 3GPP TS 45.008, range 0..7 or SignalQualityUnknown 00294 * @return NSAPI_ERROR_OK on success 00295 * NSAPI_ERROR_DEVICE_ERROR on other failures 00296 */ 00297 enum SignalQuality { 00298 SignalQualityUnknown = 99 00299 }; 00300 virtual nsapi_error_t get_signal_quality(int &rssi, int *ber = NULL) = 0; 00301 00302 /** Get the last 3GPP error code 00303 * @return see 3GPP TS 27.007 error codes 00304 */ 00305 virtual int get_3gpp_error() = 0; 00306 00307 /** Get the operator parameters. 00308 * 00309 * @param format format of the operator field 00310 * @param operator_params applicable operator param fields filled 00311 * @return NSAPI_ERROR_OK on success 00312 * NSAPI_ERROR_DEVICE_ERROR on case of other failures 00313 */ 00314 virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0; 00315 00316 /** Register callback for status reporting 00317 * 00318 * The specified status callback function will be called on status changes 00319 * on the network. The parameters on the callback are the event type and 00320 * event-type dependent reason parameter. 00321 * 00322 * @remark Application should not call attach if using CellularContext class. Call instead CellularContext::attach 00323 * as CellularDevice is dependent of this attach if CellularContext/CellularDevice is used to get 00324 * device/sim ready, registered, attached, connected. 00325 * 00326 * @param status_cb The callback for status changes 00327 */ 00328 virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0; 00329 00330 /** Read operator names 00331 * 00332 * @param op_names on successful return contains linked list of operator names. 00333 * @return NSAPI_ERROR_OK on success 00334 * NSAPI_ERROR_NO_MEMORY on memory failure 00335 * NSAPI_ERROR_DEVICE_ERROR on other failures 00336 */ 00337 virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0; 00338 00339 /** Check if there is any PDP context active. If cid is given, then check is done only for that cid. 00340 * 00341 * @param number_of_active_contexts If given then in return contains the number of all active contexts 00342 * @param cid If given then check if the context with this cid is active 00343 * 00344 * @return true if any (or the given cid) context is active, false otherwise or in case of error 00345 */ 00346 virtual bool is_active_context(int *number_of_active_contexts = NULL, int cid = -1) = 0; 00347 00348 /** Gets the latest received registration parameters from the network: 00349 * type, status, access technology, cell_id, lac, active_time, periodic_tau. 00350 * 00351 * @param reg_params see registration_params_t 00352 * @return NSAPI_ERROR_OK on success 00353 * NSAPI_ERROR_DEVICE_ERROR on failure 00354 */ 00355 virtual nsapi_error_t get_registration_params(registration_params_t ®_params) = 0; 00356 00357 /** Gets the current network registration parameters from the network with type: 00358 * status, access technology, cell_id, lac, active_time, periodic_tau. 00359 * 00360 * @param type see RegistrationType values 00361 * @param reg_params see registration_params_t 00362 * @return NSAPI_ERROR_OK on success 00363 * NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType 00364 * NSAPI_ERROR_DEVICE_ERROR on failure 00365 */ 00366 virtual nsapi_error_t get_registration_params(RegistrationType type, registration_params_t ®_params) = 0; 00367 00368 /** Set discontinuous reception time on cellular device. 00369 * 00370 * @remark See 3GPP TS 27.007 eDRX for details. 00371 * 00372 * @param mode disable or enable the use of eDRX 00373 * @param act_type type of access technology 00374 * @param edrx_value requested edxr value. Extended DRX parameters information element. 00375 * 00376 * @return NSAPI_ERROR_OK on success 00377 * NSAPI_ERROR_DEVICE_ERROR on failure 00378 */ 00379 enum EDRXAccessTechnology { 00380 EDRXGSM_EC_GSM_IoT_mode = 1, 00381 EDRXGSM_A_Gb_mode, 00382 EDRXUTRAN_Iu_mode, 00383 EDRXEUTRAN_WB_S1_mode, 00384 EDRXEUTRAN_NB_S1_mode 00385 }; 00386 virtual nsapi_error_t set_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0; 00387 00388 /** Sets the packet domain network reporting. Useful for getting events when detached from the 00389 * network. When detach event arrives it is propagated as NSAPI_STATUS_DISCONNECTED to callback set 00390 * with attach(...). 00391 * 00392 * @param on true for enabling event reporting, false for disabling 00393 * @return NSAPI_ERROR_OK on success 00394 * NSAPI_ERROR_UNSUPPORTED is command is not supported by the modem 00395 * NSAPI_ERROR_DEVICE_ERROR on failure 00396 */ 00397 virtual nsapi_error_t set_packet_domain_event_reporting(bool on) 00398 { 00399 return NSAPI_ERROR_UNSUPPORTED ; 00400 } 00401 }; 00402 00403 /** 00404 * @} 00405 */ 00406 00407 } // namespace mbed 00408 00409 #endif // CELLULAR_NETWORK_H_
Generated on Tue Jul 12 2022 13:54:05 by
