Smartfin Publish Data Format

Key Definitions

• session: refers to the time interval when fin starts recording to when the fin stops recording (i.e. surf session), also a single file of data on the fin
• ensemble: referring to each "point", since each "point" may contain multiple discrete "measurements". There are multiple ensemble types (corresponding to different IDs such as Temp, IMU, GPS, Temp+IMU, Battery, etc.) that occur at various rates.
• measurement: a specific sensor value
• packet: raw binary blob of max 496 bytes containing at least 1 ensemble.
• record: base85/base64 encoded packet. We would like to avoid Event because it has a technical definition when we think about task scheduling and programming.

Requirements

Smartfin Records MUST consist of binary data (Smartfin Packet) encoded in Base85. All data format specifications in this document are referencing the raw binary format (not Base85 encoded).

Packets MUST NOT exceed 496 bytes due to the limitation of the Particle publish API. This results in a maximum base85 encoded Record of 620 characters.

Packets MUST consist of concatenated ensembles followed by zero padding to reach the 496 byte packet size.

Each ensemble MUST consist of a three byte (24-bit) header denoting the ensemble type and time followed by a variable length payload. Ensemble types are defined below.

Integer Types

Type	Length (bytes)	Description	Byte Endianness
U8	1	Unsigned 8 bit integer	Little/Big
<U16	2	Unsigned 16 bit integer	Little
<U32	4	Unsigned 32 bit integer	Little
<U64	8	Unsigned 64 bit integer	Little
S8	1	Signed 8 bit integer	Little/Big
<S16	2	Signed 16 bit integer	Little
<S32	4	Signed 32 bit integer	Little
<S64	8	Signed 64 bit integer	Little
F32	4	IEEE single precision float
F64	8	IEEE double precision float
C[N]	N	N-array of signed 8-bit chars
B[N]	N	N-array of unsigned 8-bit ints
>U16	2	Unsigned 16 bit integer	Big
>U32	4	Unsigned 32 bit integer	Big
>U64	8	Unsigned 64 bit integer	Big
>S16	2	Signed 16 bit integer	Big
>S32	4	Signed 32 bit integer	Big
>S64	8	Signed 64 bit integer	Big

Ensemble Header

Message Offset	Description	Type
0x00	Data Type/Time LSB	U8
0x01	Time MSB	>U16

Bitwise, this is as follows:

• 23:20 - Time MSB
• 19:16 - Data Type
• 15:0 - Time MSB

Ensemble Type/Time LSB

The data type lives in the least significant 4 bits of the first byte. The most significant 4 bits of the first byte are the most significant 4 bits of the time field.

Ensemble Block Time

The 20 bit Data Block Time field represents the time in tenths of a second since the start of the recording.

Ensemble Types

Ensemble Type	Ensemble ID	Data Payload Length
Temperature	1	2
IMU	2	3
GPS	3	0
Temperature + IMU	4	5
Temperature + GPS	5	0
Temperature + IMU + GPS	6	13
Battery	7	2
Temperature + Epoch	8	6
IMUx3	9	18
Temperature + IMUx3	10	20
Temperature + IMUx3 + GPS	11	28
Text	15	Variable

Temperature (0x01)

Payload Offset	Description	Type
0x00	Raw Temperature	>S16

There are two temperature sensor sources. If the temperature source is from the IMU, then the scaled temperature can be retrieved with RAW_TEMP / 333.87 + 21.0. Otherwise, the scaled temperature can be retrieved with RAW_TEMP / 128.0.

If the temperature is < 0, then the water detect pin did not detect water, and the real temperature in degrees C is SCALED_TEMP + 100. Otherwise, the water detect pin did detect water, and the real temperature in degrees C is SCALED_TEMP.

IMU (0x02)

Payload Offset	Description	Type
0x00	Raw X Acceleration	S8
0x01	Raw Y Acceleration	S8
0x02	Raw Z Acceleration	S8

To convert to acceleration in multiples of Earth gravity, use RAW_ACC / 64.

GPS (0x03)

Undefined

Temperature + IMU (0x04)

Payload Offset	Description	Type
0x00	Raw Temperature	>S16
0x02	Raw X Acceleration	S8
0x03	Raw Y Acceleration	S8
0x04	Raw Z Acceleration	S8

See Data ID 0x01 and 0x02 for descriptions of the data fields.

Temperature + GPS (0x05)

Undefined

Temperature + IMU + GPS (0x06)

Payload Offset	Description	Type
0x00	Raw Temperature	>S16
0x02	Raw X Acceleration	S8
0x03	Raw Y Acceleration	S8
0x04	Raw Z Acceleration	S8
0x05	Latitude (deg * 1e6)	>S32
0x09	Longitude (deg * 1e6)	>S32

See Data ID 0x01 and 0x02 for descriptions of the temperature and acceleration data fields.

Battery (0x07)

Payload Offset	Description	Type
0x00	Battery Voltage (mV)	>U16

Temperature + Epoch (0x08)

Payload Offset	Description	Type
0x00	Raw Temperature	>S16
0x02	Time (seconds since Unix epoch)	>U32

See Data ID 0x01 for description of the raw temperature data field

IMUx3 (0x09)

Payload Offset	Description	Type
0x00	Scaled X Acceleration	>S16
0x02	Scaled Y Acceleration	>S16
0x04	Scaled Z Acceleration	>S16
0x06	Scaled X Angular Velocity	>S16
0x08	Scaled Y Angular Velocity	>S16
0x0A	Scaled Z Angular Velocity	>S16
0x0C	Scaled X Magnetic Field	>S16
0x0E	Scaled Y Magnetic Field	>S16
0x10	Scaled Z Magnetic Field	>S16

Accelerations are in g scaled to Q14 (scaled up by 16384). ACC = SCALED_ACC / 16384.

Angular velocity in degrees per second is ANG_VEL = SCALED_ANG_VEL / 131.072.

Magnetic field in uT is MAG = SCALED_MAG * 0.15

Temperature + IMUx3 (0x0A)

Payload Offset	Description	Type
0x00	Raw Temperature	>S16
0x02	Scaled X Acceleration	>S16
0x04	Scaled Y Acceleration	>S16
0x06	Scaled Z Acceleration	>S16
0x08	Scaled X Angular Velocity	>S16
0x0A	Scaled Y Angular Velocity	>S16
0x0C	Scaled Z Angular Velocity	>S16
0x0E	Scaled X Magnetic Field	>S16
0x10	Scaled Y Magnetic Field	>S16
0x12	Scaled Z Magnetic Field	>S16

See Data ID 0x01 and 0x09 for descriptions of data fields.

Temperature + IMUx3 + GPS (0x0B)

Payload Offset	Description	Type
0x00	Raw Temperature	>S16
0x02	Scaled X Acceleration	>S16
0x04	Scaled Y Acceleration	>S16
0x06	Scaled Z Acceleration	>S16
0x08	Scaled X Angular Velocity	>S16
0x0A	Scaled Y Acceleration	>S16
0x0C	Scaled Z Acceleration	>S16
0x0E	Scaled X Magnetic Field	>S16
0x10	Scaled Y Magnetic Field	>S16
0x12	Scaled Z Magnetic Field	>S16
0x14	Latitude (deg * 1e6)	>S32
0x18	Longitude (deg * 1e6)	>S32

See Data ID 0x01 and 0x09 for descriptions of temperature and IMU data fields.

Text (0x0F)

Payload Offset	Description	Type
0x00	String Length (N)	U8
0x01	Text Data	C[N]