Collector: battery cyclers and HDF5

Battery cyclers and HDF5

Battery cyclers write their own file formats, and most labs already export CSV or Excel from the cycler software. The file watcher (type: files) reads the native files of the common cyclers directly, so the folder the cycler writes to can be watched as it is. Every row keeps its own absolute time stamp: the cycler's test start time plus the elapsed time, or the time stamp the cycler records. Each file is read once, then moved to done; a file that cannot be read is moved to failed with the reason next to it.

Which cycler files are read

pip install "kymoscope-collector[cyclers]"   # Neware, Arbin Excel and Arbin .res (pyodbc on Windows)
pip install "kymoscope-collector[hdf5]"      # HDF5

Configuration

sources:
  - name: Cell lab
    type: files
    path: D:/cycler/export          # the folder the cycler software (or you) drops files in
    format: biologic                # or neware, arbin, maccor, basytec, digatron, hdf5 (see format below)
    timezone: Europe/Madrid         # the cycler PC's zone, for files with zone-less times
    min_age_s: 600                  # longer than the logging interval if the folder holds runs still being written

  - name: Maccor exports
    type: files
    path: D:/maccor
    pattern: "*.txt"                # .txt is only picked up by default when format is set
    format: maccor

  - name: Test bench (HDF5)
    type: files
    path: D:/bench
    format: hdf5
    hdf5_group: /run                # every 1-D numeric dataset of the same length as the time dataset
    hdf5_time: time
    start_time: 2026-10-23T10:00:00 # only when the time is relative and the file has no start attribute

Channels, units and step types

Channels are named alike for every cycler, in the units a battery engineer expects, so the same dashboard works for all of them: Voltage (V), Current (A), Capacity, Charge capacity and Discharge capacity (Ah), Energy, Charge energy and Discharge energy (Wh), Temperature or Temperature 1 (°C), Cycle and Step (numbers). Values in mA, mAh, mV or hours are converted. Other numeric columns keep their own name and unit. The step type of Neware (Step type: CC_Chg, CV_Chg, Rest…), Maccor (the State column: Charge, Discharge, Rest, Special) and BioLogic (Mode: CC, CV, Rest; Oxidation) is a channel with labels, shown by name.

HDF5 files

HDF5 (.h5, .hdf5) is common in test benches and research software. There is no standard layout, so the mapping is configurable. Needs the hdf5 extra (h5py, BSD licence). The file is read in chunks, so large files are fine.

A time dataset whose first value (in its unit) is above 10⁸ is taken as absolute Unix time; otherwise it is elapsed time from the start. When the dataset has no unit and hdf5_time_unit is not set, an absolute time is read as nanoseconds above 10¹⁷, microseconds above 10¹⁴, milliseconds above 10¹¹, else seconds. Channels take their unit from a units or unit attribute, and are named after their dataset.

import h5py, numpy as np
with h5py.File("run.h5", "w") as f:
    g = f.create_group("run")
    t = g.create_dataset("time", data=np.arange(0, 600, 0.1))   # seconds since the start
    t.attrs["units"] = "s"
    g.attrs["start_time"] = "2026-10-23T10:00:00Z"              # or set start_time in collector.yaml
    g.create_dataset("voltage", data=...).attrs["units"] = "V"
    g.create_dataset("current", data=...).attrs["units"] = "A"

Files still being written

EC-Lab (.mpr), MITS Pro (.res) and Neware software write to their file for the whole test, and may pause longer than min_age_s between records. A file read in such a pause is read only up to that point and is not read again. Watch a folder of finished files (copy or export each test there when it ends), or set min_age_s above the longest logging interval. Unless you set it, cycler files wait 120 seconds.

What has been checked

If something does not read