Skip to content

Commit

Permalink
docs: update documentation (#52)
Browse files Browse the repository at this point in the history
  • Loading branch information
@muktihari
muktihari committed Dec 19, 2023
1 parent dcd7496 commit 7d0a8bd
Show file tree
Hide file tree
Showing 2 changed files with 114 additions and 9 deletions.
22 changes: 20 additions & 2 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,33 @@ This SDK is designed with efficiency in mind, but it places a higher priority on

Please see [Usage](/docs/usage.md).

## Protocol Version 2.0 is supported

Version 2.0 introduced [**Developer Fields**](https://developer.garmin.com/fit/cookbook/developer-data) as a way to add custom data fields to existing messages. We strives to support **Developer Fields** and carefully thought about how to implement it since the inception of the SDK. While this may still need to be battle-tested to ensure correctness, this is generally work and usable.

Here is the sample of what **Developer Fields** would look like in a **.fit** that have been converted to **.csv** by `fitconv`. The **device_info** message has some **Developer Fields** defined in **field_description**:

| Type | Local Number | Message | Field 1 | Value 1 | Units 1 | Field 2 | Value 2 | Units 2 | Field 3 | Value 3 | Units 3 | Field 4 | Value 4 | Units 4 | Field 5 | Value 5 | Units 5 | Field 6 | Value 6 | Units 6 |
| ---------- | ------------ | ----------------- | -------------------- | ------- | ------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------- | ---------- | ------- | ------------------- | ------------------- | ------- | ----------------- | ------- | ------- | ------------------ | ------- | ------- |
| Definition | 0 | developer_data_id | developer_data_index | 1 | | application_id | 16 | | application_version | 1 | | | | | | | | | | |
| Data | 0 | developer_data_id | developer_data_index | 1 | | application_id | 32|99|111|109|46|115|116|114|97|118|97|46|105|111|115|32 | | application_version | 40113 | | | | | | | | | | |
| Definition | 0 | field_description | fit_base_type_id | 1 | | developer_data_index | 1 | | field_definition_number | 1 | | field_name | 13 | | | | | | | |
| Data | 0 | field_description | fit_base_type_id | 7 | | developer_data_index | 1 | | field_definition_number | 5 | | field_name | device_model | | | | | | | |
| Definition | 0 | field_description | fit_base_type_id | 1 | | developer_data_index | 1 | | field_definition_number | 1 | | field_name | 20 | | | | | | | |
| Data | 0 | field_description | fit_base_type_id | 7 | | developer_data_index | 1 | | field_definition_number | 4 | | field_name | device_manufacturer | | | | | | | |
| Data | 0 | field_description | fit_base_type_id | 7 | | developer_data_index | 1 | | field_definition_number | 6 | | field_name | device_os_version | | | | | | | |
| Data | 0 | field_description | fit_base_type_id | 7 | | developer_data_index | 1 | | field_definition_number | 7 | | field_name | mobile_app_version | | | | | | | |
| Definition | 0 | device_info | manufacturer | 1 | | product | 1 | | device_model | 11 | | device_manufacturer | 6 | | device_os_version | 5 | | mobile_app_version | 8 | |
| Data | 0 | device_info | manufacturer | 265 | | product | 101 | | device_model | iPhone14,4 | | device_manufacturer | apple | | device_os_version | 16.6 | | mobile_app_version | 332.0.0 |

## CLIs

We provides some CLI programs to interact with FIT files that can be found in `cmd` folder.

1. `fitactivity`: Combines multiple FIT activity files into one continuous FIT activity (and conceal the start and end GPS positions for privacy). [README.md](/cmd/fitactivity/README.md)
2. `fitconv`: Converts FIT file to a CSV file, allowing us to read the FIT file in a human-readable format. [README.md](/cmd/fitconv/README.md)
3. `fitprint`: Print FIT file into stdout in human-readable format. [README.md](/cmd/fitprint/README.md)

Now, the `fitactivity` and `fitconv` programs are automatically built during release; for Linux, Windows, and macOS platforms. They are available for download in [Release's Assets](https://github.com/muktihari/fit/releases).
The programs are automatically built during release; for Linux, Windows, and macOS platforms. They are available for download in [Release's Assets](https://github.com/muktihari/fit/releases).

## Custom FIT SDK

Expand Down
101 changes: 94 additions & 7 deletions docs/usage.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -261,12 +261,12 @@ func main() {
Example:

```go
csvconv := csv.NewConverter(bw)
defer csvconv.Wait()
conv := fitcsv.NewConverter(bw)
defer conv.Wait()
dec := decoder.New(f,
decoder.WithMesgDefListener(csvconv),
decoder.WithMesgListener(csvconv),
decoder.WithMesgDefListener(conv),
decoder.WithMesgListener(conv),
)
```

Expand Down Expand Up @@ -335,7 +335,7 @@ func main() {
fieldnum.FileIdProductName: "Bryton Active App",
}),
factory.CreateMesg(mesgnum.Activity).WithFieldValues(map[byte]any{
fieldnum.ActivityType: typedef.ActivityTypeCycling,
fieldnum.ActivityType: typedef.ActivityManual,
fieldnum.ActivityTimestamp: datetime.ToUint32(now),
fieldnum.ActivityNumSessions: uint16(1),
}),
Expand All @@ -344,8 +344,10 @@ func main() {
fieldnum.SessionAvgCadence: uint8(78),
fieldnum.SessionAvgHeartRate: uint8(100),
}),
// We can use WithFields as well. See factory for details.
factory.CreateMesg(mesgnum.Record).WithFields(
// We can use WithFields as well, see `proto` for details.
// When using WithFields, it's recommended to use CreateMesgOnly to create a mesg with empty fields
// to reduce unecessary alloc since the fields will be replaced anyway, see `factory` for details.
factory.CreateMesgOnly(mesgnum.Record).WithFields(
factory.CreateField(mesgnum.Record, fieldnum.RecordSpeed).WithValue(uint16(1000)),
factory.CreateField(mesgnum.Record, fieldnum.RecordCadence).WithValue(uint8(78)),
factory.CreateField(mesgnum.Record, fieldnum.RecordHeartRate).WithValue(uint8(100)),
Expand All @@ -365,6 +367,91 @@ func main() {

### Encode Common File Types

Example of encoding fit by self declaring the protocol messages but using common File Types building block.

```go
package main
import (
"os"
"time"
"github.com/muktihari/fit/encoder"
"github.com/muktihari/fit/factory"
"github.com/muktihari/fit/kit/bufferedwriter"
"github.com/muktihari/fit/profile/filedef"
"github.com/muktihari/fit/profile/mesgdef"
"github.com/muktihari/fit/profile/typedef"
)
func main() {
f, err := os.OpenFile("NewActivity.fit", os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o644)
if err != nil {
panic(err)
}
now := time.Now()
activity := filedef.NewActivity()
activity.FileId = *mesgdef.NewFileId(nil).
SetType(typedef.FileActivity).
SetTimeCreated(now).
SetManufacturer(typedef.ManufacturerSuunto).
SetProduct(56). // Suunto 5 Peak
SetProductName("Suunto 5 Peak")
activity.Records = append(activity.Records,
mesgdef.NewRecord(nil).
SetTimestamp(now.Add(1*time.Second)).
SetSpeed(1000).
SetCadence(90).
SetHeartRate(100),
mesgdef.NewRecord(nil).
SetTimestamp(now.Add(2*time.Second)).
SetSpeed(1010).
SetCadence(100).
SetHeartRate(110),
)
activity.Laps = append(activity.Laps,
mesgdef.NewLap(nil).
SetTimestamp(now.Add(3*time.Second)).
SetStartTime(now.Add(1*time.Second)).
SetAvgSpeed(1000).
SetAvgCadence(95).
SetAvgHeartRate(105),
)
activity.Sessions = append(activity.Sessions,
mesgdef.NewSession(nil).
SetTimestamp(now.Add(3*time.Second)).
SetStartTime(now.Add(1*time.Second)).
SetAvgSpeed(1000).
SetAvgCadence(95).
SetAvgHeartRate(105),
)
activity.Activity = mesgdef.NewActivity(nil).
SetType(typedef.ActivityManual).
SetTimestamp(now.Add(4 * time.Second)).
SetNumSessions(1)
// Convert back to FIT protocol messages
fit := activity.ToFit(factory.StandardFactory())
bw := bufferedwriter.New(f)
defer bw.Flush()
enc := encoder.New(bw)
if err := enc.Encode(&fit); err != nil {
panic(err)
}
}
```

Example decoding FIT file into common file `Activity File`, edit the manufacturer and product, and then encode it again.

```go
Expand Down

0 comments on commit 7d0a8bd

Please sign in to comment.