Lamp-Da 0.1
A compact lantern project
Loading...
Searching...
No Matches
Namespaces | Classes | Typedefs | Functions | Variables
lampda::logic::power Namespace Reference

Main entry point of the power handling of the board. Responsible the main state of the power handling. More...

Namespaces

namespace  __private
 Internal implementations.
 

Classes

struct  OtgRampState
 State of the OTG output voltage ramp, for one OTG session. More...
 
struct  OutputLimitsLock
 Hold _outputLimitsMutex for the scope. More...
 
struct  TemporaryOutput
 A temporary output request, replacing the output limits for a duration. More...
 

Typedefs

using PowerStates = enum class power_states_t { STARTUP, IDLE, CLEAR_POWER_RAILS, CHARGING_MODE, OUTPUT_VOLTAGE_MODE, OTG_MODE, SHUTDOWN, ERROR, }
 Define the state for the power state machine.
 

Functions

void power_loop ()
 main loop of the power, running in another thread.
 
static int startup_probe (uint8_t address, common::RecoveryStage stage)
 
etl::string< 128 > get_error_string ()
 Return the error string if set, or "x".
 
void set_error_state_message (const etl::string< 128 > &errorMsg)
 Set the error message, if not already set.
 
bool is_output_mode_ready ()
 Return true when the current state is OUTPUT_VOLTAGE_MODE, and the desired voltage are set and gates are ready. Basically, it returns true when the output is being powered.
 
uint32_t get_vbus_rail_voltage ()
 
uint32_t get_power_rail_voltage ()
 
void set_otg_parameters (uint16_t voltage_mV, uint16_t current_mA, const bool isTargetingPort=false)
 Set the OnTheGo output power.
 
void reset_otg_ramp ()
 Clear the ramp state when the OTG output is turned off: the next session starts cold, at the default voltage.
 
uint16_t ramp_otg_voltage (const uint16_t target_mV)
 Limit the rising slew rate of the OTG output voltage.
 
void handle_clear_power_rails ()
 
void stop_sinking_to_swap ()
 leave the sink phase. The PD force source mode is set by the caller
 
bool handle_source_role_by_swap ()
 Battery mode: detect a partner powering VBUS, then attach as a sink and ask for the source role.
 
void handle_charging_mode ()
 
void handle_output_voltage_mode ()
 
void handle_otg_mode ()
 
void handle_shutdown ()
 
void handle_startup ()
 
void handle_error_state ()
 
bool is_in_error_state ()
 Return true if the power handling is locked in an ERROR state. No power actions can be made.
 
bool go_to_output_mode ()
 Set the power handler to main OUTPUT_VOLTAGE_MODE.
 
bool go_to_charger_mode ()
 Set the power handler to battery CHARGING_MODE.
 
bool go_to_otg_mode ()
 Set the power handler to OTG_MODE (eg: external battery mode)
 
bool go_to_idle ()
 Set the power handler to IDLE mode (no power output/input)
 
bool go_to_shutdown ()
 Set the power handler to SHUTDOWN mode (last mode before shuting system down) The power thread shuts the power components down, then stops running their loops. This call blocks until the shutdown is completed (or a timeout, after which the shutdown is forced from the calling thread).
 
bool go_to_error ()
 Set the power handler to ERROR mode (locked safety state)
 
void set_output_voltage_mv (const uint16_t outputVoltage_mV)
 Set the desired output voltage of the charger.
 
void set_output_max_current_mA (const uint16_t outputCurrent_mA)
 Set the desired maximum output current of the charger. This is just an information, that will be used when the state machine reaches the OUTPUT_VOLTAGE_MODE state.
 
void set_temporary_output (const uint16_t outputVoltage_mV, const uint16_t outputCurrent_mA, const uint16_t timeout_ms)
 Set a new output with a time limit, after wich the output will go back to the original values. It is canceled at any point by a call to set_output_voltage_mv. This is just an information, that will be used when the state machine reaches the OUTPUT_VOLTAGE_MODE state.
 
bool enable_charge (const bool)
 Block or allow the charging of the battery. Note that the system can still be in CHARGING_MODE mode if you set this to false, but the battery just wont charge.
 
etl::string< 32 > get_state ()
 Return the current state, as a string.
 
bool is_in_output_mode ()
 Return true if the current state is OUTPUT_VOLTAGE_MODE.
 
bool is_in_otg_mode ()
 Return true if the current state is OTG_MODE.
 
bool was_started_in_battery_recovery ()
 Indicates if the charger tried the battery recovery system.
 
bool is_in_in_battery_recovery ()
 Indicates that the system is currently attempting battery recovery.
 
template<typename... Args>
void report (const char *format, Args... values)
 
void show_recovery_diagnostics ()
 Read-only startup trace and current status. Does not initialize or enable charging.
 
void show_recovery_trace ()
 
bool is_setup ()
 Return true if the power handler system is effectivly started.
 
bool is_started ()
 Return true when power machine finally exits the STARTUP.
 
void init ()
 Call once at system startup. This can fail, and it would set the state to ERROR.
 

Variables

static std::atomic< bool > _isShutdownCompleted {false}
 Set to true by the power thread once the shutdown process is finished cleanly.
 
static std::atomic< uint32_t > _vbusGateFaultCount {0}
 VBUS gate fault edges, counted by the interrupt and shown by the power thread (issue #357)
 
static constexpr uint32_t shutdownCompletionTimeout_ms = 500
 Maximum time the caller of go_to_shutdown waits for the power thread to complete the shutdown.
 
static constexpr uint32_t clearPowerRailMinDelay_ms = 10
 Minimum allowed power rail clear delay.
 
static constexpr uint32_t clearPowerRailFailureDelay_ms = 3000
 Minimum power rail clear delay after which a failure is signaled. In some rare case the rail can take up to 2 seconds to clear itself.
 
static constexpr uint32_t otgNoUseTimeToDisconnect_ms = 5000
 Delay after which the OTG_MODE will auto disable if a disconnection is detected. Long enough for a dual role partner to attach again and swap to sink (about 1.5s, issue #357)
 
static constexpr uint8_t otgTurnOffTimeMinutes = 5
 Delay after which the OTG_MODE will auto disable if not used.
 
static constexpr uint32_t otgNoUseExtBatTimeToDisconnect_ms = 1000 * 60 * otgTurnOffTimeMinutes
 Delay after which the OTG_MODE will auto disable if not used, in milliseconds.
 
static constexpr uint32_t sourceHardResetGrace_ms = 2000
 
static constexpr uint32_t sourceHardResetMaxOvervoltage_mV = 500
 
static constexpr uint32_t otgVoltageRampSlew_mV_per_ms = 75
 
static constexpr uint32_t otgVoltageHighNoUseTimeout_ms = 10000
 
static constexpr uint32_t startupFailTimeout_ms = common::RecoveryTiming::startup_timeout_ms
 Delay after which the STARTUP state will auto switch to error.
 
static uint16_t _outputVoltage_mV = 0
 true voltage output. Only access it under _outputLimitsMutex
 
static uint16_t _outputCurrent_mA = 0
 true current output limit. Only access it under _outputLimitsMutex
 
static TemporaryOutput _temporaryOutput
 Requested by the main thread, applied and expired by the power thread. Only access it under _outputLimitsMutex, so that a request is always seen as a whole.
 
static hal::mutex::hal_mutex_t _outputLimitsMutex
 Guards all the output limits (_outputVoltage_mV, _outputCurrent_mA, _temporaryOutput): set by the main thread, applied by the power thread. Not recursive.
 
static const bool _isOutputLimitsMutexInit = (hal::mutex::hal_mutex_init(&_outputLimitsMutex), true)
 Initialized at program start: the output limits are written before the power init.
 
static bool _isChargeEnabled = false
 True if battery charging is allowed.
 
static etl::string< 128 > _errorStr = ""
 Store the state error description.
 
static bool _hasAutoSwitchedToOTG = false
 True if the state changed to OTG_MODE on it's own (via USB-PD requests).
 
static bool _isOtgFromRoleSwap = false
 True if the OTG_MODE was started by a power role swap requested by the partner (a phone charging the lamp). The PD state machine owns the source role: the OTG stops when it stops sourcing (swap back, detachment).
 
static bool _isInBatteryRecoveryMode = false
 in this mode, the battery is too low to power the components. They will be powered through the vbus gate.
 
static bool _wasStartedInBatteryRecoveryMode = false
 
static common::RecoveryTrace recoveryTrace
 
const char *const PowerStatesStr []
 Name of the states as strings.
 
static bool s_isOutputModeReady = false
 True if the OUTPUT_MODE state is ready, ie if the mode is active, the power is as requested and the output gate is enabled.
 
static OtgRampState _otgRamp
 
static uint32_t timeSinceOTGNoCurrentUse = 0
 time since no more current is used
 
static uint32_t timeSinceOTGCurrentUse = 0
 track the first current use time
 
static uint32_t voltageHighRaisedTime
 store the time at which the OTH mode detect high voltage on VBUS
 
static bool isInOtgModeForce = false
 Set to true when the PD machne was forced to source already.
 
static bool _isSinkingToSwap = false
 attached (or attaching) as a sink, to ask for a swap
 
static uint32_t _partnerVbusSince_ms = UINT32_MAX
 time since VBUS is present without our output
 
static uint32_t _sinkToSwapLastAttached_ms = 0
 last time the sink was attached, or the sink phase started
 
static constexpr uint32_t partnerVbusMin_mV = 4000
 partner VBUS detection threshold
 
static constexpr uint32_t partnerVbusDebounce_ms = 500
 also lets our own VBUS decay after a detachment
 
static constexpr uint32_t sinkToSwapNoAttachTimeout_ms = 2000
 back to source if no source partner attaches
 
static uint32_t _sinkToSwapLastRequest_ms = 0
 last swap request (the first one is at the contract)
 
static uint8_t _sinkToSwapRetries = 0
 swap requests made again, while attached
 
static bool _hasSourceRoleSwapFailed = false
 the partner keeps the source role: leave battery mode
 
static constexpr uint32_t sinkToSwapRetryDelay_ms = 2000
 delay between two swap requests
 
static constexpr uint8_t sinkToSwapMaxRetries = 3
 then the battery mode ends
 
static bool isSetup = false
 

Detailed Description

Main entry point of the power handling of the board. Responsible the main state of the power handling.

Function Documentation

◆ enable_charge()

bool lampda::logic::power::enable_charge ( const bool  )

Block or allow the charging of the battery. Note that the system can still be in CHARGING_MODE mode if you set this to false, but the battery just wont charge.

Returns
True if accepted

◆ get_error_string()

etl::string< 128 > lampda::logic::power::get_error_string ( )

Return the error string if set, or "x".

Return the current error message, as a string. If not errors are present, will return "x".

◆ go_to_charger_mode()

bool lampda::logic::power::go_to_charger_mode ( )

Set the power handler to battery CHARGING_MODE.

Returns
true if the mode switch is accepted

◆ go_to_error()

bool lampda::logic::power::go_to_error ( )

Set the power handler to ERROR mode (locked safety state)

Returns
true if the mode switch is accepted

◆ go_to_idle()

bool lampda::logic::power::go_to_idle ( )

Set the power handler to IDLE mode (no power output/input)

Returns
true if the mode switch is accepted

◆ go_to_otg_mode()

bool lampda::logic::power::go_to_otg_mode ( )

Set the power handler to OTG_MODE (eg: external battery mode)

Returns
true if the mode switch is accepted

◆ go_to_output_mode()

bool lampda::logic::power::go_to_output_mode ( )

Set the power handler to main OUTPUT_VOLTAGE_MODE.

Returns
true if the mode switch is accepted

◆ go_to_shutdown()

bool lampda::logic::power::go_to_shutdown ( )

Set the power handler to SHUTDOWN mode (last mode before shuting system down) The power thread shuts the power components down, then stops running their loops. This call blocks until the shutdown is completed (or a timeout, after which the shutdown is forced from the calling thread).

Returns
true if the power components shutdown is completed

◆ handle_source_role_by_swap()

bool lampda::logic::power::handle_source_role_by_swap ( )

Battery mode: detect a partner powering VBUS, then attach as a sink and ask for the source role.

Returns
true when the port must stay off

◆ handle_startup()

void lampda::logic::power::handle_startup ( )

Component initialization

◆ init()

void lampda::logic::power::init ( )

Call once at system startup. This can fail, and it would set the state to ERROR.

TODO: issue #326 handle the VBUS gate fault cleanly

◆ is_setup()

bool lampda::logic::power::is_setup ( )

Return true if the power handler system is effectivly started.

Returns
False if the init() call failed.

◆ ramp_otg_voltage()

uint16_t lampda::logic::power::ramp_otg_voltage ( const uint16_t  target_mV)

Limit the rising slew rate of the OTG output voltage.

Parameters
[in]target_mVThe voltage to reach
Returns
The voltage to apply now: a decrease is applied directly, an increase is ramped

◆ set_otg_parameters()

void lampda::logic::power::set_otg_parameters ( uint16_t  voltage_mV,
uint16_t  current_mA,
const bool  isTargetingPort = false 
)

Set the OnTheGo output power.

Parameters
[in]voltage_mVVoltage to output
[in]current_mACurrent to output
[in]isTargetingPortIf true, the current is set for the USB-C port. If false, it is set for the output gate

◆ set_output_max_current_mA()

void lampda::logic::power::set_output_max_current_mA ( const uint16_t  outputCurrent_mA)

Set the desired maximum output current of the charger. This is just an information, that will be used when the state machine reaches the OUTPUT_VOLTAGE_MODE state.

Parameters
[in]outputCurrent_mADesired maximum allowed output current, in milliamps

◆ set_output_voltage_mv()

void lampda::logic::power::set_output_voltage_mv ( const uint16_t  outputVoltage_mV)

Set the desired output voltage of the charger.

This is just an information, that will be used when the state machine reaches the OUTPUT_VOLTAGE_MODE state.

Parameters
[in]outputVoltage_mVDesired output voltage, in millivolts

◆ set_temporary_output()

void lampda::logic::power::set_temporary_output ( const uint16_t  outputVoltage_mV,
const uint16_t  outputCurrent_mA,
const uint16_t  timeout_ms 
)

Set a new output with a time limit, after wich the output will go back to the original values. It is canceled at any point by a call to set_output_voltage_mv. This is just an information, that will be used when the state machine reaches the OUTPUT_VOLTAGE_MODE state.

Parameters
[in]outputVoltage_mVdesired temporary output voltage, in millivolts
[in]outputCurrent_mAdesired temporary maximum output current, in milliamps
[in]timeout_msTime delay after which the temporary mode will be disabled

Variable Documentation

◆ _isSinkingToSwap

bool lampda::logic::power::_isSinkingToSwap = false
static

attached (or attaching) as a sink, to ask for a swap

Battery mode, partner powering VBUS (issue #357). A dual role partner with a 3A pull-up to 3.3V (4.7k, laptops) reads our Rp in parallel with the board permanent Rd under its Rd threshold: it takes the lamp for a sink, and powers VBUS. No CC setting can fix it (the board Rd is hardware), so the lamp attaches as a sink, without using that power, and asks for the source role (power role swap).

◆ PowerStatesStr

const char* const lampda::logic::power::PowerStatesStr[]
Initial value:
= {
"STARTUP",
"IDLE",
"CLEAR_POWER_RAILS",
"CHARGING_MODE",
"OUTPUT_VOLTAGE_MODE",
"OTG_MODE",
"SHUTDOWN",
"ERROR",
}

Name of the states as strings.

◆ voltageHighRaisedTime

uint32_t lampda::logic::power::voltageHighRaisedTime
static
Initial value:
=
UINT32_MAX

store the time at which the OTH mode detect high voltage on VBUS