Keba KeContact Python Framework

A Python framework for communicating with Keba KeContact wallbox chargers via UDP.

Overview

This framework enables communication with one or more Keba KeContact P20/P30 wallbox chargers through the UDP protocol. The framework handles the special challenge that all chargers communicate on the same port (7090) by filtering messages based on IP address.

Features

• Asynchronous communication - Built with asyncio for efficient handling
• Multi-charger support - Manage multiple chargers simultaneously with shared UDP handler
• IP-based filtering - Automatic routing of messages to the correct charger
• Typed reports - Structured dataclasses for all report types
• Simple API - Intuitive methods for controlling and monitoring charging

Installation

pip install -e .

For development:

pip install -e ".[dev]"

Quick Test with Interactive Shell

Test the framework interactively using the built-in shell:

python shell.py <charger_ip>

Example:

python shell.py 192.168.1.100

Available commands in the shell:

• r1 - Get Report 1 (product info)
• r2 - Get Report 2 (current state)
• r3 - Get Report 3 (power/energy)
• r100 - Get Report 100 (session info)
• enable / disable - Enable/disable charging
• start / stop - Start/stop charging
• curr 16000 - Set current to 16A (16000mA)
• info - Show all basic information
• help - Show all commands
• quit - Exit shell

Quick Start

Single Charger

import asyncio
from keba_kecontact import KebaClient

async def main():
    async with KebaClient("192.168.1.100") as client:
        # Get product information
        report1 = await client.get_report_1()
        print(f"Serial: {report1.serial}")

        # Get current status
        report2 = await client.get_report_2()
        print(f"State: {report2.state}")

        # Get energy measurements
        report3 = await client.get_report_3()
        print(f"Power: {report3.power_kw} kW")

        # Control charging
        await client.set_current(16000)  # 16A
        await client.enable()

asyncio.run(main())

Multiple Chargers

import asyncio
from keba_kecontact import KebaClient
from keba_kecontact.udp_handler import KebaUdpHandler

async def main():
    # Create shared UDP handler
    handler = KebaUdpHandler()
    await handler.start()

    try:
        # Create clients for each charger
        client1 = KebaClient("192.168.1.100", handler)
        client2 = KebaClient("192.168.1.101", handler)

        await client1.connect()
        await client2.connect()

        # Use clients in parallel
        report1 = await client1.get_report_3()
        report2 = await client2.get_report_3()

        print(f"Charger 1: {report1.power_kw} kW")
        print(f"Charger 2: {report2.power_kw} kW")

        await client1.disconnect()
        await client2.disconnect()
    finally:
        await handler.stop()

asyncio.run(main())

API Reference

KebaClient

Reports

• get_report_1() - Product information and serial number
• get_report_2() - Current state of the charging station
• get_report_3() - Power and energy measurements
• get_report_100() - Session information (RFID)

Control

• enable() - Enable charging station
• disable() - Disable charging station
• set_current(milliamps) - Set current limit in mA
• set_energy(energy) - Set energy limit in 0.1 Wh units
• start_charging() - Start charging session
• stop_charging() - Stop charging session
• display_text(text) - Display text on charger screen

Report Classes

Report1

• product - Product name
• serial - Serial number
• firmware - Firmware version
• com_module - COM module version
• backend - Backend version

Report2

• state - Current state
• plug - Plug connection status
• max_curr - Max current (mA)
• enable_sys - System enabled
• enable_user - User enabled

Report3

• p - Power (mW)
• power_kw - Power in kW
• e_pres - Session energy (0.1 Wh)
• energy_present_kwh - Session energy in kWh
• e_total - Total energy (0.1 Wh)
• energy_total_kwh - Total energy in kWh
• u1, u2, u3 - Voltages phase 1-3
• i1, i2, i3 - Currents phase 1-3

Protocol Details

Keba KeContact uses the UDP protocol:

• Port: 7090 (both send and receive)
• Commands: Plain text without CR/LF
• Responses: JSON format with LF (0x0A) line terminators

Since all chargers use the same port, messages must be filtered based on IP address, which this framework handles automatically.

Home Assistant Usage

This framework is designed to be used as a foundation for Home Assistant integrations. See examples in examples/ for how to implement monitoring and control services.

For detailed integration guide, see HOMEASSISTANT.md.

Examples

See examples/ for more examples:

• basic_usage.py - Basic usage
• multiple_chargers.py - Multiple chargers simultaneously
• control_charging.py - Controlling charging
• home_assistant_pattern.py - Home Assistant integration pattern

License

MIT