crop_vbat.awk reads numeric voltage samples from standard input or files and extracts battery discharge intervals from logged voltage data. It is designed as a UNIX-style stream filter that can be composed with small tools.

Many battery loggers capture startup transients, battery insertion events, recovery periods, and other non-discharge portions.

When extracting discharge intervals from logged data, Absolute mode is intended for measurements where discharge starts and ends by connecting or disconnecting the battery. Delta mode is intended for measurements where the battery remains connected and discharge is controlled by switching the load.

crop_vbat.awk automatically extracts only the valid discharge interval from such logs. It is particularly useful as a preprocessing filter before numerical integration, capacity estimation, or statistical analysis.

Synopsis

crop_vbat.awk
  [-v v_term=V]
  [-v v_delta=V]
  [-v v_abn=V]
  [-v cont=N]
  [-v myname=NAME]
  [-v quiet]
  [FILE ...]

Description

Input must contain one numeric value per line. Non-numeric lines are rejected and reported to stderr. All computations are done numerically, but output preserves the original text format.

Start and termination of a discharge segment are detected using either ±Δ or absolute threshold criteria. Multiple segments can be extracted from one stream when continuation mode is enabled.

Input format

• One numeric sample per line
• Optional sign, decimal, and scientific notation supported
• Trailing CR characters are removed automatically
• Original numeric formatting is preserved on output

Accepted examples:

+01.234
0.98
3.01E+00
.75
2.

Segment detection

The following symbols are used:

• v_cur Current sample voltage.
• v_prev Previous sample voltage.

Start/Resume condition (output enabled):

• Delta mode (v_delta > 0): (v_cur - v_prev < -v_delta) && (v_cur > v_term)
• Absolute mode (v_delta = 0): (v_cur > v_term)

Terminate/Halt condition (output disabled):

• Delta mode (v_delta > 0): (v_cur - v_prev > +v_delta) || (v_cur < v_term)
• Absolute mode (v_delta = 0): (v_cur < v_term)

The sample that satisfies the termination condition is not emitted. Whether the condition causes termination or only a halt, the last output sample is the preceding value (v_prev).

When continuation mode is active (cont > 1), a termination condition halts the current segment and the detector returns to the idle state.

Detection resumes until the requested number of segments has been extracted.

Options

All options are given via awk -v variables.

• v_term=V — absolute termination threshold voltage (default 1.0 V)
• v_delta=V — delta threshold for 'Δ mode' (e.g. 0.02 V)
• v_abn=V — over-range rejection threshold (default 10.0 V)
• cont=N — number of segments to output (1 … 2⁵³ - 1, default 1)
• myname=NAME — stderr log prefix label
• quiet — Suppress error messages for skip conditions (i.e. over voltage or negative voltage conditions)

Output

Cropped samples are written to stdout unchanged. Diagnostic messages are written to stderr with the program label prefix.

Exit status

• 0 — normal completion
• 1 — argument validation error

EXAMPLES

Extract a voltage column and crop one discharge segment by ±Δ criteria:

cut -f 4 data.tsv | crop_vbat.awk -v v_delta=0.02

Use explicit thresholds:

crop_vbat.awk -v v_term=0.9 log.txt

Allow three discharge segments:

crop_vbat.awk -v cont=3 log.txt

Capacity estimate with fixed interval and load:

cut -f 4 sample1.dat \
| crop_vbat.awk -v v_term=0.9 -v v_delta=0.02 \
| stats.awk -v out=tsv \
| grep sum \
| awk -v r=2.5 -v dt=10 '{print $2 * dt / r / 3600 * 1000}'

Download

The distribution archive contains:

• crop_vbat.awk
• crop_vbat.awk.1 (manual page)
• LICENSE

Download crop_vbat-1.11.tar.gz — SPDX-License-Identifier: BSD-3-Clause

SHA256 and MD5 hash values of the archive:

SHA256 (crop_vbat-1.11.tar.gz) = b45d5a4ff53828ea235ab01e6628f4d2ac7423478df74497e2ae64dcafb77b57
MD5 (crop_vbat-1.11.tar.gz) = 688fcaf18c9ff34951d3ce6810386669

Users can verify the distributed crop_vbat-1.11.tar.gz using:

sha256 crop_vbat-1.11.tar.gz
md5    crop_vbat-1.11.tar.gz

Appendix A. Example of Absolute Mode

Figure A-1 shows a practical example of Absolute mode applied to a battery discharge log.

The test was performed on an LR44 alkaline cell discharged through a fixed 1 kΩ load resistor at approximately 25°C. During the measurement, an unexpected voltage anomaly ("Unexpected notch") appeared in the early stage of discharge. The discharge test was later intentionally interrupted ("Break") by disconnecting the battery, and subsequently resumed ("Resume") by reconnecting it.

Such interruptions and irregular events are common in practical measurements and can complicate automatic extraction of valid discharge intervals.

Absolute mode is intended for measurement systems in which the battery itself is connected and disconnected during the test. In this example, crop_vbat.awk automatically identifies the valid discharge segment and extracts the interval from the start of discharge to the point where the battery voltage reaches the specified termination voltage, V_term. Periods during which the battery is disconnected are excluded from the extracted segment.

The extracted discharge interval can then be used for subsequent processing such as discharge-capacity calculation, statistical analysis, or comparison of capacity at different termination voltages.

Figure A-2 illustrates a typical battery-discharge measurement arrangement.

Depending on the measurement point, different voltage waveforms are observed during intermittent discharge testing. When the battery terminal voltage (Vbat) is monitored, load switching typically produces relatively small voltage transitions. When the load-side voltage (Vmon) is monitored, the measured voltage alternates between the battery voltage and approximately zero volts as the battery is connected to and disconnected from the load.

In general, Delta mode is well suited to Vbat measurements, whereas Absolute mode is better suited to Vmon measurements.

See Also

• stats.awk — stream statistics utility