文章目录
-
- [Garmin FIT协议](#Garmin FIT协议)
- [FIT SDK资源](#FIT SDK资源)
- FIT文件类型
- 活动（Activity）文件类型
- 总结
Garmin FIT协议
FIT协议是智能设备穿戴厂商Garmin佳明提出的一种用于存储和共享来自体育、健身和健康设备的数据的文件协议。全称Flexible and Interoperable Data Transfer protocol，灵活互操作数据传输协议，FIT 协议定义了一组数据存储模板（FIT 消息），可用于存储诸如活动数据、课程和训练等信息。
经常使用运动手表的玩家应该都不难理解，FIT就是定义了一种文件协议，用来存储运动数据的，运动手表会采集运动时的速度、心率、海拔、坡度等等信息，一旦采集到数据后就使用FIT协议保存到FIT文件中，有了FIT协议，那么这些数据后续就可以在手表、手机、电脑等等平台上去使用，户外爱好者喜欢为自己的运动视频添加仪表盘，使视频看起来非常酷炫和专业，这其中主要就是通过FIT文件来完成的。
FIT SDK资源
Garmin作为协议发起者，也发布了FIT SDK，FIT SDK包含以下资源：
FIT配置文件
FIT 配置文件（Profile.xls）列出了在 FIT SDK 中所包含的所有预定义的 FIT 消息和 FIT 数据类型。此文档有助于了解消息的内容和格式。对于特定应用的情况，还可以生成自定义消息和文件。Profile.xlsx 每次 FIT SDK 发布时都会进行更新，并且是关于 FIT 说明的最新且最完整的参考文件。Profile.xlsx 的位置为：/fitsdk路径/Profile.xlsx。
FIT CSV 工具
FitCSVTool 是一款命令行工具，用于将二进制的 FIT 文件转换为可读的文本文件。将 FIT 文件转换为文本文件有助于对那些对 FIT 文件进行编码或解码的应用程序进行调试。
Cookbook
FIT SDK Cookbook包含了使用 FIT SDK 解决实际问题的示例。书中有关于编码和解码活动、锻炼和课程文件的步骤；还有使用 FIT SDK 的技巧。这些步骤是用 C#编写的，但其中的概念可以应用于 FIT SDK 的 Java 和 C++ 版本。
编程语言
FIT SDK 支持 C、C++、C#、Java、JavaScript、Objective-C、Python 和 Swift 语言。每个 SDK 都包含示例项目，可供您的项目作为起点使用。
FitGen
FitGen.exe 是一款适用于 Windows 的命令行工具，可用于自定义 FIT SDK。FitGen 可用于向 FIT SDK 添加自定义消息，或者优化 C SDK 以用于嵌入式应用程序。
FIT 开发者论坛
在 FIT 开发者论坛 上分享您的知识、提出问题，并获取最新的 FIT SDK 新闻。
FIT文件类型
FIT SDK 定义了一组数据存储模板，这些模板被称为 FIT 消息，可用于存储诸如传感器数据、路线点、锻炼指令、设备设置等信息。这些消息及其字段定义了数据的结构，而 FIT SDK 提供了序列化和反序列化消息以创建 FIT 文件的工具。
按照设计，FIT SDK 允许将任意组合的消息写入 FIT 文件。实际上，FIT 文件的不同应用会导致基于特定目的对消息进行自然分组。FIT 规范定义了一组常见的文件类型，但并未明确指出每种文件类型应使用哪些消息。本指南的后续部分将介绍最常见的 FIT 文件类型、与每种类型相关的常见消息以及所有类型的通用最佳实践。
本指南中所描述的文件类型均为遵循 FIT 协议的普通 FIT 文件。FIT 文件可能包含超出本指南中所描述的最低或推荐消息之外的其他消息。随着时间的推移，FIT 模型可能会添加新的消息，同时现有消息中也可能添加新的消息字段。请始终参考 FIT 配置文件以获取最新内容。
除非另有说明，文件中未标注时间戳的消息可以以任意顺序出现，而带有时间戳的消息则必须按时间顺序（即时间先后顺序）排列。具体细节请参阅各个文件的定义说明。
FIT文件结构
所有的 FIT 文件具有相同的二进制结构，该结构包括文件头、消息定义、消息以及一个 2 字节的 CRC。FIT SDK 负责创建、序列化和反序列化文件头、CRC 和消息定义；并解决文件与客户端平台之间的本地字节序问题。FIT SDK 还负责消息的序列化和反序列化。
创建 FIT 文件的应用程序只需关注创建相应类型的消息、将数据填充到消息字段中，并将消息传递给 SDK 进行序列化即可。
对于读取 FIT 文件的应用程序，该软件开发工具包会处理对二进制文件数据的反序列化操作，并重建消息。然后，这些消息会传递给客户端应用程序。在大多数情况下，客户端应用程序无需了解消息是如何进行序列化或反序列化的。
有关 FIT 协议、消息定义以及消息的序列化和反序列化方式等更多信息，请参阅本指南中的"FIT 文件协议"部分。
File Id消息
所有的 FIT 文件都必须包含一条"File Id"消息。该"File Id"消息通过"Type"字段来表明 FIT 文件的用途。该"File Id"消息应当是文件中的第一个消息。
| FileIdField | Required | Type | Description |
|---|---|---|---|
| type | Y | file (enum) | File type id |
| manufacturer | Y | manufacturer (enum) | Managed by ANT+. Contact antalliance@thisisant.com for details |
| product | N | UINT16 | Managed by manufacturer |
| product name | N | String | Managed by manufacturer |
| serial number | N | UINT32z | Device serial number, managed by manufacturer. The 'z' indicates that the invalid value for the type is 0 and not 0xFFFFFFFF. |
| time created | Y | date_time | File creation time |
| number | N | UINT16 | File identifier |
常见FIT文件类型
FIT 协议定义了一组常见的文件类型及其各自的作用。每个软件开发工具包（SDK）都会通过枚举或一组常量来定义文件类型标识。
| Type | Name | Description |
|---|---|---|
| 4 | Activity | 记录活跃会话中的传感器数据和事件 |
| 5 | Workout | 描述了一种可设计于计算机上，并能传输至显示设备的结构化活动，该活动能够引导用户完成相关操作。 |
| 6 | Course | 利用一项活动的数据来重现该课程的内容 |
| 文件类型的完整列表在"File"枚举中进行定义。 |
简单来说，以上就是说明了FIT文件由文件头、CRC与消息组成，文件头中包含厂商和时间之类的字段，而主要文件类型有活动（4）、训练（5）和课程（6）三种类型，FIT文件的基本结构就是这样。
活动（Activity）文件类型
当一个人使用其可穿戴设备或骑行计时器来记录自己的活动时，其数据很可能会被存储在 FIT 活动文件中。FIT 活动文件也是网络应用程序接口（API）用于在健身平台之间传输活动数据的常用格式。因此，FIT 活动文件是所有 FIT 文件类型中最常见的。
活动文件用于记录活动日期和时间、运动类型、圈数和分段数据、GPS 路线、传感器数据以及活动期间发生的事件。许多健身设备和应用程序会实时记录活动文件，而其他设备则在活动记录完成后将以专有格式存储的数据导出为 FIT 文件。
请参阅解码活动文件和编码活动文件示例程序部分，以获取有关如何处理活动文件的示例代码。
消息
每份活动文件都必须包含一组特定的消息类型。此外，还有一些消息类型虽然常见但并非必需包含在活动文件中；与所有 FIT 文件一样，活动文件中可以根据需要包含任何有效的消息。
必需消息
以下为活动文件必需的消息。
| Message | Purpose |
|---|---|
| File Id | "File Id"消息是所有 FIT 文件类型所必需的，并且通常应作为文件中的第一条消息出现。对于活动文件，类型属性应设置为 4。文件中的"File Id"消息的顺序以及类型属性有助于在完全解码文件之前快速识别文件类型。"File Id"消息还包含创建该文件的设备或平台的制造商标识和产品标识。制造商标识由佳明分配，每个制造商都定义了自己的产品标识列表。FIT SDK 包含制造商标识列表和佳明产品标识列表。 |
| Activity | 在 FIT 活动文件中，必须包含一条单一的活动消息。该活动消息中包含本地时间戳和会话计数这两个属性。本地时间戳用于确定可以应用于文件中所有时间戳的时区偏移量。大多数设备会实时记录 FIT 文件，而会话计数在录制结束前是未知的。因此，活动消息通常会是文件中的最后一条消息。如果文件被截断或损坏，活动消息可能会缺失，所以在对活动文件进行后期处理时，应尽量减少对活动消息的依赖。 |
| Session | 活动文件将包含一个或多个会话消息。会话消息属于摘要消息类型。所有摘要消息都必须包含"开始时间"、"总耗时"、"总计时器时间"和"时间戳"这四个字段。会话消息定义了近 150 个字段，能够提供与活动相关的信息。这些字段包括开始时间；运动及子运动类型；诸如总时长、距离和海拔升高等摘要值；泳池长度；起始位置；以及 GPS 范围框。会话消息通常会根据设备的特定功能、运动类型以及活动录制过程中使用的传感器而包含其中一部分字段。当用户进行多项运动活动时，活动的每一部分（包括过渡阶段）的摘要数据都会存储在同一个活动文件中的单独会话消息中。 |
| Lap | "圈数消息"代表了会话中的圈数或时间段间隔。圈数消息属于摘要消息类型。对于所有摘要消息，都需要填写"开始时间"、"总耗时"、"总计时器时间"和"时间戳"这四个字段。活动文件每个会话消息应包含至少一个圈数消息，但每个会话消息可能还会包含多个圈数消息，这些圈数消息代表了不同的时间或距离分段。圈数可以由用户手动标记，也可以由记录设备自动标记。圈数消息应是连续且不重叠的，所有圈数消息中总耗时和总距离值的总和应等于相应会话消息的总耗时和总距离值。 |
| Record | 记录信息是将每时每刻的全球定位系统坐标、速度、距离、心率、功率等数值存储在活动文件中的地方。记录信息包含具有一秒分辨率的时间戳，尽管设备可能会以更低的频率存储数据。设备还可能使用智能记录技术，导致记录信息以不固定的间隔被记录下来。记录信息中的数据通常以图表和地图上的轨迹的形式显示给用户。每个记录信息都需要一个时间戳以及至少一个其他值。 |
可选消息
活动文件中可能包含除必需消息之外的其他附加消息。可选消息可能取决于设备的特定功能是否被使用、用户是否正在进行锻炼或遵循课程，或者在记录活动过程中所使用的传感器类型。
这些是活动文件中常见的可选消息类型。活动文件中可能还包含此处未列出的其他消息。
| Message | Purpose |
|---|---|
| Device Info | 设备信息消息用于活动文件中，用于存储有关创建该活动的设备或平台以及其他可能被使用的硬件配件或传感器的信息。设备信息消息可能包含配件的制造商 ID、名称、描述、序列号、软件版本和电池状态等信息。并非所有配件都会报告所有属性。在 FIT 活动文件中包含设备信息消息是一种最佳实践，同时还需提供描述创建活动文件的设备或平台的其他信息。这与文件 ID 消息中的制造商 ID 和产品 ID 值一起使用。对于此设备信息消息，设备索引属性应设置为 0（创建者），应给出制造商 ID，并提供一个易于理解的产品名称。软件版本是可选的，但推荐使用。 |
| Event | 事件消息用于表明在活动录制过程中某一时刻发生了值得注意的事情。事件可以表示计时器何时启动或停止、何时完成了一项锻炼步骤、用户是否偏离了他们所遵循的路线、电子换挡系统的换挡操作，或者像骑手站立或坐下这样的骑行动态事件。事件类型的完整列表在"事件"枚举中定义。 |
| Length | 长度消息用于计轨和计池训练中，用于提供每圈计轨距离或每池游泳距离的汇总信息。长度消息属于汇总消息类型。对于所有汇总消息，起始时间、总经过时间、总计时器时间以及时间戳是必填字段。长度类型字段也是所有长度消息所必需的字段。 |
| Segment Lap | Segment Lap messages are used to mark sections of the route corresponding to predetermined GPS tracks and are typically created by the community for virtual racing. See the Garmin Support Center for more information on segments. Segment Lap is a Summary message type. Start Time, Total Elapsed Time, Total Timer Time, and Timestamp are required fields for all summary messages. |
| User Profile | The User Profile message provides information about the user at the time the activity was recorded. This may include age, gender, weight, height, and resting heart rate. An Activity file should contain a maximum of one User Profile message. The User Profile message does not have a timestamp and can occur at any point in the file. |
| Zone Target | Some sport zone target values are calculated according to user parameters such as maximum or threshold heart rate or power values. Zone Target messages are used to store the current values at the time the activity was recorded. An Activity file should contain a maximum of one Zone Target message. The Zone Target message does not have a timestamp and can occur at any point in the file. |
| Workout | An Activity file may contain Workout and Workout Step messages describing the structured training associated with the activity. An Activity file should contain a maximum of one Workout message. The Workout message does not have a timestamp and can occur at any point in the file. See the Workout File description for more information on Workout messages. |
| Workout Step | When a Workout message is included in an Activity file, one or more Workout Step messages should also be included. The Workout Step messages describe the individual steps that make up the workout. The Workout Step message does not have a timestamp and can occur at any point in the file, however they should be in sequential order. When performing a workout during an activity, the device will typically include a Lap message for each workout step completed, and the Lap message's Workout Step Index field will contain the index in to the list of Workout Step messages associated with the lap. See the Workout File description for more information on Workout Step messages. |
| HR | HR messages contain compressed heart rate samples. HR messages are commonly used by heart rate monitors that use a "store and forward" data recording method. See Decoding Activity Files for an example of how to expand compressed HR data. |
| HRV | HRV messages are used to record heart rate variability data. The HRV messages contain an array of RR intervals and are interleaved with record and event messages in chronological order. Note that HRV data is not timestamped, and shall be synchronized by checking successive RR intervals as they occur between other timestamped messages. |
请参考 FIT 说明文档以获取所有消息及消息属性的完整列表。
活动文件结构
一个活动文件应遵循以下规范：
- 活动文件应包含所有必需的消息。
- 活动文件应包含一条"File Id"消息。
- "File Id"消息应是文件中的第一个消息。
- "Type"属性必须设置为 4（活动）。建议在每个 SDK 中使用相应的枚举或 #define 值。
- "Manufacturer Id"属性必须设置。
- 活动文件应包含一条"Activity"消息。
- 活动文件应包含至少一条"Session"消息。
- 对于单个会话（Session）可以记录多个圈数（Lap）。
- 对于单个圈数（Lap）可以记录多个长度（Length）。
- 所有摘要消息都需要"开始时间"、"总耗时"、"总计时器时间"和"时间戳"字段。
消息序列
活动文件中的消息序列通常遵循以下两种模式之一：先呈现摘要，或者将摘要放在最后。
对于摘要消息在最前面的模式时，所有摘要消息会首先在文件开头集中排列，随后才是诸如"记录"和"事件"这类实时消息。
然而对于摘要消息在最后的模式，此模式下的摘要消息会在活动录制过程中实时写入文件。采用这种模式时，摘要消息则会在其所代表的时间间隔结束时写入文件。
示例消息序列：Summary First模式的活动文件记录
采用Summary First消息序列，单项运动和多项运动活动中的消息顺序是相同的。文件以必需的"File Id"和可选的"Device Info"消息开头。摘要消息按类型分组，首先为"会话"，然后是"圈数"，并按照消息开始时间的顺序排列。在摘要消息之后，实时消息将以升序时间顺序写入文件。
以下是Summary First消息的典型消息序列：
- File Id [1]
- Device Info [1...n]
- Activity [1]
- Session [1...n]
- Lap [1...n]
- Lengths [1...n]
- Records and Event messages interleaved by time stamp [1...n]
在某人参加多项目体育赛事的场景中，该文件可能包含代表赛事各环节以及各环节之间转换的多个部分。
示例消息序列：单项运动的Summary Last模式的活动文件记录
以下是使用Summary Last模式的单项运动活动文件记录的典型消息序列：
- File Id
- Device Info
- Event Timer Start
- Records...
- Lap
- Records...
- Event Timer Stop
- ...gap in time
- Event Timer Start
- Records...
- Event Timer Stop
- Lap
- Session
- Activity
示例消息序列：多项运动的Summary Last模式的活动文件记录
该消息序列与开头具有File Id和Device Info的单会话活动文件类似，随后是事件、记录和圈数消息。在每次活动的每一部分结束时，当前的圈数和会话都会被关闭，并相应消息会被保存到文件中。这种模式会一直持续到活动的最后部分完成。文件以最后的圈数和会话消息结束，然后是活动消息。
以下是采用Summary Last模式的奥运会标准距离铁人三项比赛的典型消息序列：
- File Id
- Device Info
- Event Timer Start
- Records...
- ... 1500 meter swim later
- Lap
- Session - Sport Type Swim
- Records...
- ... few records
- Lap
- Session - Sport Type Transition
- Records...
- ... 40 kilometer bike later
- Lap
- Session - Sport Type Bike
- Records...
- ... few records
- Lap
- Session - Sport Type Transition
- Records...
- ... 10 kilometer run later
- Event Timer Stop
- Lap
- Session - Sport Type Run
- Activity - Session Count = 5
总结
以上内容主要机翻自Garmin FIT SDK的官方文档，比较生硬，但是通过大致浏览可以捕获到几个关键信息，以跑步为示例，可能主要涉及到的就是Activity类型 的FIT文件，Activity类型的FIT文件有File Id、Activity、Session、Lap、Record这5个必须消息 ，还可以包含一系列非必须消息，用于更完整的表达运动过程，活动文件消息的关系参阅上面Activity的文件结构，像平常的一些速度、海拔、心率数据，就包含在最内层的Record消息中，最后也提到了几种典型消息序列，对于普通的跑步运动来说，应该就是最简单的Summary First模式，当然这里只是猜想，后续继续研究一下Activity文件的编解码，来看一下真实的FIT文件到底是啥样的。
FIT协议本身感觉还是比较复杂的，这里不去研究协议，对于应用开发者来说，需要去了解FIT文件类型、消息类型和消息序列，还要学会使用Garmin官方提供的SDK，学会这些应该就足以支撑应用开发了。