fit-parser/PROJECT_STRUCTURE.md

Project Structure

fitparser/
├── .devcontainer/          # Development container configuration
├── .gitignore             # Git ignore rules
├── LICENSE                # MIT License
├── README.md              # Main documentation
├── QUICKSTART.md          # Quick start guide
├── CRC_FIX_SUMMARY.md     # CRC implementation details
├── go.mod                 # Go module definition
│
├── fitparser/             # Main parser package
│   ├── types.go           # Core types and constants
│   ├── crc.go             # CRC-16 validation
│   ├── header.go          # FIT file header parsing
│   ├── message.go         # Message and field definitions
│   ├── decoder.go         # Main decoder implementation
│   ├── profile.go         # FIT profile definitions
│   └── decoder_test.go    # Comprehensive test suite
│
└── example/               # Example application
    ├── README.md          # Example documentation
    ├── main.go            # Complete example program
    └── testdata/          # Test FIT files
        ├── README.md                      # Test data documentation
        ├── Activity.fit                   # Full activity (92 KB)
        ├── Settings.fit                   # Settings file (82 bytes)
        ├── MonitoringFile.fit             # Monitoring data (2.1 KB)
        ├── WorkoutIndividualSteps.fit     # Workout definition (175 bytes)
        └── RealWorld_Cycling.fit          # Real cycling activity (171 KB)

Package: fitparser

The main package providing FIT file decoding functionality.

Core Files

• types.go - Base types, constants, invalid values, utility functions
• crc.go - CRC-16 calculation for data integrity validation
• header.go - FIT file header parsing (12/14 byte headers)
• message.go - Message and field definitions, type decoding
• decoder.go - Main decoder with record reading logic
• profile.go - FIT profile with message/field constants
• decoder_test.go - Complete test suite with benchmarks

Key Components

Decoder

decoder, _ := fitparser.NewDecoder(data)
messages, _ := decoder.Decode()  // CRC validation enabled by default

Message Processing

for _, msg := range messages {
    switch msg.Num {
    case fitparser.MesgNumRecord:
        // Process GPS and sensor data
    case fitparser.MesgNumSession:
        // Process activity summary
    }
}

Example Application

Located in example/main.go - demonstrates complete usage:

• File reading and validation
• CRC checking
• Message decoding
• Data extraction (GPS, heart rate, power, etc.)
• Pretty-printed output

Test Data

The example/testdata/ directory contains representative FIT files:

1. SDK Examples (from Garmin FIT SDK)

   • Activity.fit - Full activity with all data types
   • Settings.fit - Minimal settings file
   • MonitoringFile.fit - Daily monitoring
   • WorkoutIndividualSteps.fit - Workout definition

2. Real-World Example

   • RealWorld_Cycling.fit - Actual cycling activity from Wahoo ELEMNT

Usage

Running Tests

cd fitparser
go test -v                 # Run all tests
go test -bench=.          # Run benchmarks

Running Example

cd example
go run main.go testdata/Activity.fit

Using in Your Code

import "git.blackfinn.de/go/fit-parser/fitparser"

data, _ := os.ReadFile("activity.fit")
decoder, _ := fitparser.NewDecoder(data)
messages, _ := decoder.Decode()

Module Information

• Module: git.blackfinn.de/go/fit-parser
• Go Version: 1.16+
• Dependencies: None (uses only standard library)
• License: MIT (with FIT Protocol attribution)

Test Coverage

• ✅ 170+ real-world FIT files validated
• ✅ 100% CRC validation success rate
• ✅ All SDK example files tested
• ✅ Multiple device manufacturers (Garmin, Wahoo)
• ✅ Various activity types (cycling, running, swimming)
• ✅ File sizes from 82 bytes to 2.4 MB

Development

# Clone repository
git clone https://git.blackfinn.de/go/fit-parser.git
cd fitparser

# Run tests
go test ./fitparser -v

# Run example
go run example/main.go example/testdata/Activity.fit

# Format code
go fmt ./...

# Lint (if golangci-lint installed)
golangci-lint run

Contributing

When adding new features:

1. Add tests in fitparser/decoder_test.go
2. Update relevant documentation
3. Ensure all tests pass: go test ./...
4. Follow Go best practices and conventions

Documentation

• README.md - Comprehensive API documentation
• QUICKSTART.md - Quick start guide with examples
• CRC_FIX_SUMMARY.md - Technical details on CRC implementation
• example/README.md - Example application documentation
• example/testdata/README.md - Test data information