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:

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

Sample Header

1E 06 71 E8 B4 54 7C 00

Log Record Types

Note that some undocumented records are used for internal state or testing. They may be safely ignored.

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:

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

Questions and Comments

If you have any other questions or comments, please reach out to Actigraph for more information.