open-battery-information-web/README.md

# Open Battery Information — Web

A web version of the [open-battery-information](https://github.com/mnh-jansson/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](https://github.com/mnh-jansson/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`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/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](https://github.com/mnh-jansson/open-battery-information/releases) 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://`):

```sh
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`](https://serialport.io) 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:

```sh
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:

```sh
cd desktop
npm install
npm start
```

Installers for tagged releases are built automatically in CI and attached to
GitHub releases — see the [Download](download.html) 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](https://github.com/mnh-jansson/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`.