This documentation provides information on getting activity data out of ActiGraph .gt3x files.
This documentation is valid for .gt3x files downloaded from the following devices:
- GT3X+ (serial numbers starting with NEO and firmware 3.0 and higher)
- wGT3X+ (serial numbers starting with CLE)
- wGT3X-BT (serial numbers starting with MOS0 and MOS2)
- ActiSleep+ (serial numbers starting with MRA and firmware 3.0 and higher)
- wActiSleep+ (serial numbers starting with MOS3
- wActiSleep-BT (serial numbers starting with MOS4)
- GT9X Link (serial numbers starting with TAS)
NOTE: Devices with serial numbers that start with "NEO" or "MRA" and have firmware version of 2.5.0 or earlier use an older format of the .gt3x file. Please see this GitHub repo for more information: https://github.com/actigraph/NHANES-GT3X-File-Format
The .gt3x file is a zip archive contains several files needed to parse activity data. Here are the different files:
FileName | Description |
---|---|
log.bin | Log Records (see below) |
info.txt | Device information including start date and download date. |
- Verify .gt3x file is a zip file
- Verify .gt3x file has log.bin file
- Verify .gt3x file has info.txt file
- Extract log.bin and info.txt files
- Parse and save the sample rate from the info.txt file (it's stored in Hz)
- Parse and save the start date from the info.txt file (it's stored in .NET Ticks)
Binary .gt3x file data is grouped into timestamped records of varying types that are written sequentially as the data becomes available on the activity monitor. The format is similar to common protocols used for serial communication. Each log record includes a header with a record separator, record type, timestamp and payload size. After the variable length payload is a checksum for ensuring data integrity.
Offset (bytes) | Size (bytes) | Name | Description | Part of Record |
---|---|---|---|---|
0 | 1 | Seperator | An ASCII record separator byte (1Eh) marks the beginning of each log record. | Header |
1 | 1 | Type | A type identifier is used to interpret the payload of the record. | Header |
2 | 4 | Timestamp | The date and time of the data contained in the record are marked to the nearest second in Unix time format. | Header |
6 | 2 | Size | The size of the payload is given in bytes as an little-endian unsigned integer. | Header |
8 | n | Payload | This is the actual data that varies based on the record *Type* field. It's size is provided in the *Size* field. Please refer to the appropriate section for the record type for the indiviual payload formats. | Payload |
8 + n | 1 | Checksum | A 1-byte checksum immediately follows the record payload. It is a 1's complement, exclusive-or (XOR) of the log header and payload with an initial value of zero. | Checksum |
1E 06 71 E8 B4 54 7C 00
Offset (bytes) | Size (bytes) | Name | Bytes from Sample | Resultant Value |
---|---|---|---|---|
0 | 1 | Seperator | 0x1E | 0x1E |
1 | 1 | Type | 0x06 | 6 (see Metadata below) |
2 | 4 | Timestamp | 0x71 0xE8 0xB4 0x54 | 1421142129 or 2015/01/13 09:42:09 |
6 | 2 | Size | 0x7C 0x00 | 124 |
Note that some undocumented records are used for internal state or testing. They may be safely ignored.
ID (dec) | ID (hex) | Type | Description |
---|---|---|---|
0 | 0x00 | ACTIVITY | One second of raw activity samples packed into 12-bit values in YXZ order. |
2 | 0x02 | BATTERY | Battery voltage in millivolts as a little-endian unsigned short (2 bytes). |
3 | 0x03 | EVENT | Logging records used for internal debugging. |
4 | 0x04 | HEART_RATE_BPM | Heart rate average beats per minute (BPM) as one byte unsigned integer. |
5 | 0x05 | LUX | Lux value as a little-endian unsigned short (2 bytes). |
6 | 0x06 | METADATA | Arbitrary metadata content. The first record in every log is contains subject data in JSON format. |
7 | 0x07 | TAG | 13 Byte Serial, 1 Byte Tx Power, 1 Byte (signed) RSSI |
9 | 0x09 | EPOCH | 60-second epoch data |
11 | 0x0B | HEART_RATE_ANT | Heart Rate RR information from ANT+ sensor. |
12 | 0x0C | EPOCH2 | 60-second epoch data |
13 | 0x0D | CAPSENSE | Capacitive sense data |
14 | 0x0E | HEART_RATE_BLE | Bluetooth heart rate information (BPM and RR). This is a Bluetooth standard format. |
15 | 0x0F | EPOCH3 | 60-second epoch data |
16 | 0x10 | EPOCH4 | 60-second epoch data |
21 | 0x15 | PARAMETERS | Records various configuration parameters and device attributes on initialization. |
24 | 0x18 | SENSOR_SCHEMA | This record allows dynamic definition of a SENSOR_DATA record format. |
25 | 0x19 | SENSOR_DATA | This record stores sensor data according to a SENSOR_SCHEMA definition. |
26 | 0x1A | ACTIVITY2 | One second of raw activity samples as little-endian signed-shorts in XYZ order. |
A 1-byte checksum immediately follows the record payload. It is a 1's complement, exclusive-or (XOR) of the log header and payload with an initial value of zero.
To verify you have parsed a packet correctly, calculate the checksum and compare it against the last byte of the packet.
byte chkSum = Header.Sync;
chkSum ^= Header.Type;
var timestamp = DeviceUtilities.DateTime.ToUnixTime(Header.TimeStamp);
chkSum ^= (byte)(timestamp & 0xFF);
chkSum ^= (byte)((timestamp >> 8) & 0xFF);
chkSum ^= (byte)((timestamp >> 16) & 0xFF);
chkSum ^= (byte)((timestamp >> 24) & 0xFF);
chkSum ^= (byte)(Header.Size & 0xFF);
chkSum ^= (byte)((Header.Size >> 8) & 0xFF);
for (int i = 0; i < Payload.Length; ++i)
chkSum ^= Payload[i];
chkSum = (byte)~chkSum;
public UInt32 ToUnixTime(DateTime datetime)
{
return (UInt32)(datetime - EPOCH).TotalSeconds;
}
Prepared By:
- Daniel Judge - Software Architect
- Judge Maygarden - Firmware Engineer