Major Update to Pentair Suntouch, Intelliflo and Intellichlor Protocol document

[secabeen]

Hey there. Almost a decade ago, I made some small contributions to the Google Doc that stored some community knowledge about the Pentair FW 2.X RS485 Protocol. I've been working on a small MQTT repeater for Pentair RS485 messages and I have added a bunch of new information about the protocol, including some corrections to the Pump fields.

I updated the Wiki here for Pumps, but there's also a new chlorinator message and some other minor fixes in the suntouch status messaegs, in case you're interested:

https://docs.google.com/document/d/1M0KMfXfvbszKeqzu6MUF_7yM6KDHk8cZ5nrH1_OUcAc/edit?tab=t.0

[tagyoureit]

Review: Protocol Document vs. njsPC Implementation

Thanks for sharing this updated document — it's a solid reference for the SunTouch + IntelliFlo + IntelliChlor ecosystem. I've compared it against the current njsPC codebase (v9.x) to flag discrepancies, confirm agreements, and note areas where your findings could improve our implementation.

---

Command 0x02 — System Status Message

Byte	Doc Interpretation	njsPC Implementation	Status
[0]	Hours (0-23)	state.time.hours = extractPayloadByte(0)	✅ Match
[1]	Minutes (0-59)	state.time.minutes = extractPayloadByte(1)	✅ Match
[2]	Circuit bitmask (SPA=0x01, AUX1=0x02, AUX2=0x04, AUX3=0x08, FEATURE1=0x10, POOL=0x20, FEATURE2=0x40, FEATURE3=0x80)	processSunTouchCircuits() — maps bit positions to IDs with same semantics	✅ Match
[3]	FEATURE4 = bit 0 (0x01)	Byte 3 bit 0 → id 10 (Feature 4)	✅ Match
[9]	Mode mask: 0x01=Run/Service, 0x04=F/C, 0x08=Freeze, 0x10=Timeout	mode = byte & 0x81, units = byte & 0x04, freeze = byte & 0x08	⚠️ Partial — njsPC uses 0x81 mask for mode (bits 0+7), which captures Service mode + one other flag. Your doc says 0x01 is Run/Service and 0x10 is Timeout — njsPC captures bit 7 (0x80) but not bit 4 (0x10 Timeout). May be worth investigating what bit 7 represents.
[10]	"0x0f if heater on; 0x03 if heater off; 0x00 if heater disabled"	njsPC decodes this as a bitmask with individual heat status bits per body: bit 0x04=pool heater active, bit 0x08=spa heater active, bit 0x10=pool solar active, bit 0x20=spa solar active	⚠️ Different model — your doc treats byte[10] as a single-value indicator while njsPC treats it as a bitmask. njsPC's approach is more granular and handles dual-heater/solar scenarios. Your values (0x0f, 0x03) are consistent with multiple bits being set in the bitmask model (0x0f = bits 0-3 all set).
[12]	Delay bits: 0x02=DELAY on POOL, 0x04=DELAY on AUX2. "Bits 0x30 appears to be on all the time"	state.delay = byte & 63 (lower 6 bits as numeric delay value)	⚠️ Different model — njsPC interprets the lower 6 bits as a numeric delay indicator. Your bitmask interpretation is interesting — the 0x30 "always on" observation might be worth confirming whether it's signal or noise.
[14]	Water Temperature	state.temps.waterSensor1 = fnTempFromByte(byte)	✅ Match
[15]	SPA temperature	Used for body 2 (spa) sensor on dual-body systems	✅ Match
[16]	Major FW version (0x01 on 1.0, 0x02 on 2.070)	Used at init for controller model identification	✅ Match
[17]	Minor FW version (0x00 on 1.0, 0x46=70 on 2.070)	Used at init for controller model identification	✅ Match
[18]	Air Temperature	state.temps.air = fnTempFromByte(byte)	✅ Match
[19]	Solar Temperature	state.temps.solar = fnTempFromByte(byte)	✅ Match
[22]	Heat setting: low 2 bits=pool mode, next 2 bits=spa mode	Pool: byte & 0x33, Spa: (byte & 0xCC) >> 2	⚠️ Extended — njsPC uses wider bitmasks (0x33 and 0xCC instead of just 0x03 and 0x0C) to capture hybrid heater mode bits. Your "0 off, 1 heater, 2 solar pref, 3 solar" is correct for the low-order bits but doesn't account for hybrid modes that use the upper bits in newer firmware.

Summary for 0x02: The core fields (time, temps, circuits) all match perfectly. The differences are in byte[10] (heat status) and byte[22] (heat mode) where njsPC uses a more granular bitmask model that supports hybrid/multi-heater setups. Your simpler interpretation may be entirely correct for SunTouch-only systems without hybrid heaters.

---

Command 0x86 — Circuit Status Change Request

Field	Doc	njsPC	Status
Circuit codes: SPA=0x01, AUX1=0x02, AUX2=0x03, AUX3=0x04, FEATURE1=0x05, POOL=0x06, FEATURE2=0x07, FEATURE3=0x08, FEATURE4=0x09, HEAT_BOOST=0x85	These are the outbound command IDs	njsPC's SunTouchBoard.setCircuitStateAsync() remaps internal IDs → wire IDs: id 7→5, id>6→id-1, then sends Action 134 (0x86)	✅ Match (with ID remapping)
Data byte 2: 0x01=on, 0x00=off	State byte	payload: [mappedId, val ? 1 : 0]	✅ Match

---

Command 0x07 — Pump Status (IntelliFlo)

This is where I found the most significant discrepancies:

Byte	Doc Interpretation	njsPC Implementation	Status
[0]	Pump Running: 0x0a=Started, 0x04=Stopped	pump.command = byte	✅ Match (values align with observed data)
[1]	Pump Mode: 0x00=Filter, 0x01=Manual, 0x02=Backwash, 0x06=Feature 1, 0x09-0x0c=Ext Program 1-4	pump.mode = byte	✅ Match
[2]	Pump State: 0x02=Running, 0x01=Priming, 0x04=System Priming, 0x00=Fault	pump.driveState = byte	✅ Match
[3]–[4]	Power, watts = [3]×256 + [4]	pump.watts = byte[3]*256 + byte[4]	✅ Match
[5]–[6]	Speed, RPM = [5]×256 + [6]	pump.rpm = byte[5]*256 + byte[6] (if VS/VF/VSF type)	✅ Match
[7]	Flow GPM (VF/VSF only; 0 on plain VS)	pump.flow = byte (if maxFlow > 0)	✅ Match
[8]	Filter percent USED (not remaining). "Read 100 during Filter Error"	pump.ppc = byte — njsPC calls this "ppc" with a code comment: "I think this is actually the filter % for vf and vsf. Pump Pressure determines how much backpressure."	✅ Confirms njsPC's speculation — your observation that it reads 100 during a Filter Error nails the semantics. njsPC doesn't currently act on this value beyond storing it.
[9]	Unknown (always 0)	Not decoded — njsPC skips bytes 9-10 entirely	⚠️ njsPC doesn't read this byte at all
[10]	Pump Error: 0x00=OK, 0x02=Filter Error	Not decoded — njsPC skips bytes 9-10	❌ Missing in njsPC — this is valuable new information. We currently have no pump error byte decoded.
[11]–[12]	Time remaining, hh:mm ([11]=hours, [12]=minutes). "Backwash showed 00:05 counting down"	pump.status = byte[11]*256 + byte[12] — njsPC treats this as a 16-bit error/status code (mapped to pumpStatus valueMap: 0=Off, 1=Ok, 2=Filter warning, 3=Overcurrent, etc.)	❌ Conflict — This is the biggest discrepancy. njsPC interprets [11]-[12] as a combined 16-bit error code, but your evidence shows these are hours:minutes of time remaining (confirmed by watching backwash countdown). If you're correct, njsPC's pump status error detection from these bytes would be misinterpreting time values as error codes.
[13]–[14]	Clock hours:minutes (controller time)	pump.time = byte[13]*60 + byte[14] — njsPC interprets as "time" (total minutes)	⚠️ Reinterpretation needed? — njsPC calls this "time" but treats byte[13] as multiplied by 60 (as if it were hours). Your doc says this is the controller clock (hh:mm), which is consistent with njsPC's math but the semantics differ: njsPC thinks it's elapsed/remaining time while you identify it as the current clock time echoed by the pump.

Key findings for Pump 0x07:

1. Byte [10] = Pump Error is new information not currently decoded in njsPC — we should add this.
2. Bytes [11]-[12] interpretation conflict is significant. Your "time remaining hh:mm" with the backwash countdown evidence is compelling. If correct, it means njsPC's pump.status field has been misinterpreting timer data as error codes for some time. The fact that backwash shows 00:05 counting down is strong evidence.
3. Byte [8] semantics confirmed — "filter percent used" (100 = error state) validates the existing speculation in our code.

---

Command 0x05 — Clock/Calendar Broadcast

Byte	Doc	njsPC	Status
[0]	Hours (0-23)	state.time.hours = byte	✅ Match
[1]	Minutes (0-59)	state.time.minutes = byte	✅ Match
[2]	Day of week (Sun=1, Mon=2, Tue=4, etc. — bitmask)	Commented out in njsPC (// state.time.dayOfWeek)	⚠️ Parsed but unused
[3]	Day of month (1-based)	state.time.date = byte	✅ Match
[4]	Month (1-based)	state.time.month = byte	✅ Match
[5]	Year (last two digits)	state.time.year = byte	✅ Match
[6]	"clock adjust" (always 0)	Not decoded	✅ Both agree it's unknown/unused
[7]	DST (1=Auto, 0=Manual)	sys.general.options.adjustDST = byte === 0x01	✅ Match

---

IntelliChlor — DLE/STX Framing

Aspect	Doc	njsPC	Status
Frame: 10 02 <dest> <cmd> <data...> <checksum> 10 03	DLE/STX framing	testChlorHeader checks for [16, 2] prefix, testChlorTerm checks for [checksum, 16, 3]	✅ Match
Valid dest addresses	Implied: 0x50 (80) = chlorinator	njsPC accepts: 0, 16, 80, 81, 82, 83 (supports up to 4 chlorinators + controller addresses)	✅ Compatible (njsPC supports more addresses)
Checksum	Sum mod 2^16 implied?	checksum % 256 (mod 256, single byte)	⚠️ Your doc doesn't specify clearly, but njsPC uses mod 256. Worth confirming.

Command Reply 0x12 — Chlorinator Status

Byte	Doc	njsPC	Status
[0]	Salinity PPM = byte × 50 (e.g., 0x3A=58 → 2900 PPM)	cstate.saltLevel = byte * 50	✅ Match
[1]	Status/error: 0x00=OK, 0x01=No Flow, 0x02=Low Salt, 0x04=High Salt, 0x90(144)=Clean/Inspect Cell	cstate.status = byte & 0x7F (strip high bit). ValueMap: 0=Ok, 1=Low Flow, 2=Low Salt, 3=Very Low Salt, 4=High Current, 5=Clean Cell, 6=Low Voltage, 7=Water Temp Low, 8=Communication Lost	❌ Conflict in status values — see below

Chlorinator status value differences:

Value	Doc says	njsPC says
0x00	OK	Ok
0x01	No Flow	Low Flow
0x02	Low Salt	Low Salt
0x04	High Salt	High Current (val 4)
0x90 (144)	Clean/Inspect Cell	Clean Cell (val 5 after stripping high bit: 0x90 & 0x7F = 0x10 = 16??)

Important note on chlorinator status: The discrepancy suggests the status byte may be a bitmask (your interpretation: individual bits for different faults) rather than an ordinal enum (njsPC's interpretation: sequential values 0-8). Both can't be correct for all cases. njsPC's & 0x7F mask strips bit 7 before lookup, which handles the 0x90 case poorly (0x90 → 0x10 = 16 = unmapped). This is worth investigating further with captures.

---

Items in the Doc That njsPC Already Handles Well

• ✅ Protocol byte (0x00 for pump, 0x01 for automation) — correctly routed
• ✅ Station addresses (0x10=controller, 0x48=QuickTouch remote, 0x60=pump) — correct in address handling
• ✅ SunTouch firmware version detection — bytes [16]-[17] used for model identification
• ✅ SunTouch circuit state handling including the "twisted" bit mapping (bit 4→Feature1, bit 5→Pool)

Items From the Doc That njsPC Is Missing

1. Pump byte [10] — Pump Error code (0x00=OK, 0x02=Filter Error) — not decoded at all
2. Pump bytes [11]-[12] reinterpretation — if these really are "time remaining hh:mm" rather than a 16-bit status code, this is a bug in njsPC
3. Pump byte [13]-[14] clarification — if these are "controller clock echoed by pump" rather than "pump time remaining," semantics need updating

Questions / Requests for Clarification

1. Pump [11]-[12] vs [13]-[14]: Could you share a capture snippet showing the backwash countdown? Specifically interested in seeing [11]-[12] decrement while [13]-[14] show clock time. This would help us confirm whether to re-map pump.status and pump.time.

2. Chlorinator status byte: Is 0x04 definitely "High Salt" on your system? Have you observed this value directly? njsPC has had "High Current" at position 4 for years — wondering if this is a model-specific difference or if we've been wrong.

3. Chlorinator 0x90: When you see 0x90 for "Clean/Inspect Cell," is that the raw byte on the wire? njsPC strips the high bit (& 0x7F) which would give 0x10=16. Have you seen 0x10 without the high bit set for the same condition?

4. Byte [9] "Unknown": You note it's always 0. Have you observed it during any fault conditions? njsPC also doesn't decode it, so any data point would be helpful.

---

Overall Assessment

The document is well-researched and has several findings that could improve njsPC:

• The pump error byte ([10]) is genuinely new information we should incorporate
• The pump timer reinterpretation ([11]-[12]) needs investigation but could fix a long-standing misinterpretation
• The chlorinator status value mapping discrepancy needs resolution with real captures

Thanks for the work on this — especially the Filter Error correlation with byte[8]=100, which confirms a years-old speculation in our codebase.