Sensor Data Format
Action data sensors
Action data consist of data gathered from various sensors, packed and stored inside MP4 container.
Currently supported sensors are:
- GPS
- Accelerometer
- Gyro
- Magnetometer
- Barometer
- Thermometer
Depending on a sensor type, data is read out at different frequencies. Optimal sample rate is yet to be defined (as a tradeoff between action data size and sensor resolution) although it's most likely that GPS, barometer and thermometer sensor will be read out and stored at 1Hz frequency.
Sensor data format
Raw sensor data format
Data from sensors is recorded as it's read out, without any modification. To reduce size of the action data block, binary data is stored in a following way:
First, data type (which correspond to sensor type) of 1 byte length is stored and it's followed with N bytes which contains data for that particular data/sensor type. Number of bytes following ie. number of payload bytes needed for each sensor varies depending on sensor type.
So, for example, heart rate sensor will have payload of 1 byte where gyro sensor has payload of length 3x4B. Length of payload for each sensor type is addressed in look-up table in TTAD atom. Purpose of the table is to map sensor types with it's payload lengths so that the client parsing binary data don't lose the track while parsing if it doesn't recognise some of the sensor types used.
Unless multiple sensor samples share the same timestamp, every sensor sample value will have it's timestamp (data type = -1) preceding it.
NOTE: All sensor data values are stored in little endian format contrary to MP4 atom values which are big endian.
Following table represents data/sensor types currently defined along with corresponding descriptions:
Data Type | Sensor | Payload Length (bytes) | Payload Data Type | Description |
-1 | timestamp | 4 | unsigned integer | Timestamp in milliseconds. |
0 | gyro | 12 (3 x 4B) | 3 x integer | Angular speed of rotation in deg/s for x, y and z axes, correspondingly. |
1 | barometer | 4 | integer | Pressure in Pa. |
2 | magnetometer | 12 (3 x 4B) | 3 x integer | Magnetic field strength in micro Teslas for x, y and z axes, correspondingly. |
3 | accelerometer | 12 (3 x 4B) | 3 x integer | Acceleration in milli Gs for x, y and z axes, correspondingly. |
4 | thermometer | 4 | integer | Temperature inside of a housing in milli centigrade. |
5 | gps | 92 | Gps_data_t | Packet gps_data_t structure containing relevant GPS data. |
6 | heart rate | 1 | unsigned integer | Contains heart rate data. |
7 | cadence | TBD | TDB | Contains distance and rpm values. |
GPS data structure (Gps_data_t) is shown in the table below (all values stored in little endian format). Unless otherwise stated, all doubles are 8 bytes long and all ints are 4 bytes (total size of the structure is 92 bytes). Please note that, depending on the GPS status, some data may be undefined.
struct __attribute__((packed)) TTGpsData_t { double time; // UTC timestamp EGpsMode mode; // mode of fix (32-bit int value, possible options: 0 - Not seen, 1 - No Fix, 2 - Mode2D, 3 - Mode3D) double speed; // speed over ground (meters/sec) double altitude; // altitude in meters (valid if mode==3) double latitude; // latitude in degrees (valid if mode>=2) double longitude; // longitude in degrees (valid if mode>=2) unsigned int reserved; // reserved double track; // course made good (to true north) double epv; // vertical pos. uncertainty (m) double epy; // latitude pos. uncertainty (m) double epx; // longitude pos. uncertainty (m) double epd; // track uncertainty (deg) int sattelitesUsed; // number of satellites };
MP4 sensor data format
Structure of the TTAD (moov.udta.TTMD.TTAD) atom which contains above mentioned data is:
Size
A 32-bit integer that specifies the number of bytes in this sample description atom.
Type
A 32-bit integer that identifies the atom type; this field must be set to 'TTAD'.
Version
A 4-byte specification of the version of this TTAD atom (big endian format).
Number of entries
A 32-bit integer containing the number of data type descriptions that follow.
Data type description table
An array of data type descriptions. For details, see the chapter 'General structure of data type description table'.
Payload
Raw binary representation of sensor data acquired during video recording.
General structure of data type description table
A table that defines length (in bytes) of each data type in the sensor data. Each table entry contains a data type field and a length. The structure is shown in the next table.
Field | Bytes |
Data type | 4 |
Data length | 4 |