chenjintao/lucky-cat
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(power): add controlled low-battery shutdown

Browse Source
This commit is contained in:
chenjintao
2026-08-24 15:06:02 +08:00
parent 96e975d84c
commit 23f4969404
13 changed files with 467 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/control_plane/include/control_plane.h
+6
View File
@@ -130,6 +130,12 @@ esp_err_t control_plane_init(void);
*/
esp_err_t control_plane_battery_service_start(void);
/**
* Re-enter deep sleep before normal boot when a low-battery wake has not
* recovered and no charger is active.
*/
esp_err_t control_plane_battery_apply_boot_guard(void);
/**
* @brief Prepare platform-backed persistent storage before runtime workers start.
*
components/control_plane/internal/control_plane_internal.h
+1
View File
@@ -147,6 +147,7 @@ bool control_plane_voice_turn_is_idle(void);
bool control_plane_ota_voice_services_allowed(void);
bool control_plane_ota_business_interactions_allowed(void);
bool control_plane_runtime_is_stopping(void);
void control_plane_set_runtime_stop_requested(bool stop_requested);
esp_err_t control_plane_battery_service_stop(int timeout_ms);
void control_plane_battery_service_set_light_standby(bool standby);
components/control_plane/src/runtime/control_plane_battery_service.c
+206 -9
View File
@@ -25,9 +25,31 @@
#define BATTERY_FULL_CONFIRM_TIME_MS 5000
#define BATTERY_FULL_CONFIRM_SAMPLES 3U
#define BATTERY_FULL_MIN_VOLTAGE_MV 4050
#define BATTERY_SHUTDOWN_CONFIRM_SAMPLES 3U
#define BATTERY_EMERGENCY_CONFIRM_SAMPLES 2U
#define BATTERY_SHUTDOWN_RETRY_MS 1000
#define BATTERY_SHUTDOWN_TASK_STACK_BYTES 6144
#define BATTERY_SHUTDOWN_TASK_PRIORITY 5
#define BATTERY_SHUTDOWN_MOTOR_STOP_MS 2000
#define BATTERY_LOW_PROMPT_FILE "/littlefs/audio_prompts/battery_low_20.opus"
#define BATTERY_FULL_PROMPT_FILE "/littlefs/audio_prompts/charge_complete.opus"
#ifndef CONFIG_TQ_BATTERY_CONTROLLED_SHUTDOWN_ENABLE
#define CONFIG_TQ_BATTERY_CONTROLLED_SHUTDOWN_ENABLE 0
#endif
#ifndef CONFIG_TQ_BATTERY_SHUTDOWN_PROMPT_FILE
#define CONFIG_TQ_BATTERY_SHUTDOWN_PROMPT_FILE "/littlefs/audio_prompts/shutdown_power_empty.opus"
#endif
#if CONFIG_TQ_BATTERY_CONTROLLED_SHUTDOWN_ENABLE
#if CONFIG_TQ_BATTERY_EMERGENCY_VOLTAGE_MV >= CONFIG_TQ_BATTERY_SHUTDOWN_VOLTAGE_MV
#error "Emergency battery voltage must be below the controlled shutdown threshold"
#endif
#if CONFIG_TQ_BATTERY_WAKE_RECOVERY_VOLTAGE_MV <= CONFIG_TQ_BATTERY_SHUTDOWN_VOLTAGE_MV
#error "Battery wake recovery voltage must exceed the shutdown threshold"
#endif
#endif
#ifndef CONFIG_TQ_LIGHT_STANDBY_BATTERY_INTERVAL_SEC
#define CONFIG_TQ_LIGHT_STANDBY_BATTERY_INTERVAL_SEC 300
#endif
@@ -38,6 +60,17 @@ static bool s_stop_requested;
static bool s_starting;
static bool s_charge_gpio_isr_registered;
static bool s_light_standby;
static TaskHandle_t s_shutdown_task;
static uint8_t s_shutdown_confirmations;
static uint8_t s_emergency_confirmations;
typedef enum {
BATTERY_POWER_STATE_RUNNING = 0,
BATTERY_POWER_STATE_SHUTDOWN_REQUESTED,
BATTERY_POWER_STATE_SHUTTING_DOWN,
} battery_power_state_t;
static battery_power_state_t s_power_state = BATTERY_POWER_STATE_RUNNING;
static portMUX_TYPE s_battery_lock = portMUX_INITIALIZER_UNLOCKED;
static void IRAM_ATTR battery_charge_gpio_isr(void *arg)
@@ -145,14 +178,137 @@ static void battery_worker_finish(void)
portEXIT_CRITICAL(&s_battery_lock);
}
static void control_plane_battery_critical_hook(
static void battery_shutdown_task(void *arg)
{
(void)arg;
portENTER_CRITICAL(&s_battery_lock);
s_power_state = BATTERY_POWER_STATE_SHUTTING_DOWN;
portEXIT_CRITICAL(&s_battery_lock);
ESP_LOGW(TAG, "Controlled low-battery shutdown started");
control_plane_set_runtime_stop_requested(true);
(void)control_plane_local_wake_stop(BATTERY_SHUTDOWN_MOTOR_STOP_MS);
(void)control_plane_stop_ota_service(BATTERY_SHUTDOWN_MOTOR_STOP_MS);
(void)control_plane_stop_multimodal_client();
control_plane_stop_key_input_task();
control_plane_stop_system_event_task();
esp_err_t motor_err = domain_direction_release_motor_hold(
BATTERY_SHUTDOWN_MOTOR_STOP_MS);
if (motor_err != ESP_OK) {
ESP_LOGW(TAG, "Release stepper before shutdown failed: %s",
esp_err_to_name(motor_err));
}
(void)domain_runtime_multimodal_audio_stop_downstream_playback();
for (;;) {
esp_err_t audio_init_err = domain_runtime_multimodal_audio_init();
esp_err_t prompt_err = audio_init_err == ESP_OK
? domain_runtime_behavior_play_prompt_file(
CONFIG_TQ_BATTERY_SHUTDOWN_PROMPT_FILE)
: audio_init_err;
if (prompt_err == ESP_OK) {
break;
}
/* The product requires the complete prompt before entering deep sleep. */
ESP_LOGE(TAG,
"Shutdown prompt did not complete; retrying: %s",
esp_err_to_name(prompt_err));
vTaskDelay(pdMS_TO_TICKS(BATTERY_SHUTDOWN_RETRY_MS));
}
(void)domain_runtime_multimodal_audio_set_speaker_output_enabled(false);
domain_runtime_multimodal_audio_deinit();
(void)domain_runtime_set_lcd_backlight_brightness(0U);
(void)domain_runtime_wifi_portal_stop_sta();
ESP_LOGW(TAG, "Shutdown prompt completed; entering deep sleep");
esp_err_t sleep_err = domain_battery_prepare_shutdown();
ESP_LOGE(TAG, "Enter deep sleep failed: %s", esp_err_to_name(sleep_err));
portENTER_CRITICAL(&s_battery_lock);
s_power_state = BATTERY_POWER_STATE_RUNNING;
s_shutdown_task = NULL;
portEXIT_CRITICAL(&s_battery_lock);
vTaskDelete(NULL);
}
static void battery_consider_controlled_shutdown(
const domain_battery_status_t *status)
{
#if CONFIG_TQ_BATTERY_CONTROLLED_SHUTDOWN_ENABLE
if (status == NULL) {
return;
}
portENTER_CRITICAL(&s_battery_lock);
bool already_requested = s_power_state != BATTERY_POWER_STATE_RUNNING;
portEXIT_CRITICAL(&s_battery_lock);
if (already_requested) {
return;
}
if (status->charge_state == DOMAIN_BATTERY_CHARGE_CHARGING) {
s_shutdown_confirmations = 0U;
s_emergency_confirmations = 0U;
return;
}
bool normal_sample = status->valid && !status->measurement_suppressed &&
status->percentage <= CONFIG_TQ_BATTERY_CRITICAL_ENTER_PERCENT &&
status->voltage_mv <= CONFIG_TQ_BATTERY_SHUTDOWN_VOLTAGE_MV;
bool emergency_sample = status->latest_sample_valid &&
status->latest_sample_mv <= CONFIG_TQ_BATTERY_EMERGENCY_VOLTAGE_MV;
if (normal_sample) {
if (s_shutdown_confirmations < UINT8_MAX) {
++s_shutdown_confirmations;
}
} else {
s_shutdown_confirmations = 0U;
}
if (emergency_sample) {
if (s_emergency_confirmations < UINT8_MAX) {
++s_emergency_confirmations;
}
} else {
s_emergency_confirmations = 0U;
}
if (s_shutdown_confirmations < BATTERY_SHUTDOWN_CONFIRM_SAMPLES &&
s_emergency_confirmations < BATTERY_EMERGENCY_CONFIRM_SAMPLES) {
return;
}
portENTER_CRITICAL(&s_battery_lock);
if (s_power_state != BATTERY_POWER_STATE_RUNNING || s_shutdown_task != NULL) {
portEXIT_CRITICAL(&s_battery_lock);
return;
}
s_power_state = BATTERY_POWER_STATE_SHUTDOWN_REQUESTED;
portEXIT_CRITICAL(&s_battery_lock);
TaskHandle_t task = NULL;
BaseType_t created = xTaskCreate(battery_shutdown_task,
"cp_bat_shutdown",
BATTERY_SHUTDOWN_TASK_STACK_BYTES,
NULL,
BATTERY_SHUTDOWN_TASK_PRIORITY,
&task);
portENTER_CRITICAL(&s_battery_lock);
if (created == pdPASS && task != NULL) {
s_shutdown_task = task;
} else {
s_power_state = BATTERY_POWER_STATE_RUNNING;
}
portEXIT_CRITICAL(&s_battery_lock);
if (created != pdPASS || task == NULL) {
ESP_LOGE(TAG, "Create controlled-shutdown task failed");
}
#else
(void)status;
/*
* Reserved for a future product decision. Do not stop actuators, enter
* sleep, or cut board power in this release.
*/
#endif
}
static void control_plane_battery_low_hook(
@@ -268,9 +424,6 @@ static void battery_worker(void *arg)
previous_level == DOMAIN_BATTERY_LEVEL_UNKNOWN)) {
control_plane_battery_low_hook(&status);
}
if (status.level_state == DOMAIN_BATTERY_LEVEL_CRITICAL) {
control_plane_battery_critical_hook(&status);
}
previous_level = status.level_state;
}
if (status.charge_state != previous_charge) {
@@ -321,12 +474,15 @@ static void battery_worker(void *arg)
}
}
}
battery_consider_controlled_shutdown(&status);
}
uint32_t delay_ms;
if (status_err == ESP_OK && status.measurement_suppressed) {
delay_ms = BATTERY_SUPPRESSED_RETRY_MS;
} else if (full_hint_candidate) {
} else if (full_hint_candidate || s_shutdown_confirmations > 0U ||
s_emergency_confirmations > 0U) {
delay_ms = BATTERY_FULL_CONFIRM_RETRY_MS;
} else if (battery_light_standby()) {
delay_ms = (uint32_t)CONFIG_TQ_LIGHT_STANDBY_BATTERY_INTERVAL_SEC * 1000U;
@@ -347,6 +503,42 @@ static void battery_worker(void *arg)
vTaskDelete(NULL);
}
esp_err_t control_plane_battery_apply_boot_guard(void)
{
#if CONFIG_TQ_BATTERY_CONTROLLED_SHUTDOWN_ENABLE
if (!domain_battery_woke_from_deep_sleep()) {
return ESP_OK;
}
esp_err_t sample_err = domain_battery_sample();
if (sample_err != ESP_OK) {
return sample_err;
}
domain_battery_status_t status = {0};
esp_err_t status_err = domain_battery_get_status(&status);
if (status_err != ESP_OK) {
return status_err;
}
ESP_LOGW(TAG,
"Deep-sleep wake battery check voltage=%dmV charge=%s valid=%d",
status.voltage_mv,
charge_state_name(status.charge_state),
status.valid);
if (status.charge_state == DOMAIN_BATTERY_CHARGE_CHARGING ||
(status.valid &&
status.voltage_mv >= CONFIG_TQ_BATTERY_WAKE_RECOVERY_VOLTAGE_MV)) {
domain_battery_complete_wakeup();
return ESP_OK;
}
ESP_LOGW(TAG, "Battery has not recovered; returning to deep sleep");
return domain_battery_prepare_shutdown();
#else
return ESP_ERR_NOT_SUPPORTED;
#endif
}
esp_err_t control_plane_battery_service_start(void)
{
portENTER_CRITICAL(&s_battery_lock);
@@ -442,6 +634,11 @@ esp_err_t control_plane_battery_service_start(void)
return ESP_ERR_NOT_SUPPORTED;
}
esp_err_t control_plane_battery_apply_boot_guard(void)
{
return ESP_ERR_NOT_SUPPORTED;
}
esp_err_t control_plane_battery_service_stop(int timeout_ms)
{
return timeout_ms < 0 ? ESP_ERR_INVALID_ARG : ESP_OK;
components/control_plane/src/runtime/control_plane_runtime_workers.c
+1 -1
View File
@@ -490,7 +490,7 @@ static bool control_plane_runtime_stop_requested(void)
return control_plane_runtime_is_stopping();
}
static void control_plane_set_runtime_stop_requested(bool stop_requested)
void control_plane_set_runtime_stop_requested(bool stop_requested)
{
portENTER_CRITICAL(&s_runtime_lock);
s_runtime_stop_requested = stop_requested;