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      *  @param do_reset     0 for do not reset, 1 for reset the device when changing the functionality
00090      *
00091      *  @remark See 3GPP TS 27.007 CFUN for more details
00092      *
00093      *  @return zero on success
00094      */
00095     virtual nsapi_error_t set_power_level(int func_level, int do_reset = 1) = 0;
00096 
00097     /** Reset and wake-up cellular device.
00098      *
00099      *  @return zero on success
00100      */
00101     virtual nsapi_error_t reset() = 0;
00102 
00103     /** Opt for power save setting on cellular device. If both parameters are zero then disables PSM.
00104      *
00105      *  @remark See 3GPP TS 27.007 PSM for details
00106      *
00107      *  @param periodic_time Timeout in seconds IoT subsystem is not expecting messaging
00108      *  @param active_time   Timeout in seconds IoT subsystem waits for response
00109      *  @return              zero on success
00110      */
00111     virtual nsapi_error_t opt_power_save_mode(int periodic_time, int active_time) = 0;
00112 
00113     /** Opt for discontinuous reception on cellular device.
00114      *
00115      *  @remark See 3GPP TS 27.007 eDRX for details.
00116      *
00117      *  @param mode          disable or enable the use of eDRX
00118      *  @param act_type      type of access technology
00119      *  @param edrx_value    requested edxr value. Extended DRX parameters information element.
00120      *
00121      *  @return              zero on success
00122      */
00123     virtual nsapi_error_t opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0;
00124 
00125     /** Check whether the device is ready to accept commands.
00126      *
00127      *  @return     zero on success
00128      */
00129     virtual nsapi_error_t is_device_ready() = 0;
00130 
00131     /** Set URC callback function for device specific ready urc. URC is defined in device specific
00132      *  power API. Used in startup sequence to listen when device is ready
00133      *  for using at commands and possible sim.
00134      *
00135      *  @param callback Callback function called when urc received
00136      *  @return         zero on success
00137      */
00138     virtual nsapi_error_t set_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;
00139 
00140     /** Removes the device ready urc from the list of urc's.
00141      *
00142      *  @param callback callback to remove from the list of urc's
00143      */
00144     virtual void remove_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;
00145 };
00146 
00147 } // namespace mbed
00148 
00149 #endif /* CELLULAR_API_CELLULARPOWER_H_ */