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 &reg_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 &reg_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_