A TypeScript library for communicating with Hame battery devices via Bluetooth Low Energy (BLE). Primary support for the B2500 model.
👉 Try the live demo — connect to your B2500 straight from the browser, no install or account needed (requires a Web Bluetooth capable browser).
🔋 The Marstek ecosystem. This repo is part of a family of open-source tools for Marstek batteries (B2500, Venus, Jupiter, …):
| Project | What it does |
|---|---|
| hm2mqtt | Brings your battery into your smart home, turning its raw data into readable sensors and controls (e.g. in Home Assistant) |
| hame-relay | Connects the official Marstek cloud/app and your local smart home so both work together, forwarding data whichever way your battery is set up |
| marsrelay | Runs your battery completely offline, with no internet or Marstek cloud, while still sending all its data to your smart home |
| AstraMeter | Tells your battery your live grid usage (read from your existing meter) so it charges and discharges to avoid buying or selling power |
| hmjs (this repo) | Sets up and configures B2500 batteries over Bluetooth, right from your web browser, with no app or account needed |
| esphome-b2500 | Continuously monitors and controls a B2500 over Bluetooth using a small ESP32 board |
HMJS provides a simple interface for connecting to and monitoring Hame battery management systems through the Web Bluetooth API. The library includes device information retrieval, real-time monitoring, and configuration capabilities.
@tomquist/hmjs-protocol- Core protocol implementation for HM device communication@tomquist/hmjs-ble- BLE transport layer using Web Bluetooth APIdemo- React web application demonstrating library usage
This project uses GitHub Packages for distribution. To install the published packages:
# One-time setup: Configure npm to use GitHub Packages for @tomquist scope
echo "@tomquist:registry=https://npm.pkg.github.com" >> ~/.npmrc
# Install the packages
npm install @tomquist/hmjs-bleFor development:
# Clone and install dependencies
git clone https://github.com/yourusername/hmjs.git
cd hmjs
npm installThe demo is deployed to GitHub Pages at https://tomquist.github.io/hmjs/ — open it in Chrome, Edge or Opera to use it without building anything.
To run it locally:
npm startOpen your browser to the provided URL and use the demo interface to:
- Scan and connect to HM devices
- View device information and real-time data
- Monitor cell voltages and temperatures
- Read and edit the manual-mode timer schedule
- Configure device settings
import { BLEDeviceManager } from '@tomquist/hmjs-ble';
const manager = new BLEDeviceManager();
// Connect to a device
await manager.scanAndConnect();
// Listen for runtime data
manager.on('runtimeInfo', (data) => {
console.log('Battery SOC:', data.soc);
console.log('Power:', data.in1Power + data.in2Power);
});The device stores a fixed number of manual-mode timer slots (3 on firmware < 218, 5 otherwise) and rewrites all of them from a single command. Read the current schedule first, change the slots you care about and write the complete set back:
const schedule = await manager.getTimers();
const timers = schedule.timers.map((timer) => ({ ...timer }));
timers[0] = {
enabled: true,
start: { hour: 8, minute: 0 },
end: { hour: 17, minute: 0 },
outputPower: 500,
};
await manager.setTimers(timers);Note: every
setTimerscall is persisted to the device's flash memory, which only tolerates a limited number of write cycles. Do not use the timers to build a zero feed-in automation.
# Build all packages
npm run build
# Run tests
npm test
# Lint code
npm run lintRequires a browser with Web Bluetooth API support (Chrome, Edge, Opera on desktop; limited mobile support).
MIT