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     /* Network registering mode */
00203     enum NWRegisteringMode {
00204         NWModeAutomatic = 0,    // automatic registering
00205         NWModeManual,           // manual registering with plmn
00206         NWModeDeRegister,       // deregister from network
00207         NWModeSetOnly,          // set only <format> (for read command +COPS?), do not attempt registration/deregistration
00208         NWModeManualAutomatic   // if manual fails, fallback to automatic
00209     };
00210 
00211 
00212     /** Does all the needed initializations that can fail
00213      *
00214      *  @remark         must be called immediately after constructor.
00215      *  @return         zero on success
00216      */
00217     virtual nsapi_error_t init() = 0;
00218 
00219     /** Request registering to network.
00220      *
00221      *  @param plmn     format is in numeric format or 0 for automatic network registration
00222      *  @return         zero on success
00223      */
00224     virtual nsapi_error_t set_registration(const char *plmn = 0) = 0;
00225 
00226     /** Get the current network registering mode
00227      *
00228      *  @param mode on successful return contains the current network registering mode
00229      *  @return     zero on success
00230      */
00231     virtual nsapi_error_t get_network_registering_mode(NWRegisteringMode& mode) = 0;
00232 
00233     /** Activate/deactivate listening of network events for the given RegistrationType.
00234      *  This should be called after network class is created and ready to receive AT commands.
00235      *  After successful call network class starts to get information about network changes like
00236      *  registration statue, access technology, cell id...
00237      *
00238      *  @param type RegistrationType to set urc on/off
00239      *  @param on   Controls are urc' active or not
00240      *  @return     zero on success
00241      */
00242     virtual nsapi_error_t set_registration_urc(RegistrationType type, bool on) = 0;
00243 
00244     /** Gets the network registration status.
00245      *
00246      * @param type      see RegistrationType values
00247      * @param status    see RegistrationStatus values
00248      * @return zero on success
00249      */
00250     virtual nsapi_error_t get_registration_status(RegistrationType type, RegistrationStatus &status) = 0;
00251 
00252     /** Set the cellular network APN and credentials
00253      *
00254      *  @param apn      Optional name of the network to connect to
00255      *  @param username Optional username for the APN
00256      *  @param password Optional password fot the APN
00257      *  @return         0 on success, negative error code on failure
00258      */
00259     virtual nsapi_error_t set_credentials(const char *apn,
00260                                           const char *username = 0, const char *password = 0) = 0;
00261 
00262     /** Set the cellular network APN and credentials
00263      *
00264      *  @param apn      Name of the network to connect to
00265      *  @param type     Authentication type to use
00266      *  @param username Optional username for the APN
00267      *  @param password Optional password fot the APN
00268      *  @return         0 on success, negative error code on failure
00269      */
00270     virtual nsapi_error_t set_credentials(const char *apn, AuthenticationType type,
00271                 const char *username = 0, const char *password = 0) = 0;
00272 
00273     /** Request attach to network.
00274      *
00275      *  @param timeout milliseconds to wait for attach response
00276      *  @return        zero on success
00277      */
00278     virtual nsapi_error_t set_attach(int timeout = 10*1000) = 0;
00279 
00280     /** Request attach status from network.
00281      *
00282      *  @param status see AttachStatus values
00283      *  @return       zero on success
00284      */
00285     virtual nsapi_error_t get_attach(AttachStatus &status) = 0;
00286 
00287     /** Get APN rate control.
00288      *
00289      *  @remark optional params are not updated if not received from network, so use good defaults
00290      *  @param reports       Additional exception reports at maximum rate reached are allowed to be sent [optional]
00291      *  @param time_unit     Uplink time unit with values 0=unrestricted, 1=minute, 2=hour, 3=day, 4=week [optional]
00292      *  @param uplink_rate   Maximum number of messages per timeUnit [optional]
00293      *  @return              zero on success
00294      */
00295     virtual nsapi_error_t get_rate_control(CellularNetwork::RateControlExceptionReports &reports,
00296         CellularNetwork::RateControlUplinkTimeUnit &time_unit, int &uplink_rate) = 0;
00297 
00298     /** Get backoff timer value
00299      *
00300      *  @param backoff_timer Backoff timer value associated with PDP APN in seconds
00301      *  @return              zero on success
00302      */
00303     virtual nsapi_error_t get_apn_backoff_timer(int &backoff_timer) = 0;
00304 
00305     /** Sets radio access technology.
00306      *
00307      *  @param rat  Radio access technology
00308      *  @return     zero on success
00309      */
00310     virtual nsapi_error_t set_access_technology(RadioAccessTechnology rat) = 0;
00311 
00312     /** Get current radio access technology.
00313      *
00314      *  @param rat  Radio access technology
00315      *  @return     zero on success
00316      */
00317     virtual nsapi_error_t get_access_technology(RadioAccessTechnology& rat) = 0;
00318 
00319     /** Scans for operators module can reach.
00320      *
00321      *  @param operators Container of reachable operators and their access technologies
00322      *  @param ops_count Number of found operators
00323      *  @return          zero on success
00324      */
00325     virtual nsapi_error_t scan_plmn(operList_t &operators, int &ops_count) = 0;
00326 
00327     /** Set CIoT optimizations.
00328      *
00329      *  @param supported_opt Supported CIoT EPS optimizations.
00330      *  @param preferred_opt Preferred CIoT EPS optimizations.
00331      *  @return zero on success
00332      */
00333     virtual nsapi_error_t set_ciot_optimization_config(Supported_UE_Opt supported_opt,
00334                                                        Preferred_UE_Opt preferred_opt) = 0;
00335 
00336     /** Get CIoT optimizations.
00337      *
00338      *  @param supported_opt Supported CIoT EPS optimizations.
00339      *  @param preferred_opt Preferred CIoT EPS optimizations.
00340      *  @return zero on success
00341      */
00342     virtual nsapi_error_t get_ciot_optimization_config(Supported_UE_Opt& supported_opt,
00343                                                        Preferred_UE_Opt& preferred_opt) = 0;
00344 
00345     /** Start the interface. Attempts to connect to a cellular network.
00346      *
00347      *  @return 0 on success, negative error code on failure
00348      */
00349     virtual nsapi_error_t connect() = 0;
00350 
00351     /** Start the interface. Attempts to connect to a cellular network.
00352      *
00353      *  @param apn      Optional name of the network to connect to
00354      *  @param username Optional username for your APN
00355      *  @param password Optional password for your APN
00356      *  @return         0 on success, negative error code on failure
00357      */
00358     virtual nsapi_error_t connect(const char *apn,
00359                                   const char *username = 0, const char *password = 0) = 0;
00360 
00361     /** Finds the correct PDP context and activates it. If correct PDP context is not found, one is created.
00362      *  Given APN (or not given) and stack type (IPv4/IPv6/dual) are influencing when finding the PDP context.
00363      *
00364      *  @return zero on success
00365      */
00366     virtual nsapi_error_t activate_context() = 0;
00367 
00368     /**
00369      * Set the pdn type to be used
00370      *
00371      * @param stack_type the stack type to be used.
00372      *
00373      * @return NSAPI_ERROR_OK on success
00374      */
00375     virtual nsapi_error_t set_stack_type(nsapi_ip_stack_t stack_type) = 0;
00376 
00377     /**
00378      * Get the pdn type in use
00379      *
00380      * @return stack type
00381      */
00382     virtual nsapi_ip_stack_t get_stack_type() = 0;
00383 
00384     /** Get the relevant information for an active non secondary PDP context.
00385      *
00386      *  @remark optional params are not updated if not received from network.
00387      *  @param params_list  reference to linked list which is filled on successful call
00388      *  @return             0 on success, negative error code on failure
00389      */
00390     virtual nsapi_error_t get_pdpcontext_params(pdpContextList_t& params_list) = 0;
00391 
00392     /** Get extended signal quality parameters.
00393      *
00394      *  @param rxlev signal strength level
00395      *  @param ber bit error rate
00396      *  @param rscp signal code power
00397      *  @param ecno ratio of the received energy per PN chip to the total received power spectral density
00398      *  @param rsrq signal received quality
00399      *  @param rsrp signal received power
00400      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00401      */
00402     virtual nsapi_error_t get_extended_signal_quality(int &rxlev, int &ber, int &rscp, int &ecno, int &rsrq, int &rsrp) = 0;
00403 
00404     /** Get signal quality parameters.
00405      *
00406      *  @param rssi signal strength level
00407      *  @param ber bit error rate
00408      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00409      */
00410     virtual nsapi_error_t get_signal_quality(int &rssi, int &ber) = 0;
00411 
00412     /** Get cell id.
00413      *
00414      *  @param cell_id cell id
00415      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00416      */
00417     virtual nsapi_error_t get_cell_id(int &cell_id) = 0;
00418 
00419     /** Get the last 3GPP error code
00420      *  @return see 3GPP TS 27.007 error codes
00421      */
00422     virtual int get_3gpp_error() = 0;
00423 
00424     /** Get the operator parameters.
00425      *
00426      *  @param format format of the operator field
00427      *  @param operator_params applicable operator param fields filled
00428      *  @return NSAPI_ERROR_OK on success, negative error code on failure
00429      */
00430     virtual nsapi_error_t get_operator_params(int &format, operator_t &operator_params) = 0;
00431 
00432     /** Register callback for status reporting
00433      *
00434      *  The specified status callback function will be called on status changes
00435      *  on the network. The parameters on the callback are the event type and
00436      *  event-type dependent reason parameter.
00437      *
00438      *  @param status_cb The callback for status changes
00439      */
00440     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
00441 
00442     /** Get the connection status
00443      *
00444      *  @return         The connection status according to ConnectionStatusType
00445      */
00446     virtual nsapi_connection_status_t get_connection_status() const = 0;
00447 
00448     /** Set blocking status of connect() which by default should be blocking
00449      *
00450      *  @param blocking true if connect is blocking
00451      *  @return         0 on success, negative error code on failure
00452      */
00453     virtual nsapi_error_t set_blocking(bool blocking) = 0;
00454 
00455 };
00456 
00457 } // namespace mbed
00458 
00459 #endif // CELLULAR_NETWORK_H_