API Reference

One import brings in the whole package:

import 'package:carp_aware_package/carp_aware_package.dart';

Note

This page summarises the public API. The generated Dart API documentation on pub.dev has the full detail.

AppleWatchSamplingPackage

The CAMS sampling package. Register it once, before creating or deploying a protocol.

SamplingPackageRegistry().register(AppleWatchSamplingPackage());

Measure type constants

Constant	Value
APPLE_WATCH_NAMESPACE	dk.carp.watch.aware
MOTION	dk.carp.watch.aware.motion
HEART_RATE	dk.carp.watch.aware.heartrate
BATTERY	dk.carp.watch.aware.battery
LOCATION	dk.carp.watch.aware.location
HEADING	dk.carp.watch.aware.heading
BLUETOOTH	dk.carp.watch.aware.bluetooth
AMBIENT_NOISE	dk.carp.watch.aware.ambientnoise
AUDIO_LABEL	dk.carp.watch.aware.audiolabel
DEVICE	dk.carp.watch.aware.device

Members

Member	Type	Description
watchSamplingSchemes	DataTypeSamplingSchemeMap	Static. Sampling schemes for all nine types
samplingSchemes	DataTypeSamplingSchemeMap	The same map, as required by SamplingPackage
dataTypes	List<DataTypeMetaData>	Metadata for the supported types
deviceType	String	AppleWatchDevice.DEVICE_TYPE
deviceManager	DeviceManager	The shared AppleWatchDeviceManager
create(String type)	Probe?	The probe for a measure type, or null
onRegister()	void	Registers the device, registration and data classes for JSON

AppleWatchDevice

The device configuration placed in the study protocol. Extends CamsDevice<AppleWatchDeviceRegistration>.

final watch = AppleWatchDevice(
  motionSamplingRate: 10,
  heartRateEnabled: true,
  fileTransferInterval: const Duration(minutes: 15),
);

Member	Type	Description
DEVICE_TYPE	String	Static. The device type identifier
DEFAULT_ROLE_NAME	String	Static. 'Apple Watch'
toWatchSettings()	Map<String, dynamic>	This configuration as the settings dictionary sent to the watch
dataTypeSamplingSchemes	DataTypeSamplingSchemeMap?	The data types this device can collect
fromJson / toJson		Standard CARP serialization

Every configuration property is documented in Configuring the Watch.

AppleWatchDeviceRegistration

The runtime registration of the watch, stored with the deployment. Extends HardwareDeviceRegistration.

Field	Type	Description
watchDeviceId	String?	AWARE device id of the watch, if exchanged
model	String?	Watch model, if known
systemVersion	String?	watchOS version, if known
isWatchAppInstalled	bool	Whether the companion app is installed

AppleWatchDeviceManager

The CAMS device manager for the watch. Obtain it from the DeviceController:

final watchManager =
    DeviceController().getDeviceManager(AppleWatchDevice.DEVICE_TYPE)
        as AppleWatchDeviceManager;

Member	Type	Description
records	Stream<AppleWatchRecords>	Batches of records received from the watch
watchStatus	AppleWatchStatus	Last known state of the connection
watchStatusEvents	Stream<AppleWatchStatus>	State changes as they happen
fileTransferEvents	Stream<AppleWatchFileTransfer>	Progress of each transferred file
watchInfo	AppleWatchDeviceInfo?	Information reported by the watch app
displayName	String?	Watch name, model, or 'Apple Watch'
batteryLevel	int?	Watch battery in percent, from the last transfer
batteryEvents	Stream<int>	Battery level changes
canConnect	bool	true on iOS only
service	AppleWatchService	The underlying native service

See Runtime State for how to use these.

AppleWatchService

A singleton wrapping the three platform channels. The device manager uses it; use it directly only for low-level access, such as a debug screen.

final service = AppleWatchService();

Member	Returns	Description
isSupportedPlatform	bool	true on iOS
configure(AppleWatchDevice)	Future<bool>	Create and configure the native AWARE sensor
getStatus()	Future<AppleWatchStatus>	Current connection status
exchangeDeviceId()	Future<String?>	Exchange AWARE device ids with the watch. Requires the watch app to be reachable
close()	Future<void>	Tear down the native sensor. Does not stop collection on the watch
records	Stream<AppleWatchRecords>	Record batches from the watch
statusEvents	Stream<AppleWatchStatus>	Status changes
fileTransferEvents	Stream<AppleWatchFileTransfer>	File transfer progress

AppleWatchStatus

Field	Type	Description
isSupported	bool	WatchConnectivity is supported on this phone
isPaired	bool	A watch is paired
isWatchAppInstalled	bool	The companion app is installed on it
isReachable	bool	The watch app is reachable right now
isCollectingData	bool	The watch app reported that it is sampling
activationState	String	notActivated, inactive, or activated
outstandingFileTransferCount	int	Transfers not yet completed
phoneDeviceId	String?	AWARE device id of the phone
watchDeviceId	String?	AWARE device id of the watch
lastMessageAt	DateTime?	Last message exchanged
lastFileTransferAt	DateTime?	Last file received
lastError	String?	Last communication error
isAvailable	bool	isSupported && isPaired && isWatchAppInstalled

AppleWatchRecords

One decoded chunk file: all records from one AWARE table.

Field	Type	Description
table	String	The AWARE table, see AppleWatchTable
chunkIndex	int	1-based index of this chunk in the transfer
totalChunks	int	Number of chunks for this table in the transfer
records	List<Map<String, dynamic>>	The raw AWARE rows

AppleWatchFileTransfer

Field	Type	Description
table	String	The AWARE table the records come from
fileName	String	Name of the transferred file
chunkIndex	int	1-based index in the transfer
totalChunks	int	Number of files in the transfer
state	WatchFileTransferState	How far the file has come
error	String?	Set when the state is failed or saveFailed

Data classes

All extend AppleWatchData, which carries deviceId, timestamp, label and recordId. Fields per class are documented in Measure Types & Data.

Class	Measure type
AppleWatchMotion	MOTION
AppleWatchHeartRate	HEART_RATE
AppleWatchBattery	BATTERY
AppleWatchLocation	LOCATION
AppleWatchHeading	HEADING
AppleWatchBluetooth	BLUETOOTH
AppleWatchAmbientNoise	AMBIENT_NOISE
AppleWatchAudioLabel	AUDIO_LABEL
AppleWatchDeviceInfo	DEVICE

Probes

One per measure type, all extending AppleWatchProbe (itself a StreamProbe). They are created by the sampling package and rarely used directly.

AppleWatchMotionProbe, AppleWatchHeartRateProbe, AppleWatchBatteryProbe, AppleWatchLocationProbe, AppleWatchHeadingProbe, AppleWatchBluetoothProbe, AppleWatchAmbientNoiseProbe, AppleWatchAudioLabelProbe, AppleWatchDeviceInfoProbe.

Each declares the AWARE table it reads and a toData() that converts one row into its data class — the extension point if you add a sensor of your own.

Enums

WatchBackgroundSessionType

How the watch app keeps running when it is not in the foreground.

Value	Meaning
none	No background session — foreground only
workout	An HKWorkoutSession; longest runtime, visible in fitness apps
microphone	A silent microphone capture session (default)

WatchTransferMode

Which records the watch includes in a transfer.

Value	Meaning
all	Every record, every time; duplicates discarded by record id
incremental	Only records since the last successful transfer (default)

WatchBatteryState

A 1:1 mapping of WKInterfaceDeviceBatteryState.

Value	Meaning
unknown	The state cannot be determined
unplugged	Running on battery, discharging
charging	Plugged in, below 100%
full	Plugged in, at 100%

WatchFileTransferState

The progress of one transferred file.

Value	Meaning
received	Arrived on the phone
processing	Being decompressed and decoded
decoded	Records decoded and emitted
saving	Being written to the local AWARE database
saved	Written to the local AWARE database
failed	Processing failed
saveFailed	Writing to the local AWARE database failed
unknown	Unrecognised state from the native side

AppleWatchTable

Constants for the AWARE table names, used to route records to probes.

motion, heartRate, battery, location, heading, bluetooth, ambientNoise, audioLabel, device — mapping to ios_watch_motion, ios_watch_heart_rate, and so on. See How It Works.