ActiGraph NHANES .gt3x File Format

Prepared By:

• Daniel Judge - Software Engineer
• Judge Maygarden - Hardware/Firmware Engineer

Last Update: 2014-07-17

Introduction

This documentation and sample library provide information on getting activity data out of ActiGraph .gt3x files that were used in the NHANES project.

Valid .gt3x Files

This documentation and library are valid for .gt3x files downloaded from GT3X+ devices with serial numbers that start with "NEO" or ActiSleep+ devices with serial numbers that start with "MRA." The devices must have a firmware version of 2.5.0 or earlier. Files that don't fall under these conditions have a different format and are not parsable using the sample library.

Invalid .gt3x Files

This documentation is INVALID 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)

Please see this GitHub repo for more information on parsing these files: https://github.com/actigraph/GT3X-File-Format

File Format

The .gt3x file is a zip archive contains several files needed to parse activity data. Click on a file for detailed information.

FileName	Description	Size	Used in Parsing?
activity.bin	Binary Activity Data Log	Up to 237.5 MB	Yes
battery.bin	Binary Battery Data Log	Up to 256 kB	No
eeprom.bin	EEPROM device contents	2 kB	No
firmware.bin	Firmware Update Storage	128 kB	No
gt3xplus.ico	Windows Drive Icon	9,662 bytes	No
info.txt	Device information including start date and download date.	No limit (usually less than 1 kB)	Yes
log.txt	Firmware Diagnostics Log	Up to 128 kB	No
lux.bin	Binary Lux Data Log	Up to 3.5 MB	Yes
metadata	Subject Biometric Data	128 kB	No
ram.bin	Microcontroller RAM contents	Up to 128 kB	No

Technical information is also available.

Steps to Parse Activity and Light Data from a .gt3x File

1. Verify .gt3x file is a zip file
2. Verify .gt3x file has activity.bin file
3. Verify .gt3x file has info.txt file
4. Verify .gt3x file has lux.bin file
5. Extract activity.bin, info.txt and lux.bin files
6. Verify the serial number in the info.txt file starts with either "NEO" or "MRA"
7. Parse and save the sample rate from the info.txt file (it's stored in Hz)
8. Parse and save the start date from the info.txt file (it's stored in .NET Ticks)
9. Optional: calculate total number of samples by multiplying the file size (in bytes) of the activity.bin file by 8 (bits per byte) and then dividing by 36 (bits per sample).
10. Open a stream connection to the extracted activity.bin file from #5 and parse the activity data.
11. Optional: Open a stream connection to the extracted lux.bin file from #5 and parse the light data.

Source Code Example

We've included a sample C# library showing how to parse a .gt3x file. In addition, we've added a UI tool that lets you select a .gt3x file and export activity and lux data into CSV or JSON formats.

Testing Tool

The project also includes a .NET 4.0 GUI application built on the GT3X.Parsing.Library that provides a quick way to load .gt3x files and export activity and lux data to CSV or JSON format.

Pre-built releases are found in the release section of this repository.

Tools Used to Prepare Documentation and Library

• MarkdownPad for documentation
• LinqPad for quick C# parsing
• xUnit.net for unit tests
• DotNetZip for easy .NET zip file parsing
• Visual Studio for library creation and testing
• ReSharper for improved productivity in Visual Studio and unit test runner.
• Json.NET for amazing JSON usability in .NET.
• CsvHelper to help write CSV files quickly.