CSV Data Format

Overview

VBatPower uses a universal 6-column CSV format designed to be simple enough for 8-bit microcontrollers to generate. Each row represents a single measurement sample.

id,type,value,unit,nonce,runid

Column Definitions

id

Dot-notation hierarchical identifier mapping to your project structure.

  • Depth 1 (e.g. 0) — battery level
  • Depth 2 (e.g. 0.1) — component level
  • Depth 3 (e.g. 0.1.2) — state level

type

Single character indicating the measurement type:

  • t — telemetry timing (execution duration in time units)
  • v — value measurement (voltage, current, resistance, etc.)
  • n — nonce timing (elapsed time from MCU start, used to align data on the time axis)

value

Numeric measurement value. Supports integers and decimals with . as the decimal separator.

unit

Unit of the measurement. Common values: ms, V, mV, mA, A, \u00b0C.

nonce

Monotonically increasing sequence counter. Each measurement group at a given point in time shares the same nonce. The nonce never resets within a run and is used to align data points on the time axis.

runid

Numeric identifier for a test run. Multiple runs can be stored in the same CSV. The run ID is used to separate independent experiments. Lower numbers ran first.

Complete Example

A sensor node with one battery, one MCU component, and two states (sleep + active):

id,type,value,unit,nonce,runid
0,v,3.28,V,1,1
0.0.0,t,500,ms,1,1
0.0.0,v,0.01,mA,1,1
0.0.0,n,0,ms,1,1
0.0.1,t,0,ms,1,1
0.0.1,v,0,mA,1,1
0,v,3.27,V,2,1
0.0.0,t,500,ms,2,1
0.0.0,v,0.01,mA,2,1
0.0.0,n,1000,ms,2,1
0.0.1,t,200,ms,2,1
0.0.1,v,80,mA,2,1
0.0.1,n,1000,ms,2,1

In this example:

  • Battery 0 (0,v) voltage drops from 3.28V to 3.27V
  • State 0.0.0 (sleep): t = 500ms execution, v = 0.01mA current, n = elapsed time from boot
  • State 0.0.1 (active): t = 200ms execution at nonce 2, v = 80mA current draw
  • All measurements are in run 1

Design Decisions

  • No timestamps — embedded systems often lack an RTC. The nonce + elapsed time approach lets 8-bit MCUs emit data with just a simple counter and millis().
  • Numeric runid — simple integer comparison tells you which run came first.
  • Flat CSV — no JSON, no binary protocol. Easy to generate with printf on any MCU.
  • Dot-notation IDs — maps directly to your project's battery/component/state hierarchy without additional mapping tables.

Importing

In the Data page, click Import CSV and select your file. The parser validates all rows and shows a preview before importing. Invalid rows are skipped with warnings.

You can also upload data programmatically via the REST API.