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 — elapsed-time measurement (time since MCU start, used to align data on the time axis). Distinct from the nonce column below, which is the grouping counter.

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, °C.

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.