CellularPower.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 #ifndef CELLULAR_API_CELLULARPOWER_H_
00018 #define CELLULAR_API_CELLULARPOWER_H_
00019 
00020 #include "nsapi_types.h"
00021 #include "Callback.h"
00022 
00023 namespace mbed
00024 {
00025 
00026 /**
00027  *  Class CellularPower
00028  *
00029  *  An interface that provides power handling functions for modem/module.
00030  */
00031 class CellularPower
00032 {
00033 protected:
00034     // friend of CellularDevice so that it's the only way to close/delete this class.
00035     friend class CellularDevice;
00036 
00037     /**
00038      * virtual Destructor
00039      */
00040     virtual ~CellularPower() {}
00041 
00042 public:
00043     /* Access technology used in method opt_receive_period */
00044     enum EDRXAccessTechnology {
00045         EDRXGSM_EC_GSM_IoT_mode = 1,
00046         EDRXGSM_A_Gb_mode,
00047         EDRXUTRAN_Iu_mode,
00048         EDRXEUTRAN_WB_S1_mode,
00049         EDRXEUTRAN_NB_S1_mode
00050     };
00051 
00052     /** Set cellular device power on. Default implementation is empty.
00053      *  Device power on/off is modem/board specific behavior and must be done on inherited class if needed.
00054      *  Power on is done by toggling power pin/button.
00055      *
00056      *  @remark set_at_mode must be called to initialise modem
00057      *
00058      *  @return zero on success
00059      */
00060     virtual nsapi_error_t on() = 0;
00061 
00062     /** Set cellular device power off. Default implementation is empty.
00063      *  Device power on/off is modem/board specific behavior and must be done on inherited class if needed.
00064      *  Power off is done by toggling power pin/button.
00065      *
00066      *
00067      *  @return zero on success
00068      */
00069     virtual nsapi_error_t off() = 0;
00070 
00071     /** Set AT command mode. Blocking until success or failure.
00072      *
00073      *  @remark must be called after power on to prepare correct AT mode
00074      *
00075      *  @return zero on success
00076      */
00077     virtual nsapi_error_t set_at_mode() = 0;
00078 
00079     /** Set cellular device power level by enabling/disabling functionality.
00080      *
00081      *  @param func_level:
00082      *  0   minimum functionality
00083      *  1   full functionality. Enable (turn on) the transmit and receive RF circuits for all supported radio access technologies.
00084      *      For MTs supporting +CSRA, this equals the RATs indicated by the response of +CSRA=?. Current +CSRA setting is ignored.
00085      *      It is not required that the MT transmit and receive RF circuits are in a disabled state for this setting to have effect.
00086      *  2   disable (turn off) MT transmit RF circuits only
00087      *  3   disable (turn off) MT receive RF circuits only
00088      *  4   disable (turn off) both MT transmit and receive RF circuits
00089      *
00090      *  @remark See 3GPP TS 27.007 CFUN for more details
00091      *
00092      *  @return zero on success
00093      */
00094     virtual nsapi_error_t set_power_level(int func_level) = 0;
00095 
00096     /** Reset and wake-up cellular device.
00097      *
00098      *  @return zero on success
00099      */
00100     virtual nsapi_error_t reset() = 0;
00101 
00102     /** Opt for power save setting on cellular device. If both parameters are zero then disables PSM.
00103      *
00104      *  @remark See 3GPP TS 27.007 PSM for details
00105      *
00106      *  @param periodic_time Timeout in seconds IoT subsystem is not expecting messaging
00107      *  @param active_time   Timeout in seconds IoT subsystem waits for response
00108      *  @return              zero on success
00109      */
00110     virtual nsapi_error_t opt_power_save_mode(int periodic_time, int active_time) = 0;
00111 
00112     /** Opt for discontinuous reception on cellular device.
00113      *
00114      *  @remark See 3GPP TS 27.007 eDRX for details.
00115      *
00116      *  @param mode          disable or enable the use of eDRX
00117      *  @param act_type      type of access technology
00118      *  @param edrx_value    requested edxr value. Extended DRX parameters information element.
00119      *
00120      *  @return              zero on success
00121      */
00122     virtual nsapi_error_t opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0;
00123 
00124     /** Set URC callback function for device specific ready urc. URC is defined in device specific
00125      *  power API. Used in startup sequence to listen when device is ready
00126      *  for using at commands and possible sim.
00127      *
00128      *  @param callback Callback function called when urc received
00129      *  @return         zero on success
00130      */
00131     virtual nsapi_error_t set_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;
00132 
00133     /** Removes the device ready urc from the list of urc's.
00134      *
00135      *  @param callback callback to remove from the list of urc's
00136      */
00137     virtual void remove_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;
00138 };
00139 
00140 } // namespace mbed
00141 
00142 #endif /* CELLULAR_API_CELLULARPOWER_H_ */