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