Raw data models

Raw metrics are the measurements as they come off the bracelet: one row per sampling interval, parsed from the transferred files and written to the local database. They are the input the SDK uses to build the daily Summaries.

How often a row appears is governed by the bracelet plan and sampling rate — see Bracelet Plans and Set Sampling rate. At a 60-second sampling rate, a MetricActivity row arrives every 60 seconds, holding the steps taken and the average heart rate over that minute.

Note: Raw metrics accumulate quickly. See Data deletion and clean up for the retention guidance before you ship.

Reading raw metrics

Each model has a repository, reached from the Data SDK manager:

val manager = DataSdk.getInstance().getManager()

manager.metricActivityRepository.getByTimestampRange(from, to) { metrics ->
    metrics?.forEach { Log.d("Corsano-SDK", it.toString()) }
}

Model	Repository	Contents
MetricActivity	metricActivityRepository	Heart rate, steps, SpO2, respiration, NIBP, battery, wearing
MetricPpg	metricPpgRepository	Averaged PPG and accelerometer values
MetricHrv	metricHrvRepository	RR intervals
MetricSleep	metricSleepRepository	Sleep state per interval
MetricTemperature	metricTemperatureRepository	Core body and skin temperature
MetricTemperatureRaw	metricTemperatureRawRepository	Raw heat-flux sensor channels
MetricEmography	metricEmographyRepository	Cognitive zone and skin conductance (B2)

Repository methods

Every metric repository exposes the same surface. Results are delivered to a callback rather than returned.

Method	Parameters	Delivers
getByTimestampRange(start, end, results)	start: Long, end: Long	Array<T>?
getByTimestampRange(start, end, groupedBySeconds, results)	plus groupedBySeconds: Int	Array<T>?
getAll(results)	—	Array<T>?
getAll(groupedBySeconds, results)	groupedBySeconds: Int	Array<T>?
getLast(result)	—	T?
deleteByTimestamp(timestamp, onSuccess, onError)	timestamp: Long	—
deleteByTimestampRange(start, end, onSuccess, onError)	start: Long, end: Long	—
deleteAll(onSuccess, onError)	—	—

groupedBySeconds down-samples the result: rows are aggregated into buckets of that many seconds, which is what you want when charting a long period rather than reading every sample.

Timestamps are UTC milliseconds. onSuccess and onError are optional on the delete methods.

Note: getByTimestamp(startOfFirstDay, results) is deprecated. Use getByTimestampRange instead.

Field conventions

Three conventions apply across all the models below.

• timestamp is the primary key: time in UTC, in milliseconds.
• date is the local date matching that timestamp, formatted yyyy-MM-dd'T'HH:mm:ss.SSSXXX.
• Quality fields (bpm_q, spo2Q, resp_q, …) run 0–4, where 0 is unusable and 4 is very good. Values of 0 and 1 should not drive clinical alerts — see Quality.

Warning: Fields marked deprecated below are annotated @Deprecated("value always null") in the SDK. They are not merely discouraged — they are always null. Do not write code that reads them, and be aware that older examples elsewhere may show them populated.

isSynced is deprecated on every model that carries it.

MetricActivity

The main raw metric: one row per sampling interval with the vitals measured during it.

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
bpm	Int?	Heart rate [0-255]
bpm_q	Int?	Heart rate quality [0-4]
q	Int?	Same as bpm_q
last_steps	Int?	Steps taken during the interval
activity_type	Int?	0 UNSPECIFIED, 1 OTHER, 2 WALK, 4 RUN, 6 CYCLE, 7 REST
spo2	Int?	SpO2 [0-255]. B2 only
spo2Q	Int?	SpO2 quality [0-4]. See Quality for the additional codes 103–106
energy_exp	Int?	Energy expenditure in cal (active + passive)
respiration_rate	Float?	Respiration rate in breaths/min
resp_q	Int?	Respiration rate quality [0-4]
wearing	Int?	Wearing status [0-4]. 0 not worn, 4 correctly worn on the wrist
battery	Int?	Battery percentage [0-100]
isCharging	Boolean?	Whether the bracelet was charging
nibpSystolic	Int?	Systolic blood pressure. See NIBP
nibpDiastolic	Int?	Diastolic blood pressure
cardiacArrest	Int?	Cardiac arrest indicator
activityCount	Int?	Activity count
isSynced	Boolean	Deprecated

Fields that are always null

Field	Type	Note
speed	Double?	Deprecated — was speed in m/s
pha, pha_q	Int?	Deprecated
move_alert	Int?	Deprecated
cw, cwt	Int?	Deprecated
step_calories, rest_calories	Int?	Deprecated
distance, step_duration	Int?	Deprecated
active_calories	Int?	Deprecated — use energy_exp

Warning: temp1 and temp2 exist on MetricActivity but are annotated @Ignore, meaning they are not persisted. Any MetricActivity you read back from the database has both set to null. For temperature use MetricTemperature.

MetricActivity implements the IMetricActivity interface, which is where the field documentation lives in the SDK.

Example

B2, sampling rate of 10 seconds. Deprecated fields are omitted; they would all read null.

{
   "timestamp": 1694961234000,
   "date": "2023-09-17T16:33:54.000+02:00",
   "bpm": 78,
   "bpm_q": 1,
   "q": 1,
   "last_steps": 2,
   "activity_type": 1,
   "spo2": 100,
   "spo2Q": 2,
   "energy_exp": 175,
   "respiration_rate": 0,
   "resp_q": 0,
   "wearing": 4,
   "battery": 70,
   "isCharging": false
}

MetricPpg

Averaged PPG and accelerometer values. Every value is an average since the previous raw metric, not an instantaneous reading.

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
ppg	Int	PPG value, averaged over the interval
acc	Int	Accelerometer magnitude, averaged. See Accelerometer data
accX	Int?	Accelerometer X, averaged
accY	Int?	Accelerometer Y, averaged
accZ	Int?	Accelerometer Z, averaged
bpm	Int	Heart rate, averaged
bpmQ	Int	Heart rate quality [0-4]
crc	Int	Checksum of the source record
isSynced	Boolean	Deprecated

Note: The quality field here is bpmQ, camel case — unlike MetricActivity, which uses bpm_q. The two models do not share a naming convention.

For the full-rate PPG waveform rather than these averages, see Parsing Raw Files.

MetricHrv

RR intervals — the time between successive heartbeats.

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
beats	Int	RR interval in milliseconds
isSynced	Boolean	Deprecated

Note: MetricHrv arrives frequently, close to once per second, but only while the wearer is reasonably still. Movement prevents the RR interval from being determined, so gaps in this series are expected rather than a fault.

HRV sampling rate explained.

MetricSleep

One row per sleep-measurement interval.

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
sleepState	Int	Sleep state for the interval
quality	Int	Quality of the sleep state
isSynced	Boolean	Deprecated

Sleep monitoring only runs inside the bedtime/risetime window. For the state values, how sessions are built and how the summary is produced, see Sleep processing and Sleep Settings.

MetricTemperature

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
temp1	Float?	B2: core body temperature in °C, averaged since the previous raw metric
temp2	Float?	B1: skin temperature in °C, averaged. On B2, skin temperature at night
tempAmb	Float?	Ambient temperature in °C
isSynced	Boolean	Deprecated

Note that temp1 and temp2 mean different things depending on the bracelet — check the hardware before interpreting them.

MetricTemperatureRaw

The unprocessed heat-flux sensor channels, recorded only when raw temperature is enabled — see Enable EmoGraphy, BioZ & Accelerometer.

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
skinTemp	Float?	Skin temperature in °C
heatFlux	Float?	Heat flux measured by the sensor
cbt	Float?	Core body temperature in °C
pulseRate	Int?	Pulse rate recorded alongside the sample
accX	Float?	Accelerometer X
accY	Float?	Accelerometer Y
accZ	Float?	Accelerometer Z

Note: Unlike the other raw metrics, MetricTemperatureRaw has no isSynced field. Its accelerometer axes are Float, whereas MetricPpg uses Int.

MetricEmography

EmoGraphy — also called EDA or stress data. B2 only, and only when EmoGraphy is enabled on the bracelet.

Field	Type	Description
timestamp	Long	UTC time, primary key
date	String	Local date of the timestamp
cognitiveZone	Int	Cognitive zone [0-3]: 0 undefined, 1 under-stimulated, 2 balanced, 3 over-stimulated
cognitiveZoneQ	Int	Quality of the cognitive zone [0-4]
predictiveCZ	Int	Predicted cognitive zone [0-3]
predictiveCZTransitionTime	Int	Minutes until the predicted transition [0-65535]
czHour	Int	Cognitive zone one hour ahead [0-3]
cortisolContribution	Long	Cortisol contribution
stressLevelSkinConductance	Int	Stress level from skin conductance [0-1000]
stressLevelSkinConductanceQ	Int	Quality of the skin conductance value [0-4]
isSynced	Boolean	Deprecated

Note: Only summaries are retained for EmoGraphy in the general case — see Stress data and EmographySummaryModel.