DIY/open-battery-information-web
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
main
open-battery-information-web/README.md
T
liver d719b34e03 Initial commit
2026-08-19 21:35:27 +03:00

7.8 KiB
Raw Permalink Blame History

Open Battery Information — Web

A web version of the open-battery-information project, hostable entirely on GitHub Pages. It provides:

  1. Landing page (index.html) — the project front page: what it does, requirements, how to get started, and links to the two tools.
  2. OBI-1 (obi.html) — a browser port of the desktop Tkinter app: the Makita LXT module with the Arduino OBI interface, talking to the Arduino over the Web Serial API.
  3. Firmware Uploader (firmware/uploader.html) — flashes the Open Battery Information firmware to an Arduino Uno straight from the browser, using AVRDUDE compiled to WebAssembly + Web Serial.

The Arduino firmware is built by the original repository (open-battery-information) and attached to its GitHub releases. This site simply fetches the latest binaries — no local toolchain needed.

Usage

Requirements

  • Chrome or Edge on desktop (or any Chromium-based browser).
  • HTTPS or localhost (Web Serial and SharedArrayBuffer both require a secure context). GitHub Pages provides HTTPS automatically.
  • A USB-connected Arduino Uno with the optiboot bootloader.

Flashing the firmware

Open firmware/uploader.html:

  1. Board — pick your board. Arduino Uno (default) or ESP32-C3 (SuperMini).
  2. Flash — plug the board into USB and click Flash firmware; choose the port when prompted.
    • Arduino boards: AVRDUDE resets the board into its bootloader (1200 baud DTR trick), uploads and verifies the flash.
    • ESP32-C3: esptool drives RTS/DTR to enter the ROM bootloader and flashes a merged image (bootloader + partitions + app) at offset 0x0. When it finishes, the board reboots into the OBI firmware.

Note: both flashers talk to the bootloader at 115200 baud. The OBI firmware itself runs at 9600 baud and is used by OBI-1 tool.

Using OBI-1 tool

Open obi.html:

  1. Connect — click Connect and pick the serial port of the Arduino (or ESP32-C3) running the OBI firmware (9600 baud, with an automatic board reset on connect).
  2. Read battery — insert a battery and press Read battery. The model, cell voltages, temperatures, charge count and status are read in one go. LED tests and error reset work on supported batteries.

Warning: This tool talks to battery BMS hardware. Use at your own risk — see the upstream project's documentation and the MIT license.

How it works

  • js/ — OBI-1 tool: a port of the Python OpenBatteryInformation app (module + interface architecture), wrapped in a guided 3-step wizard (connect → read → results). common.js provides a SerialConnection wrapper around the Web Serial API with a background read loop.
  • firmware/avrdude.js + avrdude.wasm + avrdude.conf — AVRDUDE compiled to WebAssembly, vendored from the @leaphy-robotics/avrdude-webassembly package (a fork of avrdude). The serial layer in avrdude.js was rewritten to talk to the port directly over Web Serial on the main thread (no worker, no SharedArrayBuffer), and performs the Arduino 1200 baud DTR reset, so the actual port is picked with navigator.serial rather than -P.
  • firmware/uno.hex — the compiled ArduinoOBI firmware for the Uno, fetched from the latest upstream GitHub release by the firmware.yml workflow.
  • firmware/esp32.bin — a merged ESP32-C3 image (bootloader + partitions + app), built upstream from the esp32-c3-devkitm-1 PlatformIO env and fetched the same way.
  • firmware/esptool.js — Espressif's official esptool-js (Apache-2.0) for flashing ESP32 chips over Web Serial; loaded on demand by the uploader.

Continuous integration

Workflow What it does
firmware.yml Downloads uno.hex + esp32.bin from the latest upstream release and commits them to firmware/. Runs on a schedule and manually via Actions.
pages.yml Deploys the static site (index.html, obi.html, setup.html, download.html, css, js, firmware, assets) to GitHub Pages via actions/deploy-pages.
packaging.yml Builds the desktop app (Electron) for Windows, macOS and Linux and attaches the installers to a GitHub release. Runs on a v* tag push or manually via Actions.

To set up GitHub Pages on your fork: go to Settings → Pages → Source: GitHub Actions.

Local development

Serve the directory over HTTP (ES modules require a server, not file://):

python3 -m http.server 8000

Then open http://localhost:8000 in Chrome/Edge. localhost counts as a secure context, so Web Serial works without HTTPS.

Desktop app

The OBI-1 page is also packaged as a self-contained Electron app for Windows, macOS and Linux. The bundle contains only the OBI-1 page (no landing page, no firmware uploader), and serial access uses the native serialport package in the main process instead of the browser Web Serial API — the renderer reaches it over IPC through a navigator.serial shim, so the OBI code itself is unchanged.

Everything lives in desktop/:

  • main.js — Electron main process; loads site/obi.html and owns the serial ports (serialport), including a small serial-port picker dialog.
  • preload.js / preload-picker.js — IPC bridges (context-isolated).
  • serial-shim.js — renderer-side navigator.serial implementation backed by the native serial ports.
  • scripts/prepare-site.mjs — builds desktop/site/ from the repo's obi.html (trims the nav to the theme toggle, injects the serial shim) and copies only the assets that page uses.
  • electron-builder.yml — build config (Windows NSIS, macOS DMG + zip, Linux AppImage + deb).

Build installers locally:

cd desktop
npm install
npm run dist              # current platform
npm run dist:win          # Windows installer
npm run dist:mac          # macOS DMG + zip
npm run dist:linux        # Linux AppImage + deb

Run from source without packaging:

cd desktop
npm install
npm start

Installers for tagged releases are built automatically in CI and attached to GitHub releases — see the Download page. The macOS build is not notarized; right-click → Open on first launch.

License

The web app is released under the GPL-3.0 license. It is a port of the open-battery-information project, which is MIT licensed and is included here under its original terms:

Copyright (c) 2024 Martin Jansson

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

AVRDUDE is also GPL — see firmware/AVRDUDE-COPYING.

Reference in New Issue View Git Blame Copy Permalink