Neey Balancer Readout with Raspberry Pi

Read out your Neey (Jikong/Heltec) battery balancer directly from a Raspberry Pi via BLE—no ESP32 required

This was my original readme, the other parts are generated by kimi after analyzing the repository:

I was looking for a solution to use my existing raspberry pi to readout a neey balancer over ble without an additional esp32. A perfect starting point was the code of esphome-jk-bms https://github.com/syssi/esphome-jk-bms With the help of 3 differerent AI Tools (Deepwiki, Kimi, Claude) i got a good working solution with very low effort. I asked deepwiki.com „Can you recode to Python“ of the original code https://github.com/syssi/esphome-jk-bms/blob/112f98f7/components/heltec_balancer_ble/heltec_balancer_ble.cpp

https://deepwiki.com/search/can-you-recode-to-python_e17de732-e23e-45e7-a314-dcdbea442055?mode=deep which gave me a working python solution of the original code (deepwiki.py). Now i put this python code in kimi.com prompt the ai tool add MQTT Support, Install-tips as a service i put the kimi generated code parallel in https://claude.ai after some fine tuning both AI-tools delivered good working code I created not a single line of code by hand. I only prompted my requirements to the tools and the error messages of the code which clearly doesnt work perfect at the first time, but after some iterations i had working code tailored to my needs.

🎯 The AI-Assisted Development Journey

This project was built entirely through AI collaboration, demonstrating how modern tools can accelerate hardware interfacing development:

Zero hand-written code—just requirements, error messages, and iteration!

🚀 Features

• ✅ Direct BLE Connection - No ESP32 or additional hardware needed
• ✅ MQTT Integration - Publish data to Home Assistant, Node-RED, or any MQTT broker
• ✅ Systemd Service - Runs automatically on boot
• ✅ Low Resource - Works on Pi Zero 2W, Pi 3, Pi 4
• ✅ Based on Proven Code - Leverages esphome-jk-bms protocol knowledge

📁 Repository Structure

File	Description	Origin
neey_mqtt_kimi.py	Initial MQTT implementation	Kimi AI
neey_mqtt_claude.py	Refined & optimized version	Claude AI
blescan.py	BLE device scanner	Utility
neey-mqtt.service	Systemd service configuration	Kimi AI
README.md	This file	Human + AI

🔧 Requirements

• Raspberry Pi (3, 4, or Zero 2W) with Bluetooth
• Neey/Jikong/Heltec Balancer with BLE support
• Python 3.7+
• MQTT Broker (Mosquitto, Home Assistant, etc.)

📦 Installation

1. Install Dependencies

sudo apt update
sudo apt install python3
pip bluetooth libbluetooth-dev
pip3 install bleak paho-mqtt

2. Find Your Balancer MAC Address

python3 blescan.py

Look for devices named "JK-BMS", "Neey", or "Heltec".

3. Configure

Edit the Python file (either version) and set:

BALANCER_MAC = "XX:XX:XX:XX:XX:XX"  # Your balancer MAC
MQTT_BROKER = "192.168.1.100"        # Your MQTT broker IP
MQTT_PORT = 1883
MQTT_TOPIC = "neey/balancer"

4. Test Run

python3 neey_mqtt_kimi.py or neey_mqtt_claude.py

5. Install as Service

sudo cp neey-mqtt.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable neey-mqtt.service
sudo systemctl start neey-mqtt.service

Check status:

sudo systemctl status neey-mqtt.service

📡 MQTT Topics

Data is published to subtopics under your configured base topic (default: NEEY):

Main JSON Payload

Topic	Description	Format
NEEY/data	Complete device state	JSON object

Individual Sensor Topics (Retained, QoS 1)

Topic	Description	Unit	Example
NEEY/total_voltage	Pack total voltage	V	12.345
NEEY/delta_voltage	Cell voltage difference (max - min)	V	0.025
NEEY/temperature	Temperature sensor 1	°C	25.5
NEEY/balancing	Balancing active status	ON/OFF	ON
NEEY/cell_1/voltage	Cell 1 voltage	V	3.456
NEEY/cell_2/voltage	Cell 2 voltage	V	3.457
...	...	...	...

JSON Payload Structure (NEEY/data)

{
  "timestamp": "2024-01-15T10:30:00",
  "device": {
    "model": "NEEY-4A",
    "hw_version": "1.0", 
    "sw_version": "2.1"
  },
  "battery": {
    "total_voltage": 12.345,
    "average_cell_voltage": 3.456,
    "min_cell_voltage": 3.4,
    "max_cell_voltage": 3.5,
    "delta_voltage": 0.1,
    "cell_count": 4,
    "temperature_1": 25.5,
    "temperature_2": 26.0,
    "balancing": true,
    "status": 5
  },
  "cells": [
    {"cell": 1, "voltage": 3.456, "resistance": 0.5},
    {"cell": 2, "voltage": 3.457, "resistance": 0.51}
  ]
}

🏠 Home Assistant Integration

Add to configuration.yaml:

mqtt:
  sensor:
    - name: "NEEY Total Voltage"
      state_topic: "NEEY/total_voltage"
      unit_of_measurement: "V"
      
    - name: "NEEY Delta Voltage"
      state_topic: "NEEY/delta_voltage"
      unit_of_measurement: "V"
      
    - name: "NEEY Temperature"
      state_topic: "NEEY/temperature"
      unit_of_measurement: "°C"
      
    - name: "NEEY Balancing Status"
      state_topic: "NEEY/balancing"
      
    - name: "NEEY Cell 1 Voltage"
      state_topic: "NEEY/cell_1/voltage"
      unit_of_measurement: "V"

Or use the JSON topic with value templates:

    - name: "NEEY Cell 1 Voltage JSON"
      state_topic: "NEEY/data"
      unit_of_measurement: "V"
      value_template: "{{ value_json.cells[0].voltage }}"

Webserver for testing

Run the server:

python3 neey_webserver.py

Access the Dashboard Open your browser to: http://127.0.0.1:2222

Web Dashboard Preview

How It Works

┌─────────────┐     MQTT      ┌──────────────┐     HTTP     ┌─────────────┐
│   NEEY BMS  │ ────────────> │  Python      │ ───────────> │   Browser   │
│  (GW-24S4EB)│   NEEY/#      │  Bridge      │   /data      │  jQuery UI  │
│             │               │  Port 2222   │   (5s poll)  │             │
└─────────────┘               └──────────────┘              └─────────────┘
        ↑                                                        ↑
   mosquitto_sub                                              127.0.0.1:2222
   localhost:1883

Key Features

• MQTT Subscriber: Connects to localhost:1883, subscribes to NEEY/#
• HTTP Server: Serves dashboard at port 2222 and provides /data endpoint
• Auto-Refresh: Frontend polls every 5 seconds (as requested)
• Connection Indicator: Green dot when MQTT data is flowing
• Thread-Safe: Uses locks to prevent data corruption between MQTT and HTTP threads
• Auto-Reconnect: MQTT client reconnects if broker drops
• No External Files: Single Python file contains everything (embedded HTML)

🛠️ Troubleshooting

Permission Denied for BLE

# Option 1: Run as root (not recommended)
sudo python3 neey_mqtt_claude.py

# Option 2: Grant capabilities (recommended)
sudo setcap cap_net_raw,cap_net_admin+eip $(readlink -f $(which python3))

Connection Drops

The code includes auto-reconnection logic. Check logs:

sudo journalctl -u neey-mqtt.service -f

No Data Received

• Ensure balancer is powered on and in range
• Verify MAC address is correct
• Check that balancer is not connected to another device (app)

🧬 Technical Background

This project translates the ESPHome C++ implementation from esphome-jk-bms to Python using:

1. DeepWiki - Automated C++ to Python transpilation of the protocol parser
2. Kimi - Added MQTT publishing, configuration structure, and systemd integration
3. Claude - Code review, error handling improvements, and optimization The BLE protocol uses notification-based communication on service UUID 0000ff00-0000-1000-8000-00805f9b34fb.

📜 License

MIT License - Feel free to use, modify, and distribute.

🙏 Acknowledgments

syssi/esphome-jk-bms - For the original protocol implementation

DeepWiki, Kimi, and Claude - For making this possible without writing a single line of code manually!

Made with ❤️ and AI assistance