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:

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.