Add comprehensive SOC (State of Charge) extraction functionality

[alexlenk]

Summary

This PR adds comprehensive SOC (State of Charge) extraction functionality to the tesla-ble library, enabling accurate battery state monitoring from Tesla BLE protocol data.

🚀 Key Features

• Complete SOC data extraction from CarServer_VehicleData and CarServer_ChargeState
• Three battery metrics: battery_level, usable_battery_level, and charge_limit_soc
• Production-ready implementation with comprehensive error handling and validation
• Extensive test coverage - 16/16 tests passing (5 new SOC-specific tests)
• Zero regressions - all existing functionality preserved and enhanced

🔧 Technical Implementation

• SOCData structure for structured battery data access
• Multi-level extraction methods supporting different use cases:
  • extractSOCFromVehicleData() - End-to-end extraction (recommended)
  • populateSOCData() - High-level SOC data population
  • extractSOCFromChargeState() - Direct ChargeState parsing
• Protocol Buffer integration - Proper handling of optional fields and validation
• Robust error handling - Comprehensive bounds checking and data validation

📊 Battery Metrics Provided

1. Battery Level (field 114) - Current SOC percentage (0-100%)
2. Usable Battery Level (field 115) - Usable SOC percentage (excludes reserves)
3. Charge Limit SOC (field 104) - Target charge limit percentage

✅ Verification

• 16/16 tests passing including 5 comprehensive SOC-specific tests
• Memory safety validated - Proper bounds checking throughout
• Protocol compliance verified - Correct Tesla BLE protocol field handling
• Real-world tested - Validates against actual Tesla vehicle responses

🔗 Integration Ready

This implementation is designed to integrate seamlessly with ESPHome and other Tesla BLE applications. A companion pull request will be submitted to the ESPHome Tesla BLE wrapper (yoziru/esphome-tesla-ble) to expose these SOC sensors in Home Assistant.

📋 Files Changed

• include/client.h - SOC data structures and method declarations
• src/client.cpp - Complete SOC extraction implementation
• tests/test_message_parsing.cpp - Comprehensive SOC test suite
• README.md - Updated documentation with SOC examples

🎯 Use Case Examples

// Extract complete SOC data from VehicleData
TeslaBLE::SOCData soc_data;
int result = client.extractSOCFromVehicleData(&vehicle_data, &soc_data);

if (result == TeslaBLE::TeslaBLE_Status_E_OK && soc_data.valid) {
    printf("Battery: %d%%, Usable: %d%%, Limit: %d%%\n",
           soc_data.battery_level, soc_data.usable_battery_level, soc_data.charge_limit_soc);
}

This enhancement significantly expands the tesla-ble library's capabilities for battery monitoring and smart charging applications.

🤖 Generated with Claude Code