企业官网建设流程全解析

Flipper Zero 固件 JS SDK：flipper 模块设备信息查询 API（getModel / getName / getBatteryCharge）详解

【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware

本文基于 Flipper Zero 固件官方文档 js_flipper.md，系统讲解 JavaScript SDK 中flipper模块的加载方式、两个只读属性（firmwareVendor、jsSdkVersion）与三个查询方法（getModel()、getName()、getBatteryCharge()）的语义与使用边界，并结合 js_flipper.c 等固件源码逐一对应底层实现，帮助你在 JS 应用中可靠地读取设备型号、海豚名与电量，并避免用厂商/SDK 版本号做功能判断的常见误区。

模块加载与定位

flipper模块是 JS SDK 中用于查询设备信息与属性的内置模块，提供一组只读方法与常量。首次使用前必须通过内置的require函数加载：

let flipper = require("flipper");

从源码结构看，flipper属于固件内置模块注册表。在 js_modules.c 中，modules_builtin数组声明了{"flipper", js_flipper_create, NULL, NULL}，即模块名"flipper"映射到构造函数js_flipper_create；require("flipper")时框架会调用该构造函数生成模块对象并缓存，后续调用直接复用同一实例。require()本身及其余内置方法（delay、print、load等）在 js_builtin.md 中有完整说明。

构造函数 js_flipper_create 会创建一个 JS 对象，并通过JS_ASSIGN_MULTI/JS_FIELD宏一次性挂上 5 个字段：

JS_ASSIGN_MULTI(mjs, flipper_obj) { JS_FIELD("getModel", MJS_MK_FN(js_flipper_get_model)); JS_FIELD("getName", MJS_MK_FN(js_flipper_get_name)); JS_FIELD("getBatteryCharge", MJS_MK_FN(js_flipper_get_battery)); JS_FIELD("firmwareVendor", mjs_mk_string(mjs, JS_SDK_VENDOR, ~0, false)); JS_FIELD("jsSdkVersion", sdk_vsn); }

其中JS_ASSIGN_MULTI与JS_FIELD是 js_modules.h 中提供的对象构建语法糖，MJS_MK_FN将 C 函数包装为可被 JS 调用的原生函数。

只读属性：firmwareVendor 与 jsSdkVersion

firmwareVendor

字符串，表示设备上安装的固件的厂商。官方固件报告值为"flipperdevices"。

实现上，该字段直接取自编译期宏JS_SDK_VENDOR，在 js_modules.h 中定义：

#define JS_SDK_VENDOR "flipperdevices" #define JS_SDK_MAJOR 1 #define JS_SDK_MINOR 0

重要提示（继承自原文档）：不要使用firmwareVendor来判断某项功能是否存在或不存在。正确的做法是使用 SDK 兼容性检查机制，见 SDK compatibility methods。

jsSdkVersion

JavaScript SDK 的版本，类型为一个二元组数组[major, minor]。构造时由JS_SDK_MAJOR/JS_SDK_MINOR两个宏压入数组（js_flipper.c）。当前仓库中该值为[1, 0]；而 TypeScript 声明文件标注这些成员自 JS SDK 0.1 起即可用（@version Added in JS SDK 0.1，见 flipper/index.d.ts），说明版本号会随 SDK 演进，脚本侧不应假设固定值。

与firmwareVendor一样，不要用它做功能探测，而应改用 js_builtin.md 中定义的sdkCompatibilityStatus(major, minor)、isSdkCompatible、checkSdkCompatibility、doesSdkSupport、checkSdkFeatures等内置兼容性方法。这些方法在固件侧对应 js_modules.h 中声明的js_sdk_compatibility_status等原生函数。

方法：getModel()

返回设备型号字符串。

flipper.getModel(); // "Flipper Zero"

底层实现为 js_flipper_get_model：

static void js_flipper_get_model(struct mjs) { mjs_val_t ret = mjs_mk_string(mjs, furi_hal_version_get_model_name(), ~0, true); mjs_return(mjs, ret); }

它调用 HAL 层的furi_hal_version_get_model_name()，该函数按硬件目标分别实现：

• f7（Flipper Zero）目标下返回"Flipper Zero"（与文档示例一致，符号在 f7/api_symbols.csv 中导出）；
• f18 目标下，furi_hal_version_device.c 中实现返回"Flipper Nano"，对应型号代码"FN.1"。

同一套 HAL 接口还被 furi_hal_info.c 用于向 CLI 的property系统输出hardware/model属性，因此 JS 侧读到的型号与系统属性源一致。

方法：getName()

返回虚拟海豚（dolphin）的名字。

flipper.getName(); // "Fur1pp44"

实现见 js_flipper_get_name：

const char* name_str = furi_hal_version_get_name_ptr(); if(name_str == NULL) { name_str = "Unknown"; }

furi_hal_version_get_name_ptr()读取存储在设备版本信息中的用户自定义名字；从源码结构看，当名字尚未设置（返回NULL）时，JS 模块会兜底返回字符串"Unknown"，所以脚本在拿到返回值后可以据此判断海豚名是否已配置。设备侧该名字同样会作为hardware/name属性输出（见 furi_hal_info.c），与桌面端"设备信息"显示的名字同源。

方法：getBatteryCharge()

返回电池电量百分比（数值，0–100）。

flipper.getBatteryCharge(); // 100

实现见 js_flipper_get_battery：

static void js_flipper_get_battery(struct mjs) { Power* power = furi_record_open(RECORD_POWER); PowerInfo info; power_get_info(power, &info); furi_record_close(RECORD_POWER); mjs_return(mjs, mjs_mk_number(mjs, info.charge)); }

调用链清晰可见：通过 Furi 记录机制打开RECORD_POWER（Power 服务单例），调用power_get_info()填充PowerInfo结构（power_get_info的签名void (Power*, PowerInfo*)在 f7/api_symbols.csv 中登记），取出其中的charge字段返回给 JS，随后立即关闭记录。

从源码结构看，Power 服务底层的电量数据来源于 bq27220 电量计芯片：HAL 函数furi_hal_power_get_pct()通过 I2C 获取燃料计状态（state of charge，见 furi_hal_power.c，驱动代码在 lib/drivers/bq27220.c），因此getBatteryCharge()返回的是硬件实测的电量百分比，而非缓存值。

完整示例：在 JS 应用中打印设备信息

结合三个方法与两个属性，一个典型的信息展示脚本如下：

let flipper = require("flipper"); print("Firmware vendor :", flipper.firmwareVendor); print("JS SDK version :", flipper.jsSdkVersion[0] + "." + flipper.jsSdkVersion[1]); print("Device model :", flipper.getModel()); print("Dolphin name :", flipper.getName()); print("Battery charge :", flipper.getBatteryCharge() + "%");

注意两点：

1. print()支持字符串与数字参数（见 js_builtin.md 中print()一节）；
2. 如需在脚本开头做环境自检，请优先使用sdkCompatibilityStatus()/checkSdkFeatures()等内置机制，而不是比较jsSdkVersion的数组值——jsSdkVersion仅用于展示与记录。

TypeScript 类型声明

如果你使用仓库自带的 fz-sdk 包做类型化开发，flipper模块的声明位于 applications/system/js_app/packages/fz-sdk/flipper/index.d.ts：

export declare function getModel(): string; export declare function getName(): string; export declare function getBatteryCharge(): number; export declare const firmwareVendor: string; export declare const jsSdkVersion: [number, number];

该声明文件对firmwareVendor和jsSdkVersion均附有与文档一致的警告注释（不要用它们判断功能存在性，应参考checkSdkFeatures/checkSdkCompatibility），并标注各成员自 JS SDK 0.1 引入，与运行时行为一致。

小结与适用边界

flipper模块所有成员均为只读查询，无副作用、不改变设备状态，可安全地在任意 JS 应用中首次加载模块后随时调用；它是 JS SDK 应用获取设备上下文信息（型号、身份、电量）的标准入口。

【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware