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