ActiGraph .gt3x File Format

Introduction

This documentation provides information on getting activity data out of ActiGraph .gt3x files.

Valid .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)

Invalid .gt3x Files

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

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.

Steps to Parse Log Records from a .gt3x File

1. Verify .gt3x file is a zip file
2. Verify .gt3x file has log.bin file
3. Verify .gt3x file has info.txt file
4. Extract log.bin and info.txt files
5. Parse and save the sample rate from the info.txt file (it's stored in Hz)
6. Parse and save the start date from the info.txt file (it's stored in .NET Ticks)

Log Records

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.

Log Record Format

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

Sample Header

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

Log Record Types

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.

Internal/Diagnostic Log Record Types

The .gt3x file also contains record types utilized internally by ActiGraph engineers for diagnostic purposes. Records with these types can be ignored (or skipped over). The following are record types utilized for diagnostic purposes:

ID (dec)	ID (hex)	Type	Description
19	0x13	FIFO_ERROR	Records timestamp of FIFO Error
20	0x14	FIFO_DUMP	FIFO diagnostic record recorded if enabled and an error is detected

Extra bytes with 0's between valid records

There's a rare occurrence where a few extra bytes with 0's can be present between valid records. If such bytes occur, this does not mean that the data is corrupted. These bytes can be ignored (or skipped over).

Checksum Calculation

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.

Sample C# Checksum Code

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;
}

Sample GT3X File Parser

Here is a sample GT3X File Parser in the C# Programming Language.

Prepared By:

• Daniel Judge - Software Architect
• Judge Maygarden - Firmware Engineer