pilot/docs/battery_feature.md

Battery Telemetry Feature

Date: 2025-12-30 Status: ✅ Implemented for Linux, ⚠️ Windows stub

Overview

Battery status telemetry has been added to Pilot v2, allowing Home Assistant to monitor laptop battery levels and charging states.

Implementation Details

Linux

Battery information is read from /sys/class/power_supply/ sysfs interface:

Detected devices:

• BAT0, BAT1, BAT2, etc.
• battery (generic name)

Read files:

• capacity - Battery level (0-100)
• status - Charging state

State mapping:

• Charging → "charging"
• Discharging → "discharging"
• Full → "full"
• Not charging → "not_charging"
• Other → "unknown"

Code location: telemetry/mod.rs:80-125

Windows

Status: Stub implementation (returns None)

TODO: Implement using Windows API GetSystemPowerStatus:

use winapi::um::winbase::GetSystemPowerStatus;
use winapi::um::winnt::SYSTEM_POWER_STATUS;

Code location: telemetry/mod.rs:127-132

MQTT Topics

Published topics (only when battery is detected):

• pilot/<device>/state/battery_level - Integer 0-100 (percentage)
• pilot/<device>/state/battery_state - String (charging/discharging/full/not_charging/unknown)

Example messages:

pilot/laptop-01/state/battery_level 85
pilot/laptop-01/state/battery_state discharging

Home Assistant Discovery

Two sensors are automatically discovered:

Battery Level Sensor

{
  "name": "Battery Level",
  "unique_id": "laptop-01_battery_level",
  "state_topic": "pilot/laptop-01/state/battery_level",
  "unit_of_measurement": "%",
  "device_class": "battery",
  "icon": "mdi:battery"
}

Battery State Sensor

{
  "name": "Battery State",
  "unique_id": "laptop-01_battery_state",
  "state_topic": "pilot/laptop-01/state/battery_state",
  "icon": "mdi:battery-charging"
}

Behavior

Systems WITH Battery

• Battery metrics published every telemetry interval (default: 10s)
• Values update in real-time as battery charges/discharges
• Home Assistant shows battery card with percentage and charging indicator

Systems WITHOUT Battery (Desktop)

• No battery topics published
• Home Assistant discovery still sent (entities show as "unavailable")
• No errors or warnings logged
• Zero performance impact

Testing

Manual Testing on Laptop

1. Start Pilot v2 on laptop with battery

2. Monitor MQTT messages:

   docker exec pilot-mosquitto mosquitto_sub -v -t 'pilot/#' | grep battery
   

3. Expected output:

   pilot/laptop/state/battery_level 95
   pilot/laptop/state/battery_state charging
   

4. Unplug AC adapter

5. Verify state changes to discharging

6. Plug in AC adapter

7. Verify state changes to charging

8. Let battery charge to 100%

9. Verify state changes to full

Testing on Desktop (No Battery)

1. Start Pilot v2 on desktop
2. Monitor MQTT - should see NO battery messages
3. Verify no errors in logs
4. CPU/memory telemetry should work normally

Home Assistant Integration

Dashboard Card Example

type: entities
entities:
  - entity: sensor.laptop_01_battery_level
    name: Battery
  - entity: sensor.laptop_01_battery_state
    name: Status

Automation Example

automation:
  - alias: "Low Battery Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.laptop_01_battery_level
        below: 20
      - platform: state
        entity_id: sensor.laptop_01_battery_state
        to: "discharging"
    condition:
      - condition: numeric_state
        entity_id: sensor.laptop_01_battery_level
        below: 20
    action:
      - service: notify.mobile_app
        data:
          message: "Laptop battery low: {{ states('sensor.laptop_01_battery_level') }}%"

Performance Impact

• CPU: Negligible (single sysfs read every 10s)
• Memory: ~100 bytes per read
• Disk I/O: 2 reads from sysfs every 10s
• Network: 2 MQTT messages every 10s (if battery present)

Error Handling

Graceful degradation when:

• /sys/class/power_supply/ doesn't exist → No battery messages
• Battery directory missing → No battery messages
• capacity or status file unreadable → No battery messages
• Parse errors → No battery messages

No errors logged - battery detection is silent and optional.

Future Enhancements

Priority: MEDIUM

1. Windows Support: Implement GetSystemPowerStatus API
2. Battery Health: Read charge_full and charge_full_design to calculate health %
3. Time Remaining: Calculate estimated time to empty/full
4. Multiple Batteries: Support systems with multiple battery packs

Priority: LOW

1. Battery Temperature: Read thermal sensors if available
2. Battery Technology: Report battery chemistry (Li-ion, Li-Po, etc.)
3. Charge Cycles: Report cycle count (some batteries expose this)

Code Changes

Files Modified

• pilot-v2/src/telemetry/mod.rs - Added battery reading logic
• pilot-v2/src/ha/mod.rs - Added battery discovery sensors

Lines of Code

• New code: ~80 lines
• Tests: 0 lines (manual testing only)
• Documentation: This file

Migration from V1

V1 had basic battery support in main_prog.py:

psutil.sensors_battery()

V2 improves on this:

• ✅ More reliable (direct sysfs access)
• ✅ Better error handling
• ✅ Cross-platform architecture (Windows ready)
• ✅ Home Assistant discovery included
• ✅ Graceful handling of missing battery

Conclusion

Battery telemetry is now fully functional on Linux systems. Laptops will automatically report battery level and charging state to Home Assistant without any configuration. Desktop systems continue to work normally without battery support.

Windows implementation is a straightforward TODO item using standard Windows API calls.