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  *  Class CellularPower
00027  *
00028  *  An interface that provides power handling functions for modem/module.
00029  */
00030 class CellularPower {
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         NSAPI_ERROR_OK on success
00057      *                  NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem
00058      */
00059     virtual nsapi_error_t on() = 0;
00060 
00061     /** Set cellular device power off. Default implementation is empty.
00062      *  Device power on/off is modem/board specific behavior and must be done on inherited class if needed.
00063      *  Power off is done by toggling power pin/button.
00064      *
00065      *  @return         NSAPI_ERROR_OK on success
00066      *                  NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem
00067      */
00068     virtual nsapi_error_t off() = 0;
00069 
00070     /** Set AT command mode. Blocking until success or failure.
00071      *
00072      *  @remark must be called after power on to prepare correct AT mode
00073      *
00074      *  @return         NSAPI_ERROR_OK on success
00075      *                  NSAPI_ERROR_DEVICE_ERROR on failure
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         NSAPI_ERROR_OK on success
00094      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00095      */
00096     virtual nsapi_error_t set_power_level(int func_level, int do_reset = 0) = 0;
00097 
00098     /** Reset and wake-up cellular device.
00099      *
00100      *  @return         NSAPI_ERROR_OK on success
00101      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00102      */
00103     virtual nsapi_error_t reset() = 0;
00104 
00105     /** Opt for power save setting on cellular device. If both parameters are zero, this disables PSM.
00106      *
00107      *  @remark See 3GPP TS 27.007 PSM for details
00108      *
00109      *  @param periodic_time Timeout in seconds IoT subsystem is not expecting messaging
00110      *  @param active_time   Timeout in seconds IoT subsystem waits for response
00111      *
00112      *  @return              NSAPI_ERROR_OK on success
00113      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00114      */
00115     virtual nsapi_error_t opt_power_save_mode(int periodic_time, int active_time) = 0;
00116 
00117     /** Opt for discontinuous reception on cellular device.
00118      *
00119      *  @remark See 3GPP TS 27.007 eDRX for details.
00120      *
00121      *  @param mode          disable or enable the use of eDRX
00122      *  @param act_type      type of access technology
00123      *  @param edrx_value    requested edxr value. Extended DRX parameters information element.
00124      *
00125      *  @return              NSAPI_ERROR_OK on success
00126      *                       NSAPI_ERROR_DEVICE_ERROR on failure
00127      */
00128     virtual nsapi_error_t opt_receive_period(int mode, EDRXAccessTechnology act_type, uint8_t edrx_value) = 0;
00129 
00130     /** Check whether the device is ready to accept commands.
00131      *
00132      *  @return         NSAPI_ERROR_OK on success
00133      *                  NSAPI_ERROR_DEVICE_ERROR on failure
00134      */
00135     virtual nsapi_error_t is_device_ready() = 0;
00136 
00137     /** Set URC callback function for device specific ready urc. URC is defined in device specific
00138      *  power API. Used in startup sequence to listen when device is ready
00139      *  for using at commands and possible sim.
00140      *
00141      *  @param callback Callback function called when urc received
00142      *
00143      *  @return         NSAPI_ERROR_OK on success
00144      *                  NSAPI_ERROR_NO_MEMORY on memory failure
00145      *                  NSAPI_ERROR_UNSUPPORTED if not overridden by the target modem
00146      */
00147     virtual nsapi_error_t set_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;
00148 
00149     /** Removes the device ready urc from the list of urc's.
00150      *
00151      *  @param callback callback to remove from the list of urc's
00152      */
00153     virtual void remove_device_ready_urc_cb(mbed::Callback<void()> callback) = 0;
00154 };
00155 
00156 } // namespace mbed
00157 
00158 #endif /* CELLULAR_API_CELLULARPOWER_H_ */