X02 · Studio 配置模式——基础文件
- 适用范围:
CORE-S、CORE-M、CORE-HD、SENSE、KEY、AIR-GW(含独立模式)、HUB、VIEW;Air 开关与 Tag 仅作为 AIR-GW 的 endpoints 出现 - 引用的基础文件: X01-ybo-can-protocol.md、
X02-config-schema.md - 状态: 草案 (t)
- 最后更新: 2026-08-28
1. 范围与归属
| 参与方 | 负责 | 绝不做 |
|---|
Studio(P07-studio.md §5) | 唯一的 JSON 模式、bundle、校验(§9)、文档与版本链;模板、虚拟船、生产模式构建清单(P07-studio.md FR-21/22)。Level-1 数值只引用、不重新定义;本文件选定的每个设计值均为 (t) 并列于 §11 | 运行时控制;单独关闭 HD 馈电 / >25 A 决策(P07-studio.md §1) |
Hub(P03-hub.md §9) | 部署端点:验证签名、保存 N 个历史版本、将 bundle 拆分为各节点的 CFG 片段(X01-ybo-can-protocol.md §4)、任一节点 NACK 即原子化中止 | 编辑 bundle;接受未签名、重放或模式降级的 bundle(P07-studio.md FR-25) |
| 节点 | 验证自身片段(签名、模式主版本、能力匹配、额定值与硬件型号 ID 比对——P01-core.md FR-19),带 CRC 存入 NVM,在无 Hub 时执行本地逻辑 | 通过配置提高额定值或脉冲上限(P01-core.md FR-13/FR-19) |
独立模式 AIR-GW(P05-air-gateway.md §9) | 仅对自身承担 Hub 角色:验证并保存经 BLE/Wi-Fi 从 Studio/Mate 收到的自身片段 | 配置任何其他节点(独立套件 = 网关 + 开关,PRODUCT-PLAN.md §6 第 11 项) |
2. 文档模型
bundle.json = { "manifest": {...}, "vessel": {...}, "buses": [...], "nodes": [...], "channels": [...],
"inputs": [...], "bindings": [...], "scenes": [...], "protection_presets": [...],
"alarm_rules": [...], "ac_policy": {...}, "permissions": {...} }
bundle.sig = ECDSA P-256 *(t)* over SHA-256(canonical JSON of bundle.json, RFC 8785 JCS *(t)*)
version chain: v(n).manifest.previous_version_id -> v(n-1).manifest.version_id -> ... (Hub keeps N = 10 *(t), P07 §5)
| 规则 | 定义 | 来源 |
|---|
| 模式版本与身份 | schema_version = major.minor.patch(semver):minor 为向后兼容的新增,major 变更须附带迁移脚本,patch 仅为编辑性修改 (t);bundle_id 为 UUIDv7 (t),version_id 按船体单调递增 | P07-studio.md §5、FR-18 |
| 逐节点哈希 | manifest.node_hashes[node_ref] = 该节点规范化片段的 SHA-256;节点在 STATE/DIAG 中回显(X01-ybo-can-protocol.md §4),使 Studio、Hub、PDF 与交付包比对同一个值 | P07-studio.md FR-17、P02-sense.md FR-24 |
| 签名 | 用户密钥对 bundle_hash 签名;在线时云端附加副署(cloud_countersignature,离线时可选);Hub 与节点用预置密钥验证;单调递增的 version_id 防止重放 | P07-studio.md FR-25 |
| 不可变性 | 已部署版本绝不编辑;每次部署(含回滚)都产生新的 version_id,并设置 previous_version_id,适用时设置 rollback_of | P07-studio.md FR-18/FR-20 |
| 保留 | Hub 保留最近 10 个版本 (t);模块保留最后一个已知良好版本加正在接收的片段(Sense:最近两个,P02-sense.md §9);独立模式 AIR-GW 保留 3 个 (t) | P07-studio.md §5、§10 第 6 项 |
| 回滚与降级 | 回滚即通过完整流水线(§9)重新部署一个已保留版本;部分确认的部署会自动提供回滚;version_id 低于 Hub 当前值、或模式主版本更低且未设置 rollback_of 的均被拒绝(E-MAN-03) | P07-studio.md FR-20/25、P03-hub.md §10 |
3. 对象目录
R = 必填。*_ref 字段保存另一对象的 id,且必须可解析(E-REF-01)。未知字段见 §8。bindings/scenes 详见 §5,protection_presets 见 §4.3,alarm_rules/ac_policy 见 §6,permissions 见 §7。
| 对象 | 字段 | 类型 | R | 约束与说明 |
|---|
manifest | schema_version、bundle_id、version_id、previous_version_id、rollback_of | string、string、int、int、int | 是/是/是/否/否 | version_id > previous_version_id;首次部署无前置版本(§2) |
manifest | created_at、studio_build、author | string | 是 | RFC 3339 UTC;Studio 构建 id;账户 id——不含其他个人数据(P07-studio.md §6) |
manifest | node_hashes、capability_hashes | map | 是 | 每个 nodes[].id 一条;能力哈希在设计时由 §8 的能力块计算 |
manifest | bundle_hash、signature、cloud_countersignature、build_manifest_ref | string、object、object、string | 是/是/否/否 | signature = {alg, key_id, value},alg 为 es256 (t);build_manifest_ref 仅用于生产模式(P07-studio.md FR-22) |
vessel | hull_id、name、system_voltage | string、string、enum | 是 | hull_id 在账户内唯一;system_voltage ∈ {12, 24} V,工作范围 9–32 V(PRODUCT-PLAN.md §1) |
vessel | boat_type_template、template_version | string | 否 | 经校验的模板列表(P07-studio.md FR-07);用户模板在 P7-4 之前仅保存在本地 |
vessel | destination_profile、install_mode | enum | 是 | eu、us、…… 依 COMPLIANCE-MATRIX.md,用于过滤无线电允许列表(§8);install_mode ∈ {system, standalone_air}——standalone_air = 恰好一个 AIR-GW,无其他节点类别(G-15) |
buses | id、kind、bit_rate | string、enum、object | 是 | kind ∈ {ybo_can, n2k, rs485};ybo_can 仲裁段 500 kbit/s、数据段 2 Mbit/s (t)(X01-ybo-can-protocol.md §1);n2k 250 kbit/s;rs485 9600–115200 bit/s,每条总线一个速率(P04-ac-interface.md §6) |
buses | termination_nodes | array | ybo_can | 恰好 2 个节点引用;拓扑检查依 X01-ybo-can-protocol.md §1 |
buses | master_ref、poll_cycle_s | string、number | rs485 | 主站仅限 HUB 或 CORE-HD(P06-key.md FR-15);poll_cycle_s 由 Studio 计算(G-10) |
nodes | id、class、uid、node_id | string、enum、string、int | 是/是/是/否 | class ∈ {CORE-S, CORE-M, CORE-HD, SENSE, KEY, AIR-GW, HUB, VIEW};64 位出厂 UID 十六进制;node_id 1–200,在每条 ybo_can 总线内唯一,0 = 未分配(X01-ybo-can-protocol.md §2) |
nodes | hw_variant、fw_min、bus_refs | string、string、array | 是 | 来自能力块;额定值由型号锁定(P01-core.md FR-19);CORE-S 2 路 CAN,CORE-M 3 路,CORE-HD 2 路 CAN + rs485,AIR-GW ybo_can + n2k + rs485(PRODUCT-PLAN.md §P1/§P5) |
nodes | mode、endpoints | enum、array | AIR-GW | mode ∈ {system, standalone},须显式指定、绝不自动检测(P05-air-gateway.md §10);endpoints[] = {uid, kind, keys, profile},≤32 个开关 / 128 个按键,≤64 个 Tag(P05-air-gateway.md FR-08) |
nodes | modbus_address、n2k_instance | int | 按型号 | KEY RS-485 型号为 1–247;SENSE N2K 配置的 N2K 设备实例 |
channels | id、node_ref、index、type | string、string、int、enum | 是 | index < 能力块通道数;type 依 §4.1 且须在该通道能力 types 之内(G-06) |
channels | circuit | object | 是 | {name, zone, load_type, nominal_a, inrush_a, conductor_mm2, conductor_len_m, domain};domain ∈ {dc, ac_control}(P07-studio.md FR-01) |
channels | critical、default_state | bool、enum | 是 | default_state ∈ {on, off, hold};关键通道默认 on,除非安装商覆盖并记入审计日志(P01-core.md FR-07;G-01) |
channels | protection_ref 或 protection、upstream_protection | string 或 object、object | 是 | 预设引用或内联的 §4.3 对象(内联需安装商覆盖,P07-studio.md FR-04);{device, rating_a, declared}——declared=false 时打印"UPSTREAM PROTECTION NOT DECLARED"(P07-studio.md FR-06;G-12) |
channels | pwm、pulse、half_bridge、coil、relay_out、readback_input_ref | object ×5、string | 按类型 | §4.1 各类型专用块;pulse 与 coil 必须有 readback_input_ref,且解析为 role=readback_aux 的 di(G-02) |
channels | hd_engineering_review | object | CORE-HD | {reviewer, date, envelope_verified};馈电与 >25 A 负载必填(G-03) |
inputs | id、node_ref、index、type | string、string、int、enum | 是 | type ∈ {di, ai};SENSE 8 + 8,CORE-S 13 DI,CORE-M 48 DI + 6 AI + 2 频率 + 2 电流环(PRODUCT-PLAN.md §P1/§P2) |
inputs | label、role | string、enum | 是 | role ∈ {generic, readback_aux, source_presence, transfer_position, tank, temperature, bilge, wake};AC 角色仅限 di(G-09) |
inputs | di、ai、wake_source、sample_ms、alarm_rule_refs | object、object、bool、int、array | 按类型 | §4.2;wake_source 仅限 SENSE/CORE 的 DI(P02-sense.md FR-17);规则在模块上 ≤100 ms (t) 内求值(P02-sense.md FR-08) |
4. 通道与输入类型
4.1 通道类型(channels[].type);回读状态仅由 STATE 呈现:off、on、pending、tripped、locked、bypassed、fault
| 类型 | 允许位置 | 类型专用块 | 语义与固件限制 |
|---|
level | 所有 Core 通道;CORE-HD 重载通道须在已验证包络内 | 无 | 保持型 ON/OFF;STATE 回读 ≤5 s |
pwm | 能力 pwm=true(Core S 15+,Core M 6) | pwm: {min_pct, max_pct, ramp_ms, soft_start_ms, freq_hz} | 调光与软启动(P01-core.md FR-11);照明分区引导至 CORE-S(提示 W-CH-01) |
pulse | 任何具备能力 pulse_max_on_ms 的 Core 通道 | pulse: {width_ms, reactuation_s, mismatch_alarm_n, daily_limit} | width_ms 50–1000 且 ≤ pulse_max_on_ms(P01-core.md FR-13);AC 模板默认最小 100 ms (t)(P04-ac-interface.md §5);reactuation_s ≥12;mismatch_alarm_n = 3 (t);重试前先回读 |
half_bridge | 仅 CORE-M(6) | half_bridge: {pair_index, travel_ms, current_limit_a} | 执行器(P07-studio.md FR-03);G-06 |
coil | inductive_rated=true 的 Core 通道 | coil: {maintained, hold_a, inrush_a, deenergised_default} | AC 接触器 / 分励脱扣;续流二极管在 AC 板上(P01-core.md FR-12);hold_a ≤ 通道额定值的 50 % (t)(P04-ac-interface.md §5) |
relay_out | SENSE(1) | relay_out: {pattern, latch, ack_timeout_s} | pattern ∈ {maintained, pulsed};默认失电(P02-sense.md FR-11) |
| 类型 / 配置 | 字段 | 约束 | 来源 |
|---|
di | contact(to_gnd、to_bat)、invert、debounce_ms、eol_resistor_ohm、pulse_count、wire_break_detect | debounce_ms 1–1000 (t);断线检测需要 eol_resistor_ohm | P02-sense.md FR-06/07 |
ai / sender_profile: resistive | r_min_ohm、r_max_ohm、curve(≤12 点 (t))、open_ohm、short_ohm | 0–190 Ω 与 10–180 Ω;240–33 Ω 与 0–310 Ω (t),待 P2 #1 决定;开路 > 1 kΩ (t),短路 < 2 Ω (t) | P02-sense.md FR-02/03/22 |
ai / sender_profile: v_0_5 | v_min、v_max、scale、unit、hysteresis | 仅限自带信号调理的变送器 | P04-ac-interface.md FR-13 |
ai / sender_profile: ma_4_20 | ma_min、ma_max、scale、unit、hysteresis、wire_break_ma、over_range_ma | 默认 3.6 mA / 21 mA(NAMUR NE 43 (t)) | P02-sense.md FR-04 |
ai / sender_profile: frequency | pulses_per_unit、unit | 仅限 CORE-M 频率输入 | PRODUCT-PLAN.md §P1 |
4.3 保护字段(protection_presets[] 与内联 channels[].protection)
| 字段 | 类型 | 约束 | 说明 |
|---|
id、name | string | 仅预设 | 按模板经校验的预设库 |
trip_current、trip_curve | number(A)、enum | ≤ 能力块中的通道最大额定值且 ≤ 导线载流量(G-04);曲线 ∈ {fast, standard, motor, lamp} (t) | P01-core.md FR-03 |
inrush_window、max_conduction_ms | object、int | {multiplier, ms},multiplier ≤ 硬件浪涌包络;max_conduction_ms 仅用于 pulse,≤ 固件上限、绝不提高上限 | P01-core.md FR-13 |
retry、overtemp_action、shed_priority | object、enum、int | {count, backoff_ms},硬短路时绝不连续重试;trip 或 derate;优先级低者先卸载 | P01-core.md FR-06/FR-22 |
5. 绑定、场景与自动化
5.1 bindings[] 与 scenes[]
| 字段 | 类型 | R | 约束 |
|---|
id、kind | string、enum | 是 | keypad_key、wireless_key、scene、automation、n2k_switch、modbus_target |
source | object | 是 | keypad_key:{node_ref, key};wireless_key:{gateway_ref, switch_uid, key};automation:{task_id, origin: mate, action},action 取自白名单 {set_level, run_scene, request_source, shed_feed, notify} (t)(P08-mate.md 自动化行,G-05);scene:{trigger_binding_ref} |
gesture | enum | 是 | Key:press、hold、long_press(≥1 s);Air:short、hold(≥500 ms)、double——上限三种(P07-studio.md FR-10) |
semantics | enum | 是 | toggle、momentary、dimmer、scene、interlock_group、helm_lock;Air 仅限 toggle、dimmer、scene |
target | object | 是 | {channel_ref} 或 {scene_ref};n2k_switch:{bank_instance, channel}(PGN 127502 / 127501);modbus_target:{bus_ref, register, readback_register} |
options、nvm_target | object、enum | 否/是 | {group_id}(互锁)、{ramp_ms}(调光)、{momentary_timeout_ms}(P06-key.md FR-05);nvm_target ∈ {core, keypad, gateway},编译后的表在部署后回读(P07-studio.md FR-12) |
scenes[] | object | — | {id, name, steps: [{channel_ref, level_pct, delay_ms}], critical_off_override: {installer, date}};有序;将 critical=true 通道设为 0 % 的步骤需要该覆盖(G-01) |
5.2 作为校验约束的护栏
| 代码 | 约束(除另有说明外,违反即部署失败) | 来源 |
|---|
| G-01 | 关键回路规则:critical=true 通道若其绑定仅为 wireless_key 或 automation,则需 ≥1 个 keypad_key 绑定或一条有文档记录的旁路路径;场景步骤设为 0 % 需要 critical_off_override | P07-studio.md FR-10/11、P05-air-gateway.md FR-24 |
| G-02 | type=pulse 或 type=coil 缺少可解析为 role=readback_aux 的 di 的 readback_input_ref | P04-ac-interface.md §10 |
| G-03 | 映射规则:circuit.nominal_a > 25 A 或 load_type=feed 在 CORE-S/CORE-M 上被拒绝;在 CORE-HD 上要求 hd_engineering_review.envelope_verified=true,否则该通道必须为驱动外部接触器的 coil——绝不自动分配;在 P1-4 关闭之前,load_type ∈ {charger, bidirectional} 在任何通道上均被拒绝 | PRODUCT-PLAN.md §P1 拓扑、P07-studio.md FR-02、P01-core.md FR-16 |
| G-04 | trip_current > ampacity(conductor_mm2, conductor_len_m):阻止;仅当能力块报告 hw_max_trip_jumper=true 时降为提示 W-PR-01(P1-8) | P07-studio.md FR-05 |
| G-05 | automation.action 不在白名单枚举内 | P08-mate.md 自动化行 |
| G-06 | type 不在通道能力内:pwm=false 上使用 pwm/dimmer,half_bridge 在 CORE-M 之外或未配对,coil 缺少 inductive_rated=true 或 deenergised_default=false | P07-studio.md FR-03、P01-core.md FR-12 |
| G-07 | type=pulse 的 width_ms 超出 50–1000 或 > 能力 pulse_max_on_ms,或 reactuation_s < 12 | P07-studio.md FR-08 |
| G-08 | 节点无能力块,或 schema_version.major 超出其支持范围 | P07-studio.md §5 发现 |
| G-09 | AC 角色(readback_aux、source_presence、transfer_position)用于 ai;SENSE 的 ai 标签为 AC current/AC voltage;裸 CT 配置 | P02-sense.md FR-10、P04-ac-interface.md FR-13 |
| G-10 | 计算得到的 rs485 poll_cycle_s > 2 s (t)(P04-ac-interface.md FR-17;P05-air-gateway.md §9 写为 2.5 s——以较低值为准) | P07-studio.md FR-14 |
| G-11 | ac_policy 将 feed_class=safety_critical 的馈电、无第 (c) 层 di 的转换路径、或 ssr 设备绑定到自动化 | P07-studio.md FR-15、P04-ac-interface.md FR-08/21 |
| G-12 | upstream_protection.declared=false:PDF 上给出警告 W-CH-02,允许部署 | P07-studio.md FR-06 |
| G-13 | install_mode=standalone_air 缺少 ≥1 个 n2k_switch 或 modbus_target 绑定,或存在任何非 AIR-GW 节点 | P07-studio.md FR-13 |
6. 报警规则与 AC 策略对象
| 对象 | 字段 | 约束 |
|---|
alarm_rules[] | id、node_ref、source_ref(输入或通道)、condition ∈ {gt, lt, eq, mismatch, wire_break, heartbeat_lost}、threshold、hysteresis、debounce_ms、severity ∈ {notice, warning, critical}、latching、actions(relay_out_ref、buzzer、bus_alarm)、survives_hub_loss(计算得出:节点 ∈ {CORE-*, SENSE, AIR-GW}) | 数量 ≤ 能力 rule_capacity(E-ALM-01);mismatch 将 channel_ref 与其 readback_input_ref 配对,5 s 后触发(P02-sense.md §10);AC 安全规则(shore_loss、gen_no_output、contactor_mismatch)仅绑定 di(P07-studio.md FR-09) |
ac_policy | source_priority(有序,默认 [shore, generator, inverter])、transfer_delay_s、load_shed_order(馈电引用)、inverter_windows({soc_min_pct, solar_w_min, hours})、quiet_hours、feeds[]({id, channel_ref, feed_class, link_loss_behaviour})、modbus_map[]({bus_ref, address, model, register_block, poll_s})、transfer_pairs[]({contactor_a_ref, contactor_b_ref, position_input_refs}) | feed_class ∈ {comfort, automated, safety_critical};link_loss_behaviour ∈ {hold, shore_only},待 P4-8 决定;每个 automated 馈电都有一个 readback_aux 输入(G-02/G-11);Modbus 丢失 → 手动 + 报警属固件行为,不可配置(P04-ac-interface.md FR-18) |
7. 权限与角色
| 角色 | 在 bundle 中的范围 | 规则 |
|---|
installer | 全部对象;设置 permissions.installer_locked[](JSON 指针) | 覆盖操作(内联保护、关键通道默认 off、场景关键回路关断、G-04 跳线提示)记录于 permissions.overrides[] = {pointer, by, at, reason} 并记入审计日志;授权模型尚未定(OPEN-QUESTIONS.md P7-1),字段形态在 P07-studio.md FR-23 冻结前为 (t) |
owner | channels[].circuit.name、scenes、pwm 级别、非关键 bindings | 不得触碰 protection*、critical、default_state、ac_policy、pulse、coil 或任何已锁定指针(E-PRM-01) |
crew、charter_guest | 仅运行时(P08-mate.md):permissions.runtime_exposure 列出这些角色可操作的 comfort 类 channel_refs/scene_refs;charter_guest 为只读加舒适类 | 执行由 Hub/Mate 与 Core 舵位锁负责(P06-key.md FR-07);bundle 仅声明暴露范围 |
8. 能力发现
node -> Hub (DIAG, X01 §4) -> Studio:
capability = { product, hw_variant, fw_version, schema_supported: {min_major, max_major},
channels: [{index, max_a, types, pwm, half_bridge, pulse_max_on_ms, inductive_rated, hw_max_trip_jumper}],
inputs: {di: n, ai: n, ai_modes: [...], freq: n, current_loop: n},
binding_table_version, rule_capacity, nvm_bytes, radio_allow_list: [...] (AIR-GW only) }
capability_hash = SHA-256(canonical capability) -> manifest.capability_hashes[node_ref]
| 规则 | 定义 |
|---|
| 协商 | Studio 仅提供能力块允许的内容(P07-studio.md §5);部署时 Hub 重新计算每个哈希——不匹配(设计后硬件或固件已变更)即以 E-CAP-01 中止并提示重新校验 |
| 未知字段 | 同一主版本:节点忽略未知可选字段,仅在 nvm_bytes 允许时以不透明方式保留于 NVM,否则丢弃并报告 W-CFG-01;Hub 拒绝未知的顶层对象(E-SCH-02);Studio 绝不输出目标能力块中不存在的字段 |
| 无线电允许列表 | AIR-GW 发布已签名的频段/配置允许列表;Studio 不提供列表之外的频段(P05-air-gateway.md FR-14) |
| 厂商固件 Core | 当厂商 Core 节点仅暴露子集时(PRODUCT-PLAN.md §6 第 1b 项),其能力块声明该子集及依 X01-ybo-can-protocol.md §8 的网关节点映射 |
9. 部署流程与校验流水线
Studio (PWA, IndexedDB) --validate--> sign --HTTPS (boat LAN) | Mate relay (mTLS MQTT)--> Hub
Hub: verify sig + version_id + schema major -> split per node -> CFG fragments on YBO-CAN (X01 §4)
node: verify fragment, check capability/ratings, ACK (<=100 ms), apply, echo node_hash in STATE/DIAG
Hub: all nodes confirmed inside 5 s -> version active; any NACK/timeout -> atomic abort, last known-good
stays active, rollback offered (P03 §10, P07 FR-20)
Standalone AIR-GW: Studio/Mate --BLE | Wi-Fi (local AP / mTLS cloud)--> gateway verifies and stores its own
fragment; bindings written to gateway NVM and read back; n2k_switch / modbus_target confirmed via
PGN 127501 / read-back register (P05 FR-04/05)
Offline PWA: cached schema fragments + project + capability blocks; local deploy to Hub; backup, audit and
cloud countersignature queued until a link returns; session lifetime bounded *(t)* (P7-3)
| 阶段 | 检查项 | 失败类别 |
|---|
| 1 模式 | 由本目录生成的 JSON Schema draft 2020-12 (t):类型、枚举、必填字段、引用解析 | E-SCH-*、E-REF-*,附字段级消息(P07-studio.md §9) |
| 2 语义 | 护栏 G-01–G-13、能力匹配、NVM/规则容量、按 nvm_target 编译绑定表、角色/锁定规则 | E-* 阻止;W-* 警告 |
| 3 合理性 | 线径与脱扣值(G-04)、RS-485 轮询预算(G-10)、按节点数计算的 YBO-CAN 总线负载(X01-ybo-can-protocol.md §6)、AC 密集型船只的输入数量预算(P04-ac-interface.md §6)、未分配回路 / 未使用通道清单 | 按各代码规定阻止或提示 |
| 4 确认与回读 | 展示语义差异并显式确认,随后签名;逐节点哈希回显与 STATE 呈现;PDF / 交付包仅从已确认版本生成并携带 node_hashes;虚拟船在伪造能力块与 STATE 的模拟器上运行同一流水线(P07-studio.md FR-21) | P07-studio.md FR-16–19 |
10. 示例
Core S 通道(沙龙灯,PWM)配 Key 8 切换与调光绑定:
json{
"channels": [{
"id": "ch_saloon_lights", "node_ref": "core_s_1", "index": 7, "type": "pwm",
"circuit": {"name": "Saloon lights", "zone": "saloon", "load_type": "lighting_led", "nominal_a": 2.5,
"inrush_a": 6, "conductor_mm2": 1.5, "conductor_len_m": 8, "domain": "dc"},
"critical": false, "default_state": "off", "protection_ref": "pp_lamp_5a",
"upstream_protection": {"device": "zone_feed_fuse_F3", "rating_a": 30, "declared": true},
"pwm": {"min_pct": 5, "max_pct": 100, "ramp_ms": 800, "soft_start_ms": 200, "freq_hz": 400}
}],
"protection_presets": [{
"id": "pp_lamp_5a", "name": "LED lighting 5 A", "trip_current": 4.0, "trip_curve": "lamp",
"inrush_window": {"multiplier": 3, "ms": 50}, "retry": {"count": 2, "backoff_ms": 2000},
"overtemp_action": "trip", "shed_priority": 3
}],
"bindings": [
{"id": "b_key8_helm_k3", "kind": "keypad_key", "source": {"node_ref": "key8_helm", "key": 3},
"gesture": "press", "semantics": "toggle", "target": {"channel_ref": "ch_saloon_lights"}, "nvm_target": "core"},
{"id": "b_key8_helm_k3_dim", "kind": "keypad_key", "source": {"node_ref": "key8_helm", "key": 3},
"gesture": "hold", "semantics": "dimmer", "target": {"channel_ref": "ch_saloon_lights"},
"options": {"ramp_ms": 1500}, "nvm_target": "core"}
]
}
AC 热水器回路,采用 2P 自锁继电器(脉冲),辅助触点回读接入 Sense,并配 mismatch 规则:
json{
"channels": [{
"id": "ch_ac_water_heater", "node_ref": "core_s_1", "index": 20, "type": "pulse",
"circuit": {"name": "AC water heater relay", "zone": "ac_board", "load_type": "latching_relay_coil",
"nominal_a": 0.25, "inrush_a": 0.3, "conductor_mm2": 0.75, "conductor_len_m": 3, "domain": "ac_control"},
"critical": false, "default_state": "hold", "protection_ref": "pp_coil_1a",
"upstream_protection": {"device": "core_s_1_input_breaker", "rating_a": 80, "declared": true},
"pulse": {"width_ms": 200, "reactuation_s": 12, "mismatch_alarm_n": 3, "daily_limit": 100},
"readback_input_ref": "in_wh_aux"
}],
"inputs": [{
"id": "in_wh_aux", "node_ref": "sense_1", "index": 2, "type": "di", "label": "Water heater aux contact",
"role": "readback_aux", "di": {"contact": "to_gnd", "invert": false, "debounce_ms": 50,
"eol_resistor_ohm": 4700, "pulse_count": false, "wire_break_detect": true}
}],
"alarm_rules": [{
"id": "al_wh_mismatch", "node_ref": "sense_1", "source_ref": "in_wh_aux", "condition": "mismatch",
"threshold": null, "hysteresis": null, "debounce_ms": 5000, "severity": "warning", "latching": true,
"actions": {"bus_alarm": true, "buzzer": false}, "survives_hub_loss": true
}],
"ac_policy": {
"feeds": [{"id": "feed_wh", "channel_ref": "ch_ac_water_heater", "feed_class": "automated",
"link_loss_behaviour": "shore_only"}],
"load_shed_order": ["feed_wh"]
}
}
11. 可案头决定的事项
| 决策 | 建议 | 理由 | 冻结门槛 |
|---|
Semver patch、规范化、哈希、JSON Schema 方言、签名 | major.minor.patch(patch 仅编辑性);RFC 8785 JCS + SHA-256;draft 2020-12;ECDSA P-256(es256) | 保持 P07-studio.md §5 的 major.minor 规则;PWA、Hub 与节点间哈希确定一致;校验器成熟;与 MCU 安全引擎匹配 | Studio 模式冻结(P07-studio.md §10 第 6 项);签名在 M3(PRODUCT-PLAN.md §1 MCU 行) |
mismatch_alarm_n 默认值;独立模式 AIR-GW 保留版本数 | 3;3 | P07-studio.md FR-08 写为 3 (t),P04-ac-interface.md FR-11 写为 2 (t)——必须择一,并更新落选的 Level-1 文件;网关保留数受 NVM 限制,无 Hub 时仍可回滚 | Studio 模式冻结;Air EVT(M6–7) |
| RS-485 轮询上限(G-10) | 2 s | P04-ac-interface.md FR-17(2 s)与 P05-air-gateway.md §9(2.5 s);较低值可在 5 s 内保留一次重试 | M3,随 P4-9 |
| 脱扣曲线预设 id 与自动化动作白名单 | fast、standard、motor、lamp;set_level、run_scene、request_source、shed_feed、notify | 覆盖照明、泵/电机、电子设备、P4 策略与 P8 自动化的最小枚举集 | Core EVT 台架;Mate v1 范围冻结 |
| 未知字段保留 | NVM 允许时不透明保留,否则丢弃 + 警告 | 模式 minor 新增无需固件发布即可前向兼容 | Studio 模式冻结 |
12. 变更记录
| 日期 | 变更 | 参考 |
|---|
| 2026-08-28 | 依据 PRODUCT-PLAN §1/§P1/§P4–P8、P07 FR 列表与 §5、P01/P02/P04/P05/P06 的固件与配置章节起草初版基础文件 | PLAN-029 |