ocpp2mqtt

ocpp2mqtt is a gateway software that converts OCPP (Open Charge Point Protocol) requests to MQTT (Message Queuing Telemetry Transport) and vice versa. This enables seamless integration of EV charging stations with any home automation system.

✨ Features

• 🔌 Converts OCPP 1.6 requests to MQTT and vice versa
• 🏠 Easy integration with home automation systems (Home Assistant, OpenHAB, etc.)
• 🐳 Docker and Kubernetes support for flexible deployment
• 📝 Configurable logging with file rotation support
• 🔄 Automatic MQTT reconnection with exponential backoff
• 🔐 MQTT authentication support
• 🌐 WebSocket transport support for MQTT
• 📡 Real-time charger connection state monitoring via MQTT
• ⚡ Automatic disconnection detection with reason tracking

📋 Table of Contents

• Prerequisites
• Installation
• Configuration
• Usage
• MQTT Topics
• Logging
• Integration Guides
• Contributing
• License

📦 Prerequisites

• Python 3.8 or higher
• MQTT Broker (Mosquitto, HiveMQ, etc.)
• Docker/Kubernetes (optional)

🚀 Installation

Option 1: Python (Direct)

# Clone the repository
git clone https://github.com/gyzod/ocpp2mqtt.git
cd ocpp2mqtt

# Install dependencies
pip install -r requirements.txt

# Run the application
python central_system.py

Option 2: Docker

# Build the image
docker build -t ocpp2mqtt .

# Run the container
docker run -d \
  --name ocpp2mqtt \
  -p 3000:3000 \
  -e MQTT_HOSTNAME=your-mqtt-broker \
  -e MQTT_BASEPATH=ocpp/ \
  -e MQTT_USESTATIONNAME=true \
  ocpp2mqtt

Option 3: Docker Compose

version: '3.8'
services:
  ocpp2mqtt:
    build: .
    ports:
      - "3000:3000"
    environment:
      - MQTT_HOSTNAME=mqtt-broker
      - MQTT_BASEPATH=ocpp/
      - MQTT_USESTATIONNAME=true
      - AUTHORIZED_TAG_ID_LIST=["tag1","tag2"]
    restart: unless-stopped

Option 4: Kubernetes

See Kubernetes Deployment Guide for detailed instructions.

⚙️ Configuration

Create a .env file or set environment variables:

MQTT Configuration

Server Configuration

OCPP Command Retry Configuration

Logging Configuration

Example .env file

# MQTT Configuration
MQTT_HOSTNAME=192.168.1.100
MQTT_PORT=1883
MQTT_BASEPATH=ocpp/
MQTT_USESTATIONNAME=true
MQTT_USERNAME=
MQTT_PASSWORD=

# Server Configuration
LISTEN_PORT=3000
LISTEN_ADDR=0.0.0.0
AUTHORIZED_TAG_ID_LIST=["johnny-car","other-car"]
EXPECTED_CHARGE_POINTS=["charger1","charger2"]

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=/var/log/ocpp2mqtt/app.log
LOG_MAX_SIZE=10485760
LOG_BACKUP_COUNT=5

🔧 Usage

Starting the Server

python central_system.py

The server will start listening for OCPP connections on the configured address and port. When a charge point connects, it will automatically bridge communications to MQTT.

Charge Point Connection

Configure your OCPP charge point to connect to:

ws://<server-ip>:<port>/<station-id>

Example: ws://192.168.1.10:3000/charger1

📡 MQTT Topics

State Topics (Charger → MQTT)

All charger data is published to: <MQTT_BASEPATH>/<station-id>/state/<parameter>

Connection State Topics

These topics track the WebSocket connection between the charger and ocpp2mqtt:

Note: If EXPECTED_CHARGE_POINTS is configured, the service publishes DISCONNECTED state for each expected charger on startup, before any charger connects.

Charger Data Topics

Disconnect Reasons

When a charger disconnects, the disconnect_reason topic indicates why:

Note: When a charger disconnects, power_active_import and current_import are automatically reset to 0.

Command Topics (MQTT → Charger)

Send commands to: <MQTT_BASEPATH>/<station-id>/cmd

Message Schema

{
    "action": "<operation_name>",
    "args": { <ocpp_payload> }
}

Available Commands

Change Availability

{
    "action": "change_availability",
    "args": {
        "connector_id": 1,
        "type": "Operative"
    }
}

Remote Start Transaction

{
    "action": "remote_start_transaction",
    "args": {
        "connector_id": 1,
        "id_tag": "your-rfid-tag"
    }
}

Remote Stop Transaction

{
    "action": "remote_stop_transaction",
    "args": {
        "transaction_id": 1
    }
}

Reset

{
    "action": "reset",
    "args": {
        "type": "Soft"
    }
}

Unlock Connector

{
    "action": "unlock_connector",
    "args": {
        "connector_id": 1
    }
}

Command Result

Command results are published to: <MQTT_BASEPATH>/<station-id>/cmd_result/status

Connection Monitoring

ocpp2mqtt automatically monitors the WebSocket connection with each charger and publishes state changes to MQTT. This enables your home automation system to:

• Detect offline chargers - Trigger alerts when a charger goes offline
• Track availability - Know when chargers are available for use
• Monitor network issues - Identify connection problems with specific chargers
• Automate recovery - Trigger actions when a charger reconnects

Example: Home Assistant Binary Sensor

mqtt:
  binary_sensor:
    - name: "Charger Connection"
      state_topic: "ocpp/charger1/state/connection_state"
      payload_on: "CONNECTED"
      payload_off: "DISCONNECTED"
      device_class: connectivity

Example: Home Assistant Automation (Alert on Disconnect)

automation:
  - alias: "Charger Disconnected Alert"
    trigger:
      - platform: mqtt
        topic: "ocpp/charger1/state/connection_state"
        payload: "DISCONNECTED"
    action:
      - service: notify.mobile_app
        data:
          title: "⚠️ Charger Offline"
          message: "Your EV charger has disconnected"

📝 Logging

ocpp2mqtt supports flexible logging configuration with both console and file output.

Console Only (Default)

By default, logs are only output to the console:

LOG_LEVEL=INFO python central_system.py

File Logging

Enable file logging by setting LOG_FILE:

LOG_FILE=/var/log/ocpp2mqtt/app.log python central_system.py

Log Rotation

When file logging is enabled, logs are automatically rotated:

• Maximum file size: LOG_MAX_SIZE (default: 10MB)
• Backup files kept: LOG_BACKUP_COUNT (default: 5)

Docker with File Logging

docker run -d \
  --name ocpp2mqtt \
  -p 3000:3000 \
  -e MQTT_HOSTNAME=broker \
  -e LOG_FILE=/var/log/ocpp2mqtt/app.log \
  -v /path/to/logs:/var/log/ocpp2mqtt \
  ocpp2mqtt

📚 Integration Guides

Detailed integration guides are available for popular home automation platforms:

• Home Assistant - MQTT sensors, automations, and energy dashboard integration
• OpenHAB - Things, Items, Rules, and Sitemap configuration
• Kubernetes - Deployment, ConfigMaps, Secrets, and Ingress setup

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Running Tests

pytest tests/ -v

📄 License

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

🙏 Acknowledgements

• Thanks to the open-source community for their contributions
• Special thanks to the developers of the OCPP and aiomqtt libraries
• Based on initial work from ocpp-mqtt