Leaflet HEMS Integration for Home Assistant

Consolinno Energy GmbH — Integration "Leaflet HEMS"

This integration connects Home Assistant to Consolinno Leaflet HEMS (Heim Energie Management System) devices, which are based on the nymea framework. It allows you to monitor energy data such as grid consumption, PV generation, battery status, and more.

Features

• Automatic Discovery: Uses mDNS/Zeroconf to automatically discover Leaflet HEMS devices on your network via the _jsonrpc._tcp.local. service type.
• Easy Setup: Simple username and password authentication for discovered devices.
• Secure Connection: Connects to the nymea device using TLS/JSON-RPC on port 2222.
• Device Validation: Validates discovered devices to ensure they are genuine nymea-based Leaflet HEMS devices.
• Device Information: Displays device name, UUID, and version.
• Comprehensive Sensor Integration: Automatically creates sensors for all available energy management components:
  • Grid Connection Meter (Root Meter): Grid consumption and feed-in
  • Inverters: PV generation and performance
  • Batteries: Charge level, power flow, and status
  • Additional energy management devices as available

Installation

Using HACS (Recommended)

1. Open HACS in your Home Assistant instance.
2. Go to the "Integrations" tab.
3. Click the "+ EXPLORE & ADD ADD-ONS" button.
4. Search for "Leaflet HEMS".
5. Select the integration and click "Download".
6. Restart Home Assistant.

Manual Installation

1. Navigate to the custom_components directory of your Home Assistant installation.
2. If the custom_components directory does not exist, create it.
3. Download this repository or extract its contents into a leaflet_hems subdirectory within custom_components. Your final directory structure should look like this:

   your_home_assistant_config/
   ├── custom_components/
   │   └── leaflet_hems/
   │       ├── __init__.py
   │       ├── config_flow.py
   │       ├── const.py
   │       ├── manifest.json
   │       └── ... (other files)
   ├── tests/
   └── ...
   

4. Restart Home Assistant.

Configuration

Automatic Discovery Setup

1. In the Home Assistant UI, go to "Settings" > "Devices & Services".
2. Click the "+ Add Integration" button in the bottom right corner.
3. Search for "Leaflet HEMS" and select it.
4. The integration will automatically scan your network and display any discovered Leaflet HEMS devices.
5. Select your device from the list and click "Submit".
6. Enter your username and password when prompted.
7. Once authenticated, the integration will automatically initialize all available sensors for your energy management system.

Manual Setup (Alternative)

If your device is not found via automatic discovery, you can add it manually:

1. Follow steps 1-3 above.
2. Instead of selecting from discovered devices, choose "Configure manually".
3. Enter the device's IP address and port (default: 2222).
4. Provide your username and password when prompted.

Device Management

• Added devices will appear under "Settings" > "Devices & Services".
• Each device will be registered with its unique UUID.
• You can remove or reconfigure a device by clicking on it in the device list and selecting "Configure" or "Delete".

Entities

After successful setup, the integration automatically creates sensors for all available energy management components in your Leaflet HEMS system. The specific entities created depend on your system configuration and the devices connected to your nymea instance.

Automatically Created Sensors:

• Grid Connection Meter (Root Meter)

  • Grid Consumption (Netzbezug) - Power being drawn from the grid
  • Grid Feed-in (Netzeinspeisung) - Power being fed into the grid
  • Grid-related energy metrics and statistics

• Inverters

  • PV Generation (PV-Erzeugung) - Power currently being generated by PV modules
  • Inverter performance metrics and statistics

• Batteries

  • Battery Charge Level (Batterieladung) - State of charge of the battery
  • Battery Power (Batterieleistung) - Current power flow (charging/discharging)
  • Battery status and health metrics

• Additional Devices

  • Other energy management devices as available in your system

All sensors are automatically initialized and updated in real-time as data becomes available from your Leaflet HEMS device.

Troubleshooting

Integration Fails to Add

• "Cannot connect": Ensure the Leaflet HEMS device is powered on, connected to your network, and the nymea service is running on port 2222. Check your firewall settings.
• "No devices found" during discovery: Ensure mDNS is enabled on your network and the Leaflet HEMS device is advertising the _nymea._tcp.local service. Try the manual setup option.
• "Cannot get UUID": This usually happens during manual setup if the handshake fails. Ensure the IP address and port are correct, and the device is accessible.

Entities Not Appearing

• If sensors are not appearing after successful setup, ensure your Leaflet HEMS device has connected energy management components (grid meter, inverters, batteries).
• Check that your device credentials are correct and the integration can successfully authenticate.
• Verify that your Leaflet HEMS device is online and communicating properly with its connected components.
• Check the Home Assistant logs for any error messages related to sensor initialization.

Logs

• Check the Home Assistant logs for detailed error messages. You can enable debug logging for the leaflet_hems integration in the Home Assistant configuration (logger section) to get more detailed information:

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

Requirements

• A working Home Assistant instance (2025.10.2 or newer).
• A Consolinno Leaflet HEMS device with nymea framework.
• Network access to the Leaflet HEMS device on port 2222 (TCP).
• Python dependencies: zeroconf, aiohttp, cryptography. These are usually handled by HACS or Home Assistant's dependency management.

Development

This integration is stable and actively maintained. The core functionality includes:

• Automatic Device Discovery: Seamless network discovery of Leaflet HEMS devices
• Authentication: Secure username/password authentication
• Real-time Data Fetching: Continuous polling of energy data from nymea devices
• Sensor Creation: Automatic creation of sensors for grid meters, inverters, and batteries
• Device Management: Full device lifecycle management in Home Assistant

Running Tests

Host Machine Tests

To run the unit tests for this integration on your host machine, you'll need Python and the development dependencies installed:

1. Install dependencies: pip install -r requirements.txt
2. Run tests: pytest tests/

Docker Environment for Testing

You can use Docker to run Home Assistant with the leaflet_hems integration for end-to-end testing.

Prerequisites:

• Docker installed and running.
• Docker Compose installed and running.

Setup:

1. Build and Start:

   • Open a terminal in the root directory of this project (ha-leaflet-hems).
   • Build the custom Home Assistant image: make build
   • Start the Home Assistant instance: make up

   The Home Assistant instance will be available at http://localhost:8123. The initial setup may take a few minutes. You can monitor the logs with make logs.

2. Configuration in Home Assistant UI:

   • Once Home Assistant is running, open http://localhost:8123.
   • Go to "Settings" > "Devices & Services".
   • Click "+ Add Integration".
   • Search for "Leaflet HEMS".
   • Follow the on-screen instructions to add your device (either via discovery or manually).

3. Hot-Reloading During Development:

   • The docker-compose.override.yml is set up to mount the custom_components directory from your host machine into the container. This means changes you make to the integration's Python files in custom_components/leaflet_hems/ on your host should be immediately reflected in the running Docker container.
   • After making changes, Home Assistant might need to be reloaded. You can do this by:
     • Going to "Developer Tools" > "YAML Configuration" > "Reload" in the Home Assistant UI.
     • Or, restarting the Home Assistant service from the UI or via make down && make up (for more significant changes).

Common Docker Commands (using Makefile):

• make build: Build the Docker image.
• make up: Start the container.
• make down: Stop the container.
• make logs: View container logs.
• make clean: Stop, remove containers, and prune volumes (resets Home Assistant config).
• make rebuild: Full rebuild and start.
• make fresh: Stop, prune, build, and start (clean slate).
• make test_config_flow: Run config flow tests from the host.
• make shell: Get a shell inside the running container for debugging.

Note on Docker Tests: The test_integration and test_config_flow targets in the Makefile are primarily for running tests from your host machine against the Home Assistant instance (if tests were designed that way). Running tests inside the Docker container (e.g., docker exec home_assistant python -m pytest /tests/) is also possible but might require adjustments to how pytest-hass or other test discovery mechanisms work, especially if they rely on Home Assistant's internal APIs being fully operational. For now, host-based pytest is the primary method.

Contributing

If you have suggestions or encounter bugs, please open an issue on the GitHub repository.

License

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

---

Disclaimer: This is an unofficial integration. Use at your own risk. The author is not responsible for any damage caused by the use of this integration.