Battery Master

This is a web application for managing and tracking lithium-ion cells through various testing stages and then building them into battery packs.

It is a vital tool when building batteries from recycled cells where the individual cell characteristics are varied.

It helps to collect the cell data efficiently and then uses algorithms to calculate and balance the desired battery bank based on the available cell voltage, internal resistance, and capacity.

Features

• Multi-stage Cell Entry: Enter cell data through sequential stages (initial specs, charge voltage, capacity, recharge, 7-day testing)
• Bulk Data Entry: Quick entry of multiple cells with "Save and Next" functionality
• Flexible Editing: Edit individual cells through stages or use bulk edit mode for multiple cells
• Data Persistence: All data saved as JSON files on the server
• Authentication: Cookie-based login for security
• Export/Import: Export all data to JSONL format, import to merge data
• Filtering: Filter cells by testing stage or bank
• Status Tracking: Automatic status updates based on completion stage and battery usage
• Battery Builder: Intelligent pack assembly with balancing and stats

Prerequisites

• Docker and Docker Compose
• Web browser

Why did I make it?

I am building a new lithium battery pack for my e-scooter and I am using second-hand lithium cells. Reclaimed cells offer excellent value for money but they also vary a from one to the next because every cell ages in it's own way.

Battery Builder

When building battery packs with second-hand cells, it is important to combine the cells carefully to ensure the best reliability and longevity of the battery pack.

The battery builder lets you type in the desired series and parallel configuration, then you can select from the available cells and drag/drop them into the series groups to achieve a well-balanced pack.

Features

• Bank Filter: Select bank or all for available cells.
• S/P Configuration: Specify series/parallel count.
• Available Cells: Lists tested, unused cells sorted by capacity desc, IR asc.
• Intelligent Build:
  • Adaptive capacity filter (±1.5σ from mean).
  • IR <80mΩ.
  • Least-loaded greedy assignment to balance series groups by total mWh.
  • Parallel effective IR (harmonic mean).
  • Imbalance % (max-min / min *100), warning if >3%.
• Manual Selection: Checkbox select cells.
• Preview: Group stats, grid layout, pack energy limited by weakest group.
• Save: Marks cells stage=5 "In Battery (name)", saves groups for reload.
• Delete: Frees cells (stage=4), deletes battery.

There is an auto arrange function and an "Intelligent Build" mode too!

Testing procedure and Data Stages

I am using a battery cell tester like this one:

Each cell is already numbered with a unique id. I first test the voltage and internal resistance. These are entered into the form when I click the "Add new" button.

I then charge each cell to full capacity and I click to edit the cell, and I record the voltage of the cell after it has been charged.

I then set the test mode to discharge and I let it run the battery down until it reaches the cutoff voltage. I then click to edit the cell details again and I record: milliamps capacity, milliwatts capacity and the cell voltage at rest after having been fully discharged.

I then recharge the cell to full and again edit the cell to record the voltage after recharge.

I then let the cell rest for 7 days before recording the voltage and Internal Resistance again. This can help to identify faulty cells that would eventually destroy a battery pack.

Those are the five stages of testing and they are labeled as such:

1. New: Initial entry (cell number, voltage, IR)
2. Testing: First charge voltage entered
3. Charging: Capacity data (mAh, mWh, flat voltage) entered
4. On hold: Recharge voltage entered
5. Tested: 7-day voltage and IR entered

Saved batteries listed with summary stats, expandable groups with mini-grid.

Installation & Testing

Installation

1. Clone or download this repository
2. Navigate to the cell-app directory
3. Copy .env.example to .env and set your password: PASSWORD=yourpassword
4. Run docker-compose up --build

The app will be available at http://localhost:3000

Testing (E2E)

1. In .env: Add TEST_PASSWORD=test (same as PASSWORD for simplicity)
2. cd cell-app && docker-compose up --build (in separate terminal)
3. cd cell-app && npm run test:e2e
4. View test-results/html/index.html

Run before commits to catch UI regressions.

First Time Setup

1. Open http://localhost:3000 in your browser
2. You'll be redirected to the login page
3. Enter the password you have defined in .env
4. Click "Login"

Usage

Adding New Cells

1. Click "Add New Cell"
2. Enter cell number, first voltage, and internal resistance
3. Click "Save and Next" to add another cell, or "Save" to finish

Editing Cells

Individual Edit

• Click on any cell in the list to open the edit form
• Navigate through stages using "Save" (next stage) or "Save and Next" (next cell)

Bulk Edit

1. Click "Enter Edit Mode"
2. Check the boxes next to cells you want to edit
3. Click "Edit Selected Cells"
4. Edit through stages; "Save and Next" moves to the next selected cell

Viewing Details

• Click "View Details" on any cell to see all specifications
• Use the stage filter dropdown to show only cells in specific stages

Exporting Data

• Click "Export JSONL" to download all cell data in JSON Lines format

Importing Data

1. Click "Choose File" next to "Import JSONL"
2. Select a .jsonl file
3. Click "Import JSONL"
4. Data will be merged with existing cells

Direct JSON Editing

• Click "Edit JSON" on any cell for direct JSON editing (for corrections)

Battery Builder

See dedicated section above.

File Structure

• data/: JSON files for each cell and batteries/ subdirectory
• public/: Web assets (HTML, CSS, JS)
• server.js: Node.js Express server
• Dockerfile: Docker container configuration

Troubleshooting

• If login fails, ensure you're using the correct password
• For import/export issues, check browser console for errors
• Data is persisted in the data directory within the Docker container
• Battery cells not hiding: check stage=5 and usedInBattery in cell JSON

Security

• Uses cookie-based authentication
• All data stored locally in JSON files
• No external data transmission

Support

No support is offered for this product. You can modify your own copy of it or get someone else to do it for you.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Author: Anthony Gallon, Owner/Licensor: AntzCode Ltd https://www.antzcode.com, Contact: https://github.com/AntzCode