167 lines
5.0 KiB
Markdown
167 lines
5.0 KiB
Markdown
# 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
|
|
```go
|
|
decoder, _ := fitparser.NewDecoder(data)
|
|
messages, _ := decoder.Decode() // CRC validation enabled by default
|
|
```
|
|
|
|
#### Message Processing
|
|
```go
|
|
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
|
|
```bash
|
|
cd fitparser
|
|
go test -v # Run all tests
|
|
go test -bench=. # Run benchmarks
|
|
```
|
|
|
|
### Running Example
|
|
```bash
|
|
cd example
|
|
go run main.go testdata/Activity.fit
|
|
```
|
|
|
|
### Using in Your Code
|
|
```go
|
|
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
|
|
|
|
```bash
|
|
# 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
|