⚠️ EXPERIMENTAL INTEGRATION - USE AT YOUR OWN RISK

This is an unofficial custom integration for HomeAssistant to monitor Sunlit Solar systems. This integration is not affiliated with, endorsed by, or supported by Sunlit.

No warranty or support is provided. Use of this integration is entirely at your own risk.

This custom integration connects HomeAssistant to the Sunlit Solar API, enabling real-time monitoring of your solar installation including solar panels, inverters, batteries, and energy meters. It provides comprehensive sensor data for monitoring energy production, consumption, and battery status.

• 📊 Monitoring - Updates every 30 seconds
• 🏠 Family/Space Aggregation - Combined metrics across all devices
• 🔌 Device-Specific Sensors - Individual monitoring for each component
• 🔋 Battery Management - SOC limits, strategies, and status tracking
• ⚡ Energy Dashboard Ready - Compatible with HA Energy Dashboard
• 🚨 Fault Detection - Binary sensors for system health monitoring
• 📈 Strategy History - Track battery charging strategy changes

• HomeAssistant 2025.1.0 or newer
• Sunlit Solar Bearer API key (obtain from your Sunlit Solar account)
• Active internet connection for API access

1. Open HACS in your Home Assistant instance
2. Click on Integrations
3. Click the three dots menu in the top right corner and select Custom repositories
4. Add this repository URL: https://github.com/cedricziel/ha-sunlit
5. Select Integration as the category
6. Click Add
7. Search for "Sunlit Solar" in HACS
8. Click Download and select the latest version
9. Restart Home Assistant
10. Add the integration through the UI: Settings → Devices & Services → Add Integration → Search for "Sunlit"

1. Download or clone this repository
2. Copy the custom_components/sunlit folder to your HomeAssistant configuration directory:

   <config_dir>/custom_components/sunlit/
   

3. Restart HomeAssistant
4. Add the integration through the UI: Settings → Devices & Services → Add Integration → Search for "Sunlit"

custom_components/
└── sunlit/
    ├── __init__.py
    ├── api_client.py
    ├── binary_sensor.py
    ├── config_flow.py
    ├── const.py
    ├── manifest.json
    ├── sensor.py
    └── strings.json

1. Navigate to Settings → Devices & Services
2. Click Add Integration and search for "Sunlit"
3. Enter your API key when prompted
4. Select the families/spaces you want to monitor
5. Click Submit

The integration will create devices and sensors automatically based on your Sunlit Solar system configuration.

For modular battery systems with B215 extension modules, each additional battery module (1-3) appears as a separate virtual device with:

To integrate with HomeAssistant's Energy Dashboard:

1. Go to Settings → Dashboards → Energy
2. Under Solar Panels, click Add Solar Production
3. Select sensor: sensor.inverter_[ID]_total_power_generation

1. Under Grid, click Add Consumption
2. Select sensor: sensor.meter_[ID]_total_buy_energy

1. Under Grid, click Add Return
2. Select sensor: sensor.meter_[ID]_total_ret_energy

Since the integration provides power sensors but not energy sensors for batteries:

1. Create a helper: Settings → Devices & Services → Helpers → Create Helper → Integration - Riemann sum
2. Configure:
   • Name: "Battery Energy Input"
   • Input sensor: sensor.battery_[ID]_input_power_total
   • Integration method: Trapezoidal
   • Metric prefix: k (kilo)
   • Time unit: Hours
3. Repeat for output power
4. Add these helpers to Energy Dashboard under Battery Storage

All entities follow a consistent naming pattern to ensure uniqueness across multiple families and devices:

Pattern: sensor.sunlit_{family_id}_{sensor_key} Example: sensor.sunlit_12345_battery_level

Pattern: sensor.sunlit_{family_id}_{device_type}_{device_id}_{sensor_key} Example: sensor.sunlit_12345_battery_456_input_power_total

Pattern: sensor.sunlit_{family_id}_battery_{device_id}_module{N}_{sensor_key} Example: sensor.sunlit_12345_battery_456_module1_soc

The integration creates a hierarchical device structure:

1. Family Hub - Virtual device representing the entire solar system

   • Contains aggregate sensors and system-wide metrics
   • All physical devices are linked to this hub

2. Physical Devices - Actual hardware components

   • Smart meters (SHELLY_3EM_METER)
   • Inverters (YUNENG_MICRO_INVERTER)
   • Battery units (ENERGY_STORAGE_BATTERY)

3. Virtual Devices - Logical representations for better organization

   • Battery modules (1-3) for modular battery systems
   • Each module appears as a separate device linked to the main battery unit
   • Prevents sensor overload on single devices (30+ sensors)

For battery systems with expansion modules:

• Main Unit (BK215): Contains system-wide sensors and dual MPPT inputs
• B215 Module 1-3: Additional battery packs (2.15 kWh each) with individual MPPT solar inputs
• Each module tracks its own SOC and solar production independently
• Virtual devices ensure clean organization in HomeAssistant UI

• No Dynamic Device Discovery: New devices added to your Sunlit system require a HomeAssistant restart to appear
• No Historical Data: The integration cannot backfill historical data from before it was installed
• API Rate Limits: The 30-second update interval is fixed to avoid API rate limiting
• Read-Only: All sensors are read-only; device control is not supported

Add to your configuration.yaml:

logger:
  default: info
  logs:
    custom_components.sunlit: debug

Sensors showing "unavailable"

• Check your internet connection
• Verify API key is correct
• Ensure devices are online in Sunlit Solar app

Missing devices after adding new hardware

• Restart HomeAssistant to discover new devices
• Check if devices appear in Sunlit Solar app first

Energy Dashboard not showing data

• Ensure sensors have state_class: total_increasing (check Developer Tools)
• Wait for at least one update cycle (30 seconds)
• Verify units are in kWh for energy sensors

# Clone the repository
git clone https://github.com/cedricziel/ha-sunlit.git
cd ha-sunlit

# Install dependencies
make setup

# Format code
make format

# Run linters (without making changes)
make lint

# Clean up cache files
make clean

# Show all available commands
make help

# Start HomeAssistant in development mode
hass -c config

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

This integration is provided "as is" without warranty of any kind. The authors and contributors are not responsible for any damages or losses that may result from using this integration.

This is an experimental, unofficial integration that:

• May stop working if Sunlit Solar changes their API
• Could potentially impact your Sunlit Solar warranty (check your terms)
• Is not endorsed or supported by Sunlit Solar GmbH
• May contain bugs that could affect your HomeAssistant installation

Use at your own risk and always maintain backups of your HomeAssistant configuration.

This project is licensed under the MIT License - see the LICENSE file for details.

This is a community project with no official support. For issues and questions:

• Check existing GitHub Issues
• Open a new issue with detailed information about your problem
• Join HomeAssistant community forums for general help

Remember: This is an experimental integration maintained by volunteers in their spare time.