CellularNetwork.h

00001 /*
00002  * Copyright (c) 2017, Arm Limited and affiliates.
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef CELLULAR_NETWORK_H_
00019 #define CELLULAR_NETWORK_H_
00020 
00021 #include "NetworkInterface.h"
00022 #include "CellularList.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  *  Class CellularNetwork
00035  *
00036  *  An abstract interface for connecting to a network and getting information from it.
00037  */
00038 class CellularNetwork : public NetworkInterface {
00039 protected:
00040     // friend of CellularDevice so that it's the only way to close/delete this class.
00041     friend class CellularDevice;
00042 
00043     /**
00044      * virtual Destructor
00045      */
00046     virtual ~CellularNetwork() {}
00047 
00048 public:
00049     /* Definition for Supported CIoT EPS optimizations type. */
00050     enum Supported_UE_Opt {
00051         SUPPORTED_UE_OPT_NO_SUPPORT = 0, /* No support. */
00052         SUPPORTED_UE_OPT_CONTROL_PLANE,  /* Support for control plane CIoT EPS optimization. */
00053         SUPPORTED_UE_OPT_USER_PLANE,     /* Support for user plane CIoT EPS optimization. */
00054         SUPPORTED_UE_OPT_BOTH,           /* Support for both control plane CIoT EPS optimization and user plane CIoT EPS
00055                                             optimization. */
00056         SUPPORTED_UE_OPT_MAX
00057     };
00058 
00059     /* Definition for Preferred CIoT EPS optimizations type. */
00060     enum Preferred_UE_Opt {
00061         PREFERRED_UE_OPT_NO_PREFERENCE = 0, /* No preference. */
00062         PREFERRED_UE_OPT_CONTROL_PLANE,     /* Preference for control plane CIoT EPS optimization. */
00063         PREFERRED_UE_OPT_USER_PLANE,        /* Preference for user plane CIoT EPS optimization. */
00064         PREFERRED_UE_OPT_MAX
00065     };
00066 
00067     /* Network registration status */
00068     enum RegistrationStatus {
00069         NotRegistered = 0,
00070         RegisteredHomeNetwork,
00071         SearchingNetwork,
00072         RegistrationDenied,
00073         Unknown,
00074         RegisteredRoaming,
00075         RegisteredSMSOnlyHome,
00076         RegisteredSMSOnlyRoaming,
00077         AttachedEmergencyOnly,
00078         RegisteredCSFBNotPreferredHome,
00079         RegisteredCSFBNotPreferredRoaming = 10
00080     };
00081 
00082     /* Network registration type */
00083     enum RegistrationType {
00084         C_EREG = 0,
00085         C_GREG,
00086         C_REG,
00087         C_MAX
00088     };
00089 
00090     /* device attach status to network */
00091     enum AttachStatus {
00092         Detached = 0,
00093         Attached,
00094     };
00095 
00096     /*  whether the additional exception reports are allowed to be sent when the maximum uplink rate is reached */
00097     enum RateControlExceptionReports {
00098         NotAllowedToBeSent = 0,
00099         AllowedToBeSent
00100     };
00101 
00102     /* specifies the time unit to be used for the maximum uplink rate */
00103     enum RateControlUplinkTimeUnit {
00104         Unrestricted = 0,
00105         Minute,
00106         Hour,
00107         Day,
00108         Week
00109     };
00110 
00111     /* authentication type when activating or modifying the pdp context */
00112     enum AuthenticationType {
00113         NOAUTH = 0,
00114         PAP,
00115         CHAP
00116     };
00117 
00118     enum RadioAccessTechnology {
00119         RAT_GSM,
00120         RAT_GSM_COMPACT,
00121         RAT_UTRAN,
00122         RAT_EGPRS,
00123         RAT_HSDPA,
00124         RAT_HSUPA,
00125         RAT_HSDPA_HSUPA,
00126         RAT_E_UTRAN,
00127         RAT_CATM1,
00128         RAT_NB1,
00129         RAT_UNKNOWN
00130     };
00131 
00132     // 3GPP TS 27.007 - 7.3 PLMN selection +COPS
00133     struct operator_t {
00134         enum Status {
00135             Unknown,
00136             Available,
00137             Current,
00138             Forbiden
00139         };
00140 
00141         Status op_status;
00142         char op_long[MAX_OPERATOR_NAME_LONG + 1];
00143         char op_short[MAX_OPERATOR_NAME_SHORT + 1];
00144         char op_num[MAX_OPERATOR_NAME_SHORT + 1];
00145         RadioAccessTechnology op_rat;
00146         operator_t *next;
00147 
00148         operator_t()
00149         {
00150             op_status = Unknown;
00151             op_rat = RAT_UNKNOWN;
00152             next = NULL;
00153             op_long[0] = NULL;
00154             op_short[0] = NULL;
00155             op_num[0] = NULL;
00156         }
00157     };
00158 
00159     typedef CellularList<operator_t> operList_t;
00160 
00161     /* PDP Context information */
00162     struct pdpcontext_params_t {
00163         char apn[MAX_ACCESSPOINT_NAME_LENGTH + 1];
00164         char local_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00165         char local_subnet_mask[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00166         char gateway_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00167         char dns_primary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00168         char dns_secondary_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00169         char p_cscf_prim_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00170         char p_cscf_sec_addr[MAX_IPV6_ADDR_IN_IPV4LIKE_DOTTED_FORMAT + 1];
00171         int cid;
00172         int bearer_id;
00173         int im_signalling_flag;
00174         int lipa_indication;
00175         int ipv4_mtu;
00176         int wlan_offload;
00177         int local_addr_ind;
00178         int non_ip_mtu;
00179         int serving_plmn_rate_control_value;
00180         pdpcontext_params_t *next;
00181 
00182         pdpcontext_params_t()
00183         {
00184             apn[0] = '\0';
00185             local_addr[0] = '\0';
00186             local_subnet_mask[0] = '\0';
00187             gateway_addr[0] = '\0';
00188             dns_primary_addr[0] = '\0';
00189             dns_secondary_addr[0] = '\0';
00190             p_cscf_prim_addr[0] = '\0';
00191             p_cscf_sec_addr[0] = '\0';
00192             cid = -1;
00193             bearer_id = -1;
00194             im_signalling_flag = -1;
00195             lipa_indication = -1;
00196             ipv4_mtu = -1;
00197             wlan_offload = -1;
00198             local_addr_ind = -1;
00199             non_ip_mtu = -1;
00200             serving_plmn_rate_control_value = -1;
00201             next = NULL;
00202         }
00203     };
00204     typedef CellularList<pdpcontext_params_t> pdpContextList_t;
00205 
00206     struct operator_names_t {
00207         char numeric[MAX_OPERATOR_NAME_SHORT + 1];
00208         char alpha[MAX_OPERATOR_NAME_LONG + 1];
00209         operator_names_t *next;
00210         operator_names_t()
00211         {
00212             numeric[0] = '\0';
00213             alpha[0] = '\0';
00214             next = NULL;
00215         }
00216     };
00217     typedef CellularList<operator_names_t> operator_names_list;
00218 
00219     /* Network registering mode */
00220     enum NWRegisteringMode {
00221         NWModeAutomatic = 0,    // automatic registering
00222         NWModeManual,           // manual registering with plmn
00223         NWModeDeRegister,       // deregister from network
00224         NWModeSetOnly,          // set only <format> (for read command +COPS?), do not attempt registration/deregistration
00225         NWModeManualAutomatic   // if manual fails, fallback to automatic
00226     };
00227 
00228 
00229     /** Does all the needed initializations that can fail
00230      *
00231      *  @remark         must be called immediately after constructor.
00232      *  @return         NSAPI_ERROR_OK on success
00233      *                  NSAPI_ERROR_NO_MEMORY on memory failure
00234      */
00235     virtual nsapi_error_t init() = 0;
00236 
00237     /** Request registering to network.
00238      *
00239      *  @param plmn     format is in numeric format or 0 for automatic network registration
00240      *  @return         NSAPI_ERROR_OK on success
00241      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00242      */
00243     virtual nsapi_error_t set_registration(const char *plmn = 0) = 0;
00244 
00245     /** Get the current network registering mode
00246      *
00247      *  @param mode     on successful return contains the current network registering mode
00248      *  @return         NSAPI_ERROR_OK on success
00249      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00250      */
00251     virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode &mode) = 0;
00252 
00253     /** Activate/deactivate listening of network events for the given RegistrationType.
00254      *  This should be called after network class is created and ready to receive AT commands.
00255      *  After successful call network class starts to get information about network changes like
00256      *  registration statue, access technology, cell id...
00257      *
00258      *  @param type     RegistrationType to set urc on/off
00259      *  @param on       Controls are urc active or not
00260      *  @return         NSAPI_ERROR_OK on success
00261      *                  NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
00262      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00263      */
00264     virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0;
00265 
00266     /** Gets the network registration status.
00267      *
00268      *  @param type     see RegistrationType values
00269      *  @param status   see RegistrationStatus values
00270      *  @return         NSAPI_ERROR_OK on success
00271      *                  NSAPI_ERROR_UNSUPPORTED if the modem does not support RegistrationType
00272      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00273      */
00274     virtual nsapi_error_t get_registration_status(RegistrationType type, RegistrationStatus &status) = 0;
00275 
00276     /** Set the cellular network APN and credentials
00277      *
00278      *  @param apn      Optional name of the network to connect to
00279      *  @param username Optional username for the APN
00280      *  @param password Optional password fot the APN
00281      *  @return         NSAPI_ERROR_OK on success
00282      *                  NSAPI_ERROR_NO_MEMORY on memory failure
00283      */
00284     virtual nsapi_error_t set_credentials(const char *apn,
00285                                           const char *username = 0, const char *password = 0) = 0;
00286 
00287     /** Set the cellular network APN and credentials
00288      *
00289      *  @param apn      Name of the network to connect to
00290      *  @param type     Authentication type to use
00291      *  @param username Optional username for the APN
00292      *  @param password Optional password fot the APN
00293      *  @return         NSAPI_ERROR_OK on success
00294      *                  NSAPI_ERROR_NO_MEMORY on memory failure
00295      */
00296     virtual nsapi_error_t set_credentials(const char *apn, AuthenticationType type,
00297                                           const char *username = 0, const char *password = 0) = 0;
00298 
00299     /** Request attach to network.
00300      *
00301      *  @deprecated Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead.
00302      *  @param timeout  milliseconds to wait for attach response
00303      *  @return         NSAPI_ERROR_OK on success
00304      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00305      */
00306     MBED_DEPRECATED_SINCE("mbed-os-5.9", "Parameter timeout will be deprecated. Use mbed-os/features/cellular/framework/API/CellularDevice.h set_timeout instead.")
00307     virtual nsapi_error_t set_attach(int timeout = 10 * 1000) = 0;
00308 
00309     /** Request attach status from network.
00310      *
00311      *  @param status   see AttachStatus values
00312      *  @return         NSAPI_ERROR_OK on success
00313      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00314      */
00315     virtual nsapi_error_t get_attach(AttachStatus &status) = 0;
00316 
00317     /** Request detach from a network.
00318      *
00319      *  @return         NSAPI_ERROR_OK on success
00320      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00321      */
00322     virtual nsapi_error_t detach() = 0;
00323 
00324     /** Get APN rate control.
00325      *
00326      *  @remark optional params are not updated if not received from network, so use good defaults
00327      *  @param reports       Additional exception reports at maximum rate reached are allowed to be sent [optional]
00328      *  @param time_unit     Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
00329      *  @param uplink_rate   Maximum number of messages per timeUnit [optional]
00330      *  @return              NSAPI_ERROR_OK on success
00331      *                       NSAPI_ERROR_DEVICE_ERROR on case of failure
00332      */
00333     virtual nsapi_error_t get_rate_control(CellularNetwork::RateControlExceptionReports &reports,
00334                                            CellularNetwork::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
00335 
00336     /** Get backoff timer value
00337      *
00338      *  @param backoff_timer Backoff timer value associated with PDP APN in seconds
00339      *  @return              NSAPI_ERROR_OK on success
00340      *                       NSAPI_ERROR_PARAMETER if no access point is set or found when activating context
00341      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00342      */
00343     virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
00344 
00345     /** Sets radio access technology.
00346      *
00347      *  @param rat           Radio access technology
00348      *  @return              NSAPI_ERROR_OK on success
00349      *                       NSAPI_ERROR_UNSUPPORTED if the given rat is RAT_UNKNOWN or inheriting target class
00350      *                                               has not implemented method set_access_technology_impl(...)
00351      *                       OR return value of the inheriting target class set_access_technology_impl(...)
00352      */
00353     virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0;
00354 
00355     /** Get current radio access technology.
00356      *
00357      *  @param rat           Radio access technology
00358      *  @return              NSAPI_ERROR_OK
00359      */
00360     virtual nsapi_error_t get_access_technology(RadioAccessTechnology &rat) = 0;
00361 
00362     /** Scans for operators module can reach.
00363      *
00364      *  @param operators     Container of reachable operators and their access technologies
00365      *  @param ops_count     Number of found operators
00366      *  @return              NSAPI_ERROR_OK on success
00367      *                       NSAPI_ERROR_NO_MEMORY on memory failure
00368      *                       NSAPI_ERROR_DEVICE_ERROR on other failures
00369      */
00370     virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0;
00371 
00372     /** Set CIoT optimizations.
00373      *
00374      *  @param supported_opt Supported CIoT EPS optimizations.
00375      *  @param preferred_opt Preferred CIoT EPS optimizations.
00376      *  @return              NSAPI_ERROR_OK on success
00377      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00378      */
00379     virtual nsapi_error_t set_ciot_optimization_config(Supported_UE_Opt supported_opt,
00380                                                        Preferred_UE_Opt preferred_opt) = 0;
00381 
00382     /** Get CIoT optimizations.
00383      *
00384      *  @param supported_opt Supported CIoT EPS optimizations.
00385      *  @param preferred_opt Preferred CIoT EPS optimizations.
00386      *  @return              NSAPI_ERROR_OK on success
00387      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00388      */
00389     virtual nsapi_error_t get_ciot_optimization_config(Supported_UE_Opt &supported_opt,
00390                                                        Preferred_UE_Opt &preferred_opt) = 0;
00391 
00392     /** Start the interface. Attempts to connect to a cellular network.
00393      *
00394      *  @return              NSAPI_ERROR_OK on success
00395      *                       NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated)
00396      *                       NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found or cellular device does not support authentication
00397      *                       NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed
00398      *                       Also if PPP mode
00399      *                       NSAPI_ERROR_DEVICE_ERROR on failure and check more error from nsapi_ppp_connect(...)
00400      */
00401     virtual nsapi_error_t connect() = 0;
00402 
00403     /** Start the interface. Attempts to connect to a cellular network.
00404      *
00405      *  @param apn      Optional name of the network to connect to
00406      *  @param username Optional username for your APN
00407      *  @param password Optional password for your APN
00408      *  @return              NSAPI_ERROR_OK on success
00409      *                       NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated)
00410      *                       NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found
00411      *                       NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed
00412      *                       NSAPI_ERROR_NO_MEMORY on memory failure
00413      *                       Also if PPP mode
00414      *                       NSAPI_ERROR_DEVICE_ERROR on failure and check more error from nsapi_ppp_connect(...)
00415      */
00416     virtual nsapi_error_t connect(const char *apn,
00417                                   const char *username = 0, const char *password = 0) = 0;
00418 
00419     /** Finds the correct PDP context and activates it. If correct PDP context is not found, one is created.
00420      *  Given APN (or not given) and stack type (IPv4/IPv6/dual) are influencing when finding the PDP context.
00421      *
00422      *  @return              NSAPI_ERROR_OK on success
00423      *                       NSAPI_ERROR_NO_CONNECTION if fails to find suitable context to activate or activation failed (if not already activated)
00424      *                       NSAPI_ERROR_UNSUPPORTED if NetworkStack was not found
00425      *                       NSAPI_ERROR_AUTH_FAILURE if password and username were provided and authentication to network failed
00426      */
00427     virtual nsapi_error_t activate_context() = 0;
00428 
00429     /**
00430      * Set the pdn type to be used
00431      *
00432      * @param stack_type the stack type to be used.
00433      *
00434      * @return              NSAPI_ERROR_OK on success
00435      *                      NSAPI_ERROR_PARAMETER if modem does not support the given stack_type
00436      */
00437     virtual nsapi_error_t set_stack_type(nsapi_ip_stack_t stack_type) = 0;
00438 
00439     /**
00440      * Get the pdn type in use
00441      *
00442      * @return stack type
00443      */
00444     virtual nsapi_ip_stack_t get_stack_type() = 0;
00445 
00446     /** Get the relevant information for an active non secondary PDP context.
00447      *
00448      *  @remark optional params are not updated if not received from network.
00449      *  @param params_list   reference to linked list, which is filled on successful call
00450      *  @return              NSAPI_ERROR_OK on success
00451      *                       NSAPI_ERROR_NO_MEMORY on memory failure
00452      *                       NSAPI_ERROR_DEVICE_ERROR on other failures
00453      */
00454     virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t &params_list) = 0;
00455 
00456     /** Get extended signal quality parameters.
00457      *
00458      *  @param rxlev         signal strength level
00459      *  @param ber           bit error rate
00460      *  @param rscp          signal code power
00461      *  @param ecno          ratio of the received energy per PN chip to the total received power spectral density
00462      *  @param rsrq          signal received quality
00463      *  @param rsrp          signal received power
00464      *  @return              NSAPI_ERROR_OK on success
00465      *                       NSAPI_ERROR_DEVICE_ERROR on other failures
00466      */
00467     virtual nsapi_error_t get_extended_signal_quality(int &rxlev, int &ber, int &rscp, int &ecno, int &rsrq, int &rsrp) = 0;
00468 
00469     /** Get signal quality parameters.
00470      *
00471      *  @param rssi          signal strength level
00472      *  @param ber           bit error rate
00473      *  @return              NSAPI_ERROR_OK on success
00474      *                       NSAPI_ERROR_DEVICE_ERROR on other failures
00475      */
00476     virtual nsapi_error_t get_signal_quality(int &rssi, int &ber) = 0;
00477 
00478     /** Get cell id.
00479      *
00480      *  @param cell_id  cell ID
00481      *  @return         NSAPI_ERROR_OK
00482      */
00483     virtual nsapi_error_t get_cell_id(int &cell_id) = 0;
00484 
00485     /** Get the last 3GPP error code
00486      *  @return see 3GPP TS 27.007 error codes
00487      */
00488     virtual int get_3gpp_error() = 0;
00489 
00490     /** Get the operator parameters.
00491      *
00492      *  @param format           format of the operator field
00493      *  @param operator_params  applicable operator param fields filled
00494      *  @return                 NSAPI_ERROR_OK on success
00495      *                          NSAPI_ERROR_DEVICE_ERROR on case of other failures
00496      */
00497     virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0;
00498 
00499     /** Register callback for status reporting
00500      *
00501      *  The specified status callback function will be called on status changes
00502      *  on the network. The parameters on the callback are the event type and
00503      *  event-type dependent reason parameter.
00504      *
00505      *  @param status_cb The callback for status changes
00506      */
00507     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
00508 
00509     /** Get the connection status
00510      *
00511      *  @return         The connection status according to ConnectionStatusType
00512      */
00513     virtual nsapi_connection_status_t get_connection_status() const = 0;
00514 
00515     /** Set blocking status of connect() which by default should be blocking
00516      *
00517      *  @param blocking true if connect is blocking
00518      *  @return         NSAPI_ERROR_OK
00519      *                  if PPP mode check errors from nsapi_ppp_set_blocking(...)
00520      */
00521     virtual nsapi_error_t set_blocking(bool blocking) = 0;
00522 
00523     /** Read operator names
00524      *
00525      *  @param op_names      on successful return contains linked list of operator names.
00526      *  @return              NSAPI_ERROR_OK on success
00527      *                       NSAPI_ERROR_NO_MEMORY on memory failure
00528      *                       NSAPI_ERROR_DEVICE_ERROR on other failures
00529      */
00530     virtual nsapi_error_t get_operator_names(operator_names_list &op_names) = 0;
00531 };
00532 
00533 } // namespace mbed
00534 
00535 #endif // CELLULAR_NETWORK_H_