CellularDevice.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_DEVICE_H_
00019 #define CELLULAR_DEVICE_H_
00020 
00021 #include "CellularStateMachine.h"
00022 #include "Callback.h"
00023 #include "ATHandler.h"
00024 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
00025 #include "UARTSerial.h"
00026 #endif // #if DEVICE_SERIAL
00027 
00028 /** @file CellularDevice.h
00029  * @brief Class CellularDevice
00030  *
00031  */
00032 namespace mbed {
00033 
00034 class CellularSMS;
00035 class CellularInformation;
00036 class CellularNetwork;
00037 class CellularContext;
00038 class FileHandle;
00039 
00040 const int MAX_PIN_SIZE = 8;
00041 const int MAX_PLMN_SIZE = 16;
00042 const int MAX_SIM_READY_WAITING_TIME = 30;
00043 
00044 /**
00045  * @addtogroup cellular
00046  * @{
00047  */
00048 
00049 /**
00050  *  Class CellularDevice
00051  *
00052  *  An abstract interface that defines opening and closing of cellular interfaces.
00053  *  You can delete or close opened interfaces only through this class.
00054  */
00055 class CellularDevice {
00056 public:
00057     /* enumeration for possible SIM states */
00058     enum SimState {
00059         SimStateReady = 0,
00060         SimStatePinNeeded,
00061         SimStatePukNeeded,
00062         SimStateUnknown
00063     };
00064 
00065     /** Returns singleton instance of CellularDevice, if Mbed target board has a supported
00066      *  onboard modem, or provide-default is defined for a cellular driver in JSON configuration
00067      *  files. Otherwise returns NULL. See NetworkInterface::get_default_instance for details.
00068      *
00069      *  @remark Application may override this (non-weak) default implementation.
00070      *
00071      *  @return default CellularDevice, NULL if not defined
00072      */
00073     static CellularDevice *get_default_instance();
00074 
00075     /** Return target onboard instance of CellularDevice
00076      *
00077      *  @remark Mbed OS target shall override (non-weak) this function for an onboard modem.
00078      *
00079      *  @return CellularDevice* instance, NULL if not defined
00080      */
00081     static CellularDevice *get_target_default_instance();
00082 
00083     /** Default constructor
00084      *
00085      *  @param fh   File handle used in communication with the modem.
00086      */
00087     CellularDevice(FileHandle *fh);
00088 
00089     /** virtual Destructor
00090      */
00091     virtual ~CellularDevice();
00092 
00093 public: //Virtual functions
00094 
00095     /** Clear modem to a default initial state
00096      *
00097      *  Clear persistent user data from the modem, such as PDP contexts.
00098      *
00099      *  @pre All open network services on modem, such as contexts and sockets, must be closed.
00100      *  @post Modem power off/on may be needed to clear modem's runtime state.
00101      *  @remark CellularStateMachine calls this on connect when `cellular.clear-on-connect: true`.
00102      *
00103      *  @return         NSAPI_ERROR_OK on success, otherwise modem may be need power cycling
00104      */
00105     virtual nsapi_error_t clear();
00106 
00107     /** Shutdown cellular device to minimum functionality.
00108      *
00109      *  Actual functionality is modem specific, for example UART may is not be responsive without
00110      *  explicit wakeup signal (such as RTS) after shutdown.
00111      *
00112      *  @remark You must call shutdown before power off to prepare the modem and to quit cellular network.
00113      *
00114      *  @return         NSAPI_ERROR_OK on success
00115      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00116      */
00117     virtual nsapi_error_t shutdown();
00118 
00119     /** Get the linked list of CellularContext instances
00120      *
00121      *  @return Pointer to first item in linked list
00122      */
00123     virtual CellularContext *get_context_list() const;
00124 
00125     /** Get event queue that can be chained to main event queue.
00126      *  @return event queue
00127      */
00128     virtual events::EventQueue *get_queue();
00129 
00130 protected: //Virtual functions
00131     /** Cellular callback to be attached to Network and CellularStateMachine classes.
00132      *  CellularContext calls this when in PPP mode to provide network changes.
00133      *  This method will broadcast to every interested classes:
00134      *  CellularContext (might be many) and CellularStateMachine if available.
00135      */
00136     virtual void cellular_callback(nsapi_event_t ev, intptr_t ptr, CellularContext *ctx = NULL);
00137 
00138 public: //Pure virtual functions
00139 
00140     /** Sets the modem up for powering on
00141      *  This is equivalent to plugging in the device, i.e., attaching power and serial port.
00142      *  In general, hard_power_on and soft_power_on provides a simple hardware abstraction layer
00143      *  on top of the modem drivers written for Mbed OS; they can be overridden
00144      *  in a derived class to perform custom power controls in a particular board configuration.
00145      *  In many boards this will be a no-op if there is no separate power supply control circuitry.
00146      *
00147      *  @remark CellularStateMachine calls hard_power_on at first until successful,
00148      *  then soft_power_on and init until the modem responds.
00149      *  If you are not using CellularStateMachine then you need to call these functions yourself.
00150      *
00151      *  @post You must call soft_power_on to power on the modem after calling hard_power_on.
00152      *
00153      *  @return         NSAPI_ERROR_OK on success
00154      */
00155     virtual nsapi_error_t hard_power_on() = 0;
00156 
00157     /** Sets the modem in unplugged state
00158      *
00159      *  This is equivalent to pulling the plug off of the device, i.e.,
00160      *  detaching power and serial port.
00161      *
00162      *  This puts the modem in the lowest power state.
00163      *
00164      *  @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
00165      *  but you need to do that yourself.
00166      *
00167      *  @pre You must call soft_power_off to power off the modem before calling hard_power_off.
00168      *
00169      *  @return         NSAPI_ERROR_OK on success
00170      */
00171     virtual nsapi_error_t hard_power_off() = 0;
00172 
00173     /** Powers up the modem
00174      *
00175      *  This is equivalent to pressing the "power button" to activate or reset the modem
00176      *  and usually implemented as a short pulse on a dedicated GPIO signal.
00177      *  It is expected to be present to make it possible to reset the modem.
00178      *  The driver may repeat this if the modem is not responsive to AT commands.
00179      *
00180      *  @remark CellularStateMachine calls this when requested to connect.
00181      *  If you are not using CellularStateMachine then you need to call this function yourself.
00182      *
00183      *  @post You must call init to setup the modem.
00184      *
00185      *  @return         NSAPI_ERROR_OK on success
00186      */
00187     virtual nsapi_error_t soft_power_on() = 0;
00188 
00189     /** Powers down the modem
00190      *
00191      *  This is equivalent to turning off the modem by button press.
00192      *
00193      *  @remark CellularStateMachine disconnect or destruct does not shutdown or power off the modem,
00194      *  but you need to do that yourself.
00195      *
00196      *  @pre You must call shutdown to prepare the modem for power off.
00197      *
00198      *  @return         NSAPI_ERROR_OK on success
00199      */
00200     virtual nsapi_error_t soft_power_off() = 0;
00201 
00202     /** Open the SIM card by setting the pin code for SIM.
00203      *
00204      *  @param sim_pin  PIN for the SIM card
00205      *  @return         NSAPI_ERROR_OK on success
00206      *                  NSAPI_ERROR_PARAMETER if sim_pin is null and sim is not ready
00207      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00208      */
00209     virtual nsapi_error_t set_pin(const char *sim_pin) = 0;
00210 
00211     /** Get SIM card's state
00212      *
00213      *  @param state    current state of SIM
00214      *  @return         NSAPI_ERROR_OK on success
00215      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00216      */
00217     virtual nsapi_error_t get_sim_state(SimState &state) = 0;
00218 
00219     /** Creates a new CellularContext interface.
00220      *
00221      *  @param fh       file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
00222      *                  file handle is used.
00223      *  @param apn      access point to use with context, can be null.
00224      *  @param cp_req       flag indicating if EPS control plane optimization is required
00225      *  @param nonip_req    flag indicating if this context is required to be Non-IP
00226      *
00227      *  @return         new instance of class CellularContext or NULL in case of failure
00228      *
00229      */
00230     virtual CellularContext *create_context(FileHandle *fh = NULL, const char *apn = NULL, bool cp_req = false, bool nonip_req = false) = 0;
00231 
00232 #if (DEVICE_SERIAL && DEVICE_INTERRUPTIN) || defined(DOXYGEN_ONLY)
00233     /** Creates a new CellularContext interface. This API should be used if serial is UART and PPP mode used.
00234      *  CellularContext created will use data carrier detect to be able to detect disconnection much faster in PPP mode.
00235      *  UARTSerial usually is the same which was given for the CellularDevice.
00236      *
00237      *  @param serial       UARTSerial used in communication to modem. If null then the default file handle is used.
00238      *  @param apn          access point to use with context, can be null.
00239      *  @param dcd_pin      Pin used to set data carrier detect on/off for the given UART
00240      *  @param active_high  a boolean set to true if DCD polarity is active low
00241      *  @param cp_req       Flag indicating if EPS control plane optimization is required
00242      *  @param nonip_req    Flag indicating if this context is required to be Non-IP
00243      *
00244      *  @return         new instance of class CellularContext or NULL in case of failure
00245      *
00246      */
00247     virtual CellularContext *create_context(UARTSerial *serial, const char *apn, PinName dcd_pin = NC,
00248                                             bool active_high = false, bool cp_req = false, bool nonip_req = false) = 0;
00249 #endif // #if DEVICE_SERIAL
00250 
00251     /** Deletes the given CellularContext instance
00252      *
00253      *  @param context CellularContext to delete
00254      */
00255     virtual void delete_context(CellularContext *context) = 0;
00256 
00257     /** Turn modem debug traces on
00258      *
00259      *  @param on         set true to enable debug traces
00260      */
00261     virtual void modem_debug_on(bool on) = 0;
00262 
00263     /** Initialize cellular device must be called right after the module is ready.
00264      *
00265      *  For example, when multiple cellular modules are supported in a single driver this function
00266      *  detects and adapts to an actual module at runtime.
00267      *
00268      *  @remark CellularStateMachine calls soft_power_on and init repeatedly when starting to connect
00269      *  until the modem responds.
00270      *
00271      *  @return         NSAPI_ERROR_OK on success
00272      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00273      *                  NSAPI_ERROR_UNSUPPORTED if current cellular module type is not detected
00274      *                  NSAPI_ERROR_DEVICE_ERROR if model information could not be read
00275      *
00276      */
00277     virtual nsapi_error_t init() = 0;
00278 
00279     /** Check whether the device is ready to accept commands.
00280      *
00281      *  @return         NSAPI_ERROR_OK on success
00282      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00283      */
00284     virtual nsapi_error_t is_ready() = 0;
00285 
00286     /** Set callback function to listen when device is ready.
00287      *
00288      *  @param callback function to call on device ready, or NULL to remove callback.
00289      */
00290     virtual void set_ready_cb(Callback<void()> callback) = 0;
00291 
00292     /** Set power save mode
00293      *
00294      *  @remark See 3GPP TS 27.007 PSM for details
00295      *
00296      *  @param periodic_time    in seconds to enable power save, or zero to disable
00297      *  @param active_time      in seconds to wait before entering power save mode
00298      *
00299      *  @return              NSAPI_ERROR_OK on success
00300      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00301      */
00302     virtual nsapi_error_t set_power_save_mode(int periodic_time, int active_time = 0) = 0;
00303 
00304     /** Get the current ATHandler instance in use for debug purposes etc.
00305      *  Once use has been finished call to release_at_handler() has to be made
00306      *
00307      *  @return Pointer to the ATHandler in use
00308      */
00309     virtual ATHandler *get_at_handler() = 0;
00310 
00311     /** Release the ATHandler taken into use with get_at_handler()
00312      *
00313      *  @param at_handler
00314      *  @return NSAPI_ERROR_OK on success, NSAPI_ERROR_PARAMETER on failure
00315      */
00316     virtual nsapi_error_t release_at_handler(ATHandler *at_handler) = 0;
00317 
00318     /** Sets cellular modem to given baud rate
00319      *
00320      *  @param baud_rate
00321      *  @return NSAPI_ERROR_OK on success, NSAPI_ERROR_DEVICE_ERROR on failure
00322      */
00323     virtual nsapi_error_t set_baud_rate(int baud_rate) = 0;
00324 
00325     /** Create new CellularNetwork interface.
00326      *
00327      *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
00328      *               file handle is used.
00329      *  @return      New instance of interface CellularNetwork.
00330      */
00331     virtual CellularNetwork *open_network(FileHandle *fh = NULL) = 0;
00332 
00333 #if MBED_CONF_CELLULAR_USE_SMS || defined(DOXYGEN_ONLY)
00334     /** Create new CellularSMS interface.
00335      *
00336      *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
00337      *               file handle is used.
00338      *  @return      New instance of interface CellularSMS.
00339      */
00340     virtual CellularSMS *open_sms(FileHandle *fh = NULL) = 0;
00341 
00342     /** Closes the opened CellularSMS by deleting the CellularSMS instance.
00343      */
00344     virtual void close_sms() = 0;
00345 
00346 #endif // MBED_CONF_CELLULAR_USE_SMS
00347 
00348     /** Create new CellularInformation interface.
00349      *
00350      *  @param fh    file handle used in communication to modem. This can be, for example, UART handle. If null, then the default
00351      *               file handle is used.
00352      *  @return      New instance of interface CellularInformation.
00353      */
00354     virtual CellularInformation *open_information(FileHandle *fh = NULL) = 0;
00355 
00356     /** Closes the opened CellularNetwork by deleting the CellularNetwork instance.
00357      */
00358     virtual void close_network() = 0;
00359 
00360     /** Closes the opened CellularInformation by deleting the CellularInformation instance.
00361      */
00362     virtual void close_information() = 0;
00363 
00364     /** Set the default response timeout.
00365      *
00366      *  @remark CellularStateMachine timeouts for all states are also changed to `timeout`.
00367      *
00368      *  @param timeout    milliseconds to wait response from modem
00369      */
00370     virtual void set_timeout(int timeout) = 0;
00371 
00372 
00373 public: //Common functions
00374 
00375     /** Stop the current operation. Operations: set_device_ready, set_sim_ready, register_to_network, attach_to_network
00376      *
00377      */
00378     MBED_DEPRECATED_SINCE("mbed-os-5.15", "Use CellularDevice::shutdown() instead.")
00379     void stop();
00380 
00381     /** Get the current FileHandle item used when communicating with the modem.
00382      *
00383      *  @return reference to FileHandle
00384      */
00385     FileHandle &get_file_handle() const;
00386 
00387     /** Set the pin code for SIM card
00388      *
00389      *  @param sim_pin      PIN for the SIM card
00390      */
00391     void set_sim_pin(const char *sim_pin);
00392 
00393     /** Plmn to use when registering to cellular network.
00394      *  If plmn is set, then registering is forced to this plmn. If plmn is not set, then automatic
00395      *  registering is used when registering to a cellular network. It doesn't start any operations.
00396      *
00397      *  @param plmn     plmn used when registering to cellular network
00398      */
00399     void set_plmn(const char *plmn);
00400 
00401     /** Start the interface
00402      *
00403      *  Initializes the modem for communication.
00404      *  API is asynchronous. Application can get results from CellularContext callback, which is set
00405      *  with attach(...), or callback, which is set by attach(...), in this class.
00406      *
00407      *  @return         NSAPI_ERROR_OK on success
00408      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00409      */
00410     nsapi_error_t set_device_ready();
00411 
00412     /** Start the interface
00413      *
00414      *  Attempts to open the sim.
00415      *  API is asynchronous. Application can get results from CellularContext callback, which is set
00416      *  with attach(...), or callback, which is set by attach(...), in this class.
00417      *
00418      *  @return         NSAPI_ERROR_OK on success
00419      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00420      */
00421     nsapi_error_t set_sim_ready();
00422 
00423     /** Start the interface
00424      *
00425      *  Attempts to register the device to cellular network.
00426      *  API is asynchronous. Application can get results from CellularContext callback, which is set
00427      *  with attach(...), or callback, which is set by attach(...), in this class.
00428      *
00429      *  @return         NSAPI_ERROR_OK on success
00430      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00431      */
00432     nsapi_error_t register_to_network();
00433 
00434     /** Start the interface
00435      *
00436      *  Attempts to attach the device to cellular network.
00437      *  API is asynchronous. Application can get results from CellularContext callback, which is set
00438      *  with attach(...), or callback, which is set by attach(...), in this class.
00439      *
00440      *  @return         NSAPI_ERROR_OK on success
00441      *                  NSAPI_ERROR_NO_MEMORY on case of memory failure
00442      */
00443     nsapi_error_t attach_to_network();
00444 
00445     /** Register callback for status reporting.
00446      *
00447      *  The specified status callback function will be called on the network and cellular device status changes.
00448      *  The parameters on the callback are the event type and event-type dependent reason parameter.
00449      *
00450      *  @remark  deleting CellularDevice/CellularContext in callback not allowed.
00451      *  @remark  Allocating/adding lots of traces not recommended as callback is called mostly from State machines thread which
00452      *           is now 2048. You can change to main thread for example via EventQueue.
00453      *
00454      *  @param status_cb The callback for status changes.
00455      */
00456     void attach(Callback<void(nsapi_event_t, intptr_t)> status_cb);
00457 
00458     /** Set an array of timeouts to wait before CellularStateMachine retries after failure.
00459      *  To disable retry behavior completely use `set_retry_timeout_array(NULL, 0)`.
00460      *  CellularContext callback event `cell_callback_data_t.final_try` indicates true when all retries have failed.
00461      *
00462      *  @remark Use `set_retry_timeout_array` for CellularStateMachine to wait before it retries again after failure,
00463      *          this is useful to send repetitive requests when don't know exactly when modem is ready to accept requests.
00464      *          Use `set_timeout` for timeout how long to wait for a response from modem for each request,
00465      *          this is useful if modem can accept requests but processing takes long time before sending response.
00466      *
00467      *  @param timeout      timeout array using seconds
00468      *  @param array_len    length of the array
00469      */
00470     void set_retry_timeout_array(const uint16_t timeout[], int array_len);
00471 
00472 protected: //Common functions
00473     friend class AT_CellularNetwork;
00474     friend class AT_CellularContext;
00475     friend class CellularContext;
00476 
00477     /** Get the retry array from the CellularStateMachine. Array is used in retry logic.
00478      *  Array contains seconds and retry logic uses those second to wait before trying again.
00479      *
00480      *  @param timeout      timeout array containing seconds for retry logic. Must have space for
00481      *                      CELLULAR_RETRY_ARRAY_SIZE (defined in CellularCommon.h)
00482      *  @param array_len    length of the timeout array on return
00483      */
00484     void get_retry_timeout_array(uint16_t *timeout, int &array_len) const;
00485 
00486 private: //Common functions
00487     nsapi_error_t start_state_machine(CellularStateMachine::CellularState target_state);
00488 
00489     nsapi_error_t create_state_machine();
00490 
00491     void stm_callback(nsapi_event_t ev, intptr_t ptr);
00492 
00493 protected: //Member variables
00494     int _network_ref_count;
00495 #if MBED_CONF_CELLULAR_USE_SMS
00496     int _sms_ref_count;
00497 #endif // MBED_CONF_CELLULAR_USE_SMS
00498     int _info_ref_count;
00499     FileHandle *_fh;
00500     events::EventQueue _queue;
00501     CellularStateMachine *_state_machine;
00502 
00503 private: //Member variables
00504     CellularNetwork *_nw;
00505     char _sim_pin[MAX_PIN_SIZE + 1];
00506     char _plmn[MAX_PLMN_SIZE + 1];
00507     PlatformMutex _mutex;
00508     Callback<void(nsapi_event_t, intptr_t)> _status_cb;
00509 
00510     const intptr_t *_property_array;
00511 };
00512 
00513 /**
00514  * @}
00515  */
00516 
00517 } // namespace mbed
00518 
00519 #endif // CELLULAR_DEVICE_H_