Bus writes & safety

By default HeatSync is read-only on the F1/F2 bus. Reads carry no risk — we’re just listening to packets the unit broadcasts anyway. Writes are different: we’re sending data the heat pump will act on, and getting that wrong could put the system into an unhappy state.

This page documents how the write path works, what guard-rails are in place, and where the responsibility sits.

Master toggle

The single “Allow bus writes” toggle on /config gates everything. With it off:

• The web UI shows write controls but they return 400 "bus writes disabled".
• Home Assistant’s climate entity drops its command topics — HA shows it as read-only.
• The DHW schedule tick is a no-op.

Turn it on once you’ve watched the bus for a while and the readings look sensible.

What we can write

Function	Register	Range	Validation
DHW target	0x4235 VAR_in_temp_water_heater_target_f	30–65 °C	API rejects outside range
DHW power	0x4065 ENUM_in_water_heater_power	on / off	—
DHW mode	0x4066 ENUM_in_water_heater_mode	Eco / Standard / Power / Force	API validates enum
Heating mode	0x4001 ENUM_in_operation_mode	Off / Heat / Cool / Auto	API validates enum; “off” sends power=false
Heating target	0x4202 VAR_in_temp_target_f	5–30 °C	API rejects outside range
Flow target	0x4247 VAR_in_temp_water_outlet_target_f	15–65 °C	API rejects outside range
Water-law offset	0x4248 VAR_IN_TEMP_WATER_LAW_TARGET_F	±5 °C	API rejects outside range
Heating curve (slopes)	0x4254–0x4259 FSV2011–FSV2032	sensible bounds	Per-field range check
Quiet (silence) mode	0x4046 ENUM_in_silence	on / off	—
Fan mode	0x4007 ENUM_in_fan_mode	auto / low / med / high / turbo	API validates enum
Anti-legionella schedule	0x4099 +0x409A +0x4269–0x426B	day / hour / temp / duration	Per-field validation
Room temp (injection)	0x4203 VAR_in_temp_room_f	-10 to 50 °C	Only used when room-temp injection is enabled

Plus internal one-shots that aren’t bus writes per se — DHW boost (+5 °C for 1 h), heating boost (+1 °C for 1 h), Away setback — and the DHW scheduler, which writes dhw-target + dhw-power once per minute when its conditions change.

Writes use Samsung’s standard NASA Request packet type. The unit broadcasts back the new value within a few seconds; HeatSync’s web UI uses an optimistic-update pattern with an ~8 s hold to keep the visual stable across the round-trip.

Bus arbitration

NASA’s F1/F2 is a multi-drop RS485 bus. To avoid colliding with the wired remote or other controllers (a SmartThings MIM gateway, for example), the transmit path waits for 50 ms of quiet before driving the line. If the bus is constantly busy, the write times out at 500 ms and reports a failure.

In practice the bus has 50–500 ms gaps between packets, so writes go through within a tick or two.

Counters and observability

/api/status exposes:

• txCount — total successful writes since boot.
• txBlocked — writes attempted while writesEnabled = false (should always be 0 — UI gates them already).

Failed writes are also logged in the in-RAM event ring (/api/events) with reason — "no indoor seen yet", "bus busy timeout", etc.

What HeatSync won’t write

We deliberately don’t expose:

• FSV (installer-menu) parameters. These are set once at install and changing them wrong can damage the heating system (over-temp flooring, frozen pipes from a low-temp threshold, etc.). HeatSync reads FSVs and shows their current values on /fsv with plain-English explanations, but the only FSV we let you write is the water-law offset (±5 °C, with explicit Samsung-supported limits).
• Compressor frequency / EEV positions / 4-way valve. These are inverter control loops the heat pump’s own firmware runs. Writing them externally would fight the unit and is unnecessary for any domestic use case.
• Bus address takeover. HeatSync doesn’t claim to be a wired remote; it transmits from a passive address. Multiple instances of HeatSync on the same bus would just be two readers + two writers, not a conflict.

What could still go wrong

Even with the guard-rails, things to be aware of:

• Wrong target temperature — setting DHW to 65 °C every day will shorten the lifetime of the cylinder’s anode and your boiler if it’s also providing heat. Pick sensible defaults.
• Mode-switching at high frequency — pinging between Heat and Cool every few minutes is bad for the compressor. The dashboard’s picker has no rate limit; don’t automate something that loops on it.
• Schedule conflicts — if you also have an external scheduler (HA automation, the wired remote’s own schedule, the MIM gateway), and HeatSync’s schedule, the last writer wins. Pick one.

Use the diagnostics page (/diagnostics) and the event log to keep an eye on what’s happening on the bus. If something looks wrong, flip the writes toggle off — HeatSync goes back to read-only immediately.