跳到主要内容
版本：1.1.0

Power API

power 模块对接 PMU：

  • 读：电源摘要、详细状态、当前活动电池、事件流。
  • 写：开关电源轨/灯光、设置风扇转速、切换电池包、清除故障、查询固件版本。

控制接口会直接影响真实硬件，操作前请确认目标与现场安全条件。

应用侧至少包含 Session 与 Power Client 头文件；电池/状态/控制等数据类型头文件已由后者间接引入：

#include <latentos/sdk/core/session.h>
#include <latentos/sdk/power/power_client.h>

CMake 中查找并链接对应模块包。安装前缀需已加入 CMAKE_PREFIX_PATH（常见为 /data/latentos/sdk_cpp）：

find_package(latentos_sdk_power CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE latentos::sdk_power)

入口类为 latentos::sdk::power::PowerClient，构造时传入已配置好的 core::Session。公开方法如下：

explicit PowerClient(core::Session& session);

void SubscribeSummary(SummaryCallback callback);
std::optional<PowerSummary> GetLatestSummary() const;
void SubscribeStatus(StatusCallback callback);
std::optional<PowerStatus> GetLatestStatus() const;
void SubscribeBattery(BatteryCallback callback);
std::optional<BatteryStatus> GetLatestBattery() const;
void SubscribeEvent(EventCallback callback);
std::optional<PowerEvent> GetLatestEvent() const;

PowerControlResult SetPowerRail(PowerRail rail, bool on,
                                PowerControlOptions options = {});
PowerControlResult SetPowerLight(PowerLight light, bool on,
                                 PowerControlOptions options = {});
PowerControlResult SetPowerFanSpeed(PowerFan fan, int percent,
                                    PowerControlOptions options = {});
PowerControlResult ClearPowerFaults(PowerControlOptions options = {});
PowerControlResult QueryPowerVersion(PowerControlOptions options = {});

方法​

方法说明
SubscribeSummary / GetLatestSummary订阅/读取整机电源摘要
SubscribeStatus / GetLatestStatus订阅/读取电源轨、故障、风扇及固件状态
SubscribeBattery / GetLatestBattery订阅/读取当前活动电池
SubscribeEvent / GetLatestEvent订阅/读取 PMU 事件
SetPowerRail开关指定电源轨
SetPowerLight开关指定灯光
SetPowerFanSpeed设置风扇速度百分比（0–100）
ClearPowerFaults清除当前故障
QueryPowerVersion查询 PMU 固件版本

只读接口遵循两步式：先 Subscribe*()，再 GetLatest*()。控制接口为阻塞请求/回复，成功通常至少要求 ok && accepted。

只读状态​

BatteryStatus​

头文件：<latentos/sdk/power/battery.h>

SDK 从接入的电池包中选择当前活动包，并提供统一状态。

字段类型说明
okbool数据是否有效
stalebool数据是否过期
presentbool电池包是否接入
pack_indexstd::int32_t电池包编号
soc_percentdouble剩余电量百分比
remaining_capacity_mahdoubleBMS 容量估计，仅供诊断
voltage_v / current_adouble电压 V、电流 A
sample_time_ns / sequence整数采样时间和消息序号
messagestd::string状态说明
power_stateBatteryPowerState整机充放电状态

BatteryPowerState：Unknown、Charging、Discharging、NotCharging、Full。使用前同时检查 ok、present 和 stale。

读取 BatteryStatus（轮询）​

#include <latentos/sdk/core/session.h>
#include <latentos/sdk/power/power_client.h>

#include <chrono>
#include <iostream>
#include <thread>
#include <utility>

latentos::sdk::SdkOptions options;
options.client_config_path = "config/echo/mode/client.yaml";
latentos::sdk::core::Session session(std::move(options));
latentos::sdk::power::PowerClient power(session);

power.SubscribeBattery({});

for (int waited_ms = 0; waited_ms < 5000; waited_ms += 50) {
  const auto battery = power.GetLatestBattery();
  if (!battery.has_value()) {
    std::this_thread::sleep_for(std::chrono::milliseconds(50));
    continue;
  }
  const auto& status = *battery;
  std::cout << "ok=" << status.ok
            << " present=" << status.present
            << " stale=" << status.stale
            << " power_state=" << latentos::sdk::ToString(status.power_state)
            << " soc_percent=" << status.soc_percent
            << " voltage_v=" << status.voltage_v
            << " current_a=" << status.current_a << '\n';
  break;
}

PowerSummary​

头文件：<latentos/sdk/power/summary.h>

字段组说明
send_time_ns、sample_time_ns、sequence时间与消息序号
online、stale、health_level在线、时效与综合健康状态
work_allowed、motion_pause_required是否允许工作、是否要求暂停运动
scram_active、fault_active、fault_summary急停与故障摘要
pack1_connected、pack2_connected、connected_pack_count电池连接情况
min_soc_percent、min_cell_voltage_v、max_temperature_c关键电池安全指标

PowerHealthLevel：Unknown、Ok、Warn、Fault、Stale。

PowerStatus​

头文件：<latentos/sdk/power/status.h>

字段组说明
send_time_ns、sample_time_ns、sequence、stale时间、序号与时效
firmware_version、debug_enabledPMU 固件与调试状态
scram_active、fault_active急停与故障状态
pack1_connected、pack2_connected、connected_pack_count电池连接情况
pack1_mos_on、pack2_mos_on电池 MOS 状态
motor_soft_on、motor_hv_on、external_48v_on电源轨状态
light1_on、light2_on灯光状态
fault_name、fault_description、fault_num故障摘要
fault_detail_name、fault_detail_description故障明细数组
motor_current_a、motor_voltage_v电机母线电流和电压
bat1_5v_v、bat1_48v_v、bat2_5v_v、bat2_48v_v电池电压测量
fan_num、fan_rpm风扇数量和转速

PowerEvent​

头文件：<latentos/sdk/power/event.h>

字段说明
send_time_ns、event_time_ns、sequence时间与序号
event_id事件标识
severityPowerEventSeverity
event_typePowerEventType
message可读事件信息
pack_index相关电池包编号
fault_name / fault_description相关故障信息

事件级别：Info、Warn、Error、Fatal。

事件类型：Unknown、ScramPressed、ScramReleased、FaultRaised、FaultCleared、BatteryConnected、BatteryDisconnected、StatusStale、StatusRecovered。

控制​

控制目标​

类型枚举值
PowerRailLegs、External48V1、External48V2
PowerLightWhite、Infrared
PowerFanFan1 至 Fan6

SetPowerFanSpeed() 的 percent 范围为 0–100。

PowerControlOptions​

字段默认值说明
timeout_ms1000请求超时，ms
forcefalse在 PMU 允许时绕过软联锁；不能绕过硬件安全限制
reason空操作原因，供目标端记录
requesterSDK 默认值请求方标识，通常无需设置

PowerControlResult​

字段说明
ok是否成功收到并解析回复
acceptedPMU 是否接受操作
result_codePowerControlResultCode
result_message可读结果说明
versionQueryPowerVersion() 成功时的版本
status_refreshed操作后是否已刷新状态
handled_at_ns / request_id处理时间与请求标识

结果码包括 Ok、Accepted、RejectedByMode、RejectedBySafety、InvalidArgument、DeviceNotOpen、DeviceTimeout、DeviceError、Busy、UnsupportedOperation、InternalError。

注意

电源轨、电池切换和风扇控制会直接影响真实硬件。执行前确认目标枚举、当前工作模式和现场条件；不要因为 ok == true 就忽略 accepted 与 result_code。

控制示例​

latentos::sdk::PowerControlOptions control_options;
control_options.timeout_ms = 1000;
control_options.reason = "operator request";

auto rail = power.SetPowerRail(
    latentos::sdk::PowerRail::Legs, /*on=*/true, control_options);
std::cout << "ok=" << rail.ok
          << " accepted=" << rail.accepted
          << " code=" << latentos::sdk::ToString(rail.result_code)
          << '\n';

auto light = power.SetPowerLight(
    latentos::sdk::PowerLight::White, /*on=*/true, control_options);
auto fan = power.SetPowerFanSpeed(
    latentos::sdk::PowerFan::Fan1, /*percent=*/40, control_options);
auto version = power.QueryPowerVersion(control_options);
if (version.ok) {
  std::cout << "pmu version=" << version.version << '\n';
}

电池充放电示例见 电池状态；更多控制见 latentos_sdk_example 的 power_control。

相关文档​