加尔明 - FIT JavaScript SDK
FIT SDK 文档
FIT SDK 文档可在 https://developer.garmin.com/fit (英语)。 。 。 .
FIT SDK 开发者论坛
分享你的知识,问问题, 并获得最新的FIT SDK新闻 FIT SDK 开发者论坛。 。 。 .
FIT JavaScript SDK 要求
FIT JavaScript SDK使用ECMAScript模块语法,并需要node.js v14.0或更高,或者一个带有兼容的JavaScript运行时引擎的浏览器.
安装
npm install @garmin-fit/sdk
使用量
import { Decoder, Stream, Profile, Utils } from '@garmin-fit/sdk';
const bytes = [0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00];
const stream = Stream.fromByteArray(bytes);
console.log("isFIT (static method): " + Decoder.isFIT(stream));
const decoder = new Decoder(stream);
console.log("isFIT (instance method): " + decoder.isFIT());
console.log("checkIntegrity: " + decoder.checkIntegrity());
const { messages, errors } = decoder.read();
console.log(errors);
console.log(messages);
解码器
构造器
解码器对象由Streams创建,代表要解码的二进制 FIT 文件数据. 见 创建流 以获取关于构建流对象的更多信息.
一旦创建了解码器对象,就可以用来检查Stream是FIT文件,FIT文件有效,并读取FIT文件的内容.
是FIT 方法
所有有效的FIT文件应当包括一个12或14字节文件头. 14字节标题是首选标题大小和最常用的大小. 标题中的字节8-11包含ASCII值 ".FIT " 。 此字符串在文本或十六进制编辑器中打开二进制 FIT 文件时很容易被发现.
Offset: 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000000: 0E 10 43 08 78 06 09 00 2E 46 49 54 96 85 40 00 ..C.x....FIT..@.
00000010: 00 00 00 07 03 04 8C 04 04 86 07 04 86 01 02 84 ................
00000020: 02 02 84 05 02 84 00 01 00 00 19 28 7E C5 95 B0 ...........(~E.0
IsFIT方法读取文件头并返回真实,如果字节8–11等于ACSII值".FIT". isFIT提供了在试图解码文件之前快速检查文件为FIT文件的方法.
解码器类包括静态和实例版本的isFIT方法.
检查完整性方法
检查完整性方法对一个FIT文件进行三次检查:
- 检查标题中的字节 8-11 是否包含 ASCII 值 ".FIT " .
- 检查文件总大小是否等于标题大小+数据大小+CRC大小.
- 读取文件内容,计算CRC,然后检查计算出来的CRC是否与文件CRC相匹配.
一个文件必须通过所有这些测试,才能被视为有效的FIT文件. 见 IsFIT (), 检查完整性 (), 并读 () 方法配方 用于应使用检查完整性方法的用例,以及最好避免使用的方法.
读取方法
"读取"方法解码出输入流的所有消息,并返回包含解码过程中遇到的一系列错误的对象和按消息类型分组的解码消息词典. 解码过程中遇到的任何例外都会被读取方法所捕捉并被添加到出错的数组中.
"读取"方法接受一个可选选项对象,可以用来自定义字段数据如何在解码后的消息中表示. 所有选项默认启用 。 禁用选项可能会加快文件解码. 也可以根据如何使用已解码的数据启用或禁用选项.
const { messages, errors } = decoder.read({
mesgListener: (messageNumber, message) => {},
applyScaleAndOffset: true,
expandSubFields: true,
expandComponents: true,
convertTypesToStrings: true,
convertDateTimesToDates: true,
includeUnknownData: false,
mergeHeartRates: true
});
mesg 听取者 = (消息号码,消息) => {}
可选的回调功能,在消息被完全解码并全部应用后,可用于检查或操纵消息. 消息是可变的,我们会从消息词典中的Read方法返回.
实例 mesg 听取器调用, 跟踪所有记录信件的字段名称 .
const recordFields = new Set();
const onMesg = (messageNumber, message) => {
if (Profile.types.mesgNum[messageNumber] === "record") {
Object.keys(message).forEach(field => recordFields.add(field));
}
}
const { messages, errors } = decoder.read({
mesgListener = onMesg
});
console.log(recordFields);
应用缩放AndOffset:真 QQ 假
当对原始字段值适用FIT配置中定义的缩放和相抵值时.
{
altitude: 1587 // with a scale of 5 and offset of 500 applied
}
当假用生字段值.
{
altitude: 10435 // raw value store in file
}
扩展子字段: 真 QQ 假
当为FIT配置中定义的字段创建了真子字段时.
{
event: 'rearGearChange',
data: 16717829,
gearChangeData:16717829 // Sub Field of data when event == 'rearGearChange'
}
当虚空子域被省去时.
{
event: 'rearGearChange',
data: 16717829
}
扩展组件:真 QQ 假
当FIT配置中定义的真字段组件被扩展为新字段. 扩展Sub 字段必须设置为真实,以便扩展子字段
{
event: 'rearGearChange'
data: 16717829,
gearChangeData:16717829, // Sub Field of data when event == 'rearGearChange
frontGear: 2, // Expanded field of gearChangeData, bits 0-7
frontGearNum: 53, // Expanded field of gearChangeData, bits 8-15
rearGear: 11, // Expanded field of gearChangeData, bits 16-23
rearGearNum: 1, // Expanded field of gearChangeData, bits 24-31
}
当不扩展假字段组件时 .
{
event: 'rearGearChange',
data: 16717829,
gearChangeData: 16717829 // Sub Field of data when event == 'rearGearChange
}
转换 TypesToStrings: true QQ 假
当真字段值从原始整数值转换为FIT配置中定义的相应字符串值时.
{ type:'activity'}
当假用原始整数值时.
{ type: 4 }
转换 DateTimesToDates: true QQ 假
当将真实的 FIT Epoch 值转换为 JavaScript Date 对象时.
{ timeCreated: {JavaScript Date object} }
当使用 FIT Epoch 值时.
{ timeCreated: 995749880 }
当假的Utils.convertDateTimeToDate方法可能用于将FIT Epoch值转换为JavaScript Date对象.
包括未知数据: 真 QQ 假
当使用字段 ID 作为密钥存储在信件中时 .
{ 249: 1234} // Unknown field with an id of 249
合并HeartRates: true QQ 虚假
当真实自动将HR消息的心率值合并到"记录"消息中时. 此选项需要启用应用 ScaleAndOffset并扩展组件选项 。 当解码信件中没有HR消息时,此选项对记录信件没有效果.
创建流
流对象包含要解码的二进制 FIT 数据. 流对象可以由字节阵列,ArrayBuffers和Node.jsBuffers来创建. 内部流级使用一个矩阵缓冲器来管理字节流.
从字节阵列
const streamFromByteArray = Stream.fromByteArray([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]);
console.log("isFIT: " + Decoder.isFIT(streamFromByteArray));
从矩阵缓冲器
const uint8Array = new Uint8Array([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]);
const streamFromArrayBuffer = Stream.fromArrayBuffer(uint8Array.buffer);
console.log("isFIT: " + Decoder.isFIT(streamFromArrayBuffer));
从节点起跑
const buffer = Buffer.from([0x0E, 0x10, 0xD9, 0x07, 0x00, 0x00, 0x00, 0x00, 0x2E, 0x46, 0x49, 0x54, 0x91, 0x33, 0x00, 0x00]);
const streamFromBuffer = Stream.fromBuffer(buffer);
console.log("isFIT: " + Decoder.isFIT(streamFromBuffer));
从使用 Node.js 的文件中
const buf = fs.readFileSync('activity.fit');
const streamfromFileSync = Stream.fromBuffer(buf);
console.log("isFIT: " + Decoder.isFIT(streamfromFileSync));
用户
Utils对象既包含常数,也包含使用解码消息和字段的工作方法.
FIT EPOCH MS (英语). 常数
FIT EPOCH MS常数代表了Unix Epoch和FIT Epoch之间的毫秒数.
const FIT_EPOCH_MS = 631065600000;
FIT EPOCH MS值可用于将FIT Epoch值转换为JavaScript Date对象.
const jsDate = new Date(fitDateTime * 1000 + Utils.FIT_EPOCH_MS);
转换时间到日期方法
一个将 FIT Epoch 值转换为 JavaScript Date 对象的说服方法.
const jsDate = Utils.convertDateTimeToDate(fitDateTime);