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](../pilot-v2/src/telemetry/mod.rs#L80-L125)

### Windows

**Status**: Stub implementation (returns None)

**TODO**: Implement using Windows API `GetSystemPowerStatus`:
```rust
use winapi::um::winbase::GetSystemPowerStatus;
use winapi::um::winnt::SYSTEM_POWER_STATUS;
```

**Code location**: [telemetry/mod.rs:127-132](../pilot-v2/src/telemetry/mod.rs#L127-L132)

## 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
```json
{
  "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
```json
{
  "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:
   ```bash
   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

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

### Automation Example

```yaml
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](../pilot-v2/src/telemetry/mod.rs) - Added battery reading logic
- [pilot-v2/src/ha/mod.rs](../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`:
```python
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.