# Property of PMA Electrical Solutions, LLC.
#
# Eaton S811+ SOFT STARTER — not a VFD. Native Modbus RTU on the unit's own
# comms terminal block (D0/D1/Ground); no C441 or EML option module assumed.
#
# S811+ ONLY. MN03900001E documents no sibling model, so the S611 is NOT
# claimed here despite the two being sold together.
#
# Source — Eaton primary documentation only:
#   MN03900001E (August 2025) "S811+ Soft Starter User Manual"
#     printed p. 30  (PDF 42)     Table 20, the fault code list below
#     printed p. 45  (PDF 57)     network setup defaults, Comm Loss Action
#     printed pp. 55-58 (PDF 67-70) Table 50, the Modbus register map
#     printed p. 22  (PDF 34)     Permissive / Start semantics used by [control]
#
# ADDRESSING — UNCONFIRMED, THE ONE THING TO CHECK FIRST ON A BENCH.
# Table 50 heads its column "Modbus register number" and lists 300..381 for
# reads and 500..686 for writes. The manual never states whether that number is
# the on-the-wire PDU address or a 1-based/4xxxx entity number, and it gives no
# worked frame anywhere. The values here are used AS PRINTED, i.e. treated as
# 0-based protocol addresses. Because the map starts at 300/500 rather than at
# 40001, that is the only self-consistent reading — but it is an inference, not
# a quotation. If reads come back shifted, try address-1 before anything else.
#
# EATON TABLE DEFECT — read this before trusting anything at 359 or above.
# In Table 50 the Parameter-name column slips one row out of step with the
# register number from 359 onward, while the Description column stays correct.
# Printed p. 57 labels register 359 "Power Factor" but describes it as "L3 RMS
# pole current in 0.1 Amps", and labels 368 "Line Phase Sequence" while
# describing it as "Line Frequency (in 0.01 Hz)" with a UINT8 width that cannot
# hold 6000. The Description column is the internally consistent one: the
# four-entry current groups (356-359 = average, L1, L2, L3) only close if the
# description aligns with the number. This profile follows the Description
# column and every point at/above 359 is marked accordingly.
#
# DRIVE-SIDE SETUP — without these the S811+ will not answer or will not obey:
#   Modbus Address       factory 0. The unit does not answer until it is set.
#   Modbus Baud Rate     @503, factory 4 = 19200
#   Modbus Parity        @505, factory 0 = Even
#   Modbus Stop Bits     @506, factory 1
#   Modbus Mode          @507, factory 0 = RTU
#   Network 2Wire Enable factory 0 = Disabled, which makes register 500 the
#                        active control register. Set it and control moves to
#                        register 501 and every sequence below stops working.
#   The DIP/QCPort selector must be in the Modbus (ON) position at 24 Vdc
#   power-up, per printed p. 12.

name = "Eaton S811+ (soft starter)"
vendor = "Eaton"
device_type = "soft_starter"
verified = false
probe_register = 300  # Motor Control Status, readable whenever the port is alive

[connection]
summary = "Connect directly to the CH0 Net terminal block D0/D1/GND; the native Modbus port needs no C441 adapter."
warnings = ["Isolate line and 24 Vdc control power before wiring.", "Only 24 Vdc may be applied to the control terminal block; higher voltage damages the control circuit."]
[[connection.methods]]
id = "native_ch0_modbus"
title = "Native CH0 Net Modbus RTU"
transport = "serial"
hardware = "built_in"
port = "CH0 Net terminals D0 (RS485-), D1 (RS485+), GND"
connector = "Network control screw terminal block"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded two-wire RS-485 cable with ground/reference conductor"
parts = ["24 Vdc control supply sized for starter inrush", "Small insulated screwdriver"]
wiring = [{ adapter = "D- / A-", device = "CH0 D0", signal = "RS-485 negative" }, { adapter = "D+ / B+", device = "CH0 D1", signal = "RS-485 positive" }, { adapter = "COM/GND", device = "CH0 GND", signal = "RS-485 reference" }]
steps = ["Lock out the starter and 24 Vdc control supply and locate CH0 Net D0/D1/GND.", "Land negative on D0, positive on D1, and adapter reference on GND.", "Verify the 24 Vdc supply, Permissive circuit, and network-control wiring before restoring power.", "Power up with the DIP/QCPort selector in Modbus ON and select the computer adapter."]
setup = ["Set a nonzero Modbus Address, Baud Rate, Parity, Stop Bits, and RTU Mode.", "Leave Network 2Wire Enable disabled for this profile's register 500 control path and disable Local Control for network operation."]
warnings = ["Network 2Wire Enable moves control to register 501 and makes this profile's command register wrong.", "The selector position is sampled at 24 Vdc power-up."]
source = "Eaton MN03900001E, printed pp. 12, 15-18, 45, and 55-58"

# Printed p. 45: factory network setup is 19200 / Even / 1 stop bit / RTU.
[serial]
baudrate = 19200
parity = "E"
stopbits = 1

[monitor]
# Motor Control Status, printed p. 55. UINT8 in the low byte of the register.
# Two independent run flags because the S811+ has two selectable ramp profiles.
status_word = { address = 300, bits = { 0 = "Running1", 1 = "Running2", 2 = "Permissive", 3 = "Ramp2", 4 = "LocalControlStatus", 5 = "Faulted", 6 = "Warning", 7 = "InBypass" } }
# Motor Control Faults bitfield, printed p. 55 — which protection tripped, as
# distinct from the numeric code in [faults].
fault_bits = { address = 304, bits = { 0 = "PhaseLoss", 1 = "PhaseImbalance", 2 = "ThermalPile", 3 = "Overcurrent", 4 = "BreakerFault", 5 = "GndFault", 6 = "MotorStall", 7 = "MotorJam", 8 = "OverTemp", 9 = "UnderLoad", 11 = "EStop", 15 = "Other" } }
# Motor Control Warnings bitfield, printed p. 55. Same bit order as the faults
# above except bit 10, which is warning-only.
warning_bits = { address = 305, bits = { 0 = "PhaseLoss", 1 = "PhaseImbalance", 2 = "ThermalPile", 3 = "Overcurrent", 4 = "BreakerFault", 5 = "GndFault", 6 = "MotorStall", 7 = "MotorJam", 8 = "OverTemp", 9 = "UnderLoad", 10 = "OverloadImpendingTrip", 15 = "Other" } }
# Printed p. 55. Percent of the configured Motor FLA, so this is relative to a
# SETTING (@602), not an absolute current.
current_pct_fla = { address = 306, unit = "%" }
# Thermal pile percentage, printed p. 55. 100% = trip.
thermal_pile = { address = 307, unit = "%" }
line_voltage_l1 = { address = 308, unit = "V" }
line_voltage_l2 = { address = 309, unit = "V" }
line_voltage_l3 = { address = 310, unit = "V" }
# Scaled average three-phase LINE current in deciamps, printed p. 56. Preferred
# over the FLOAT pair at 328 (which is split LSB/MSB across two registers in a
# vendor-specific order) and over the whole-amp value at 336.
motor_current = { address = 340, scale = 0.1, unit = "A" }
# Analog input as percent of its selected range, printed p. 55.
analog_input_pct = { address = 313, unit = "%" }
# Discrete input status, printed p. 56. Bits 4-7 exist only with a C441 module.
logic_inputs = { address = 315, bits = { 0 = "TB_Input1", 1 = "TB_Input2", 2 = "TB_Input3", 3 = "TB_Input4" } }
#
# EVERYTHING BELOW THIS LINE IS IN THE MISALIGNED REGION OF TABLE 50 (>= 359).
# Addresses follow the Description column, per the table-defect note in the
# header. Confirm each against the DIM before relying on it.
power_factor = { address = 360, scale = 0.0001 }
active_power_kw = { address = 361, unit = "kW" }
device_temperature = { address = 366, scale = 0.1, unit = "C" }
auto_reset_count = { address = 367 }
line_frequency = { address = 368, scale = 0.01, unit = "Hz" }

# Modbus Motor Control (3-Wire), register 500, printed p. 57.
#   bit 0 Run1, bit 1 Run2, bit 2 Permissive, bit 3 Fault Reset, bit 7 Ramp2
#
# PERMISSIVE IS THE STOP. Printed p. 22 and p. 25: "Permissive must be
# energized to enable START", and "To initiate a Stop remove the 24 Vdc
# Permissive" — removing it starts a coast, soft or pump stop according to the
# configured stop type. The Modbus Permissive bit is the network equivalent, so
# clearing the register is a genuine stop command and not merely the absence of
# a run command. Bit 0 alone would never start the motor.
#
# A soft starter has no speed reference and no direction, so speed_register,
# speed_scale, max_ref and run_rev are all deliberately absent.
[control]
command_register = 500
step_delay = 0.05
# Drop Permissive -> configured stop ramp.
stop = [0x00]
# Raise Permissive first, then pulse Run1 on top of it. Run1 is edge-sensed by
# default (@381 = 0x00 edge sense), so Permissive must already be true when the
# Run1 edge arrives; holding 0x05 afterwards keeps Permissive asserted, which
# the starter requires for the whole run.
run_fwd = [0x04, 0x05]
# Fault Reset is bit 3, framed as a pulse. Run1 (bit 0) and Permissive (bit 2)
# are clear in every step, so nothing in this sequence can start the motor.
reset = [0x00, 0x08, 0x00]

# Printed p. 57: "Transient Motor Control Timeout" @685 and "Motor Control
# Device Command Missing Timeout" @686 are both 2000 ms, and "Comm Loss Action"
# @684 is factory 0 = Auto Stop, which trips fault 36 "ComLoss Stop fault".
# 500 ms sits well inside the 2000 ms window. Note the action is configurable:
# set to 3 = Hold Last the starter KEEPS RUNNING when the master goes quiet,
# and to 1 = Auto Run1 it will start on its own. Confirm @684 before arming.
[control.watchdog]
interval_ms = 500
fault = "36 ComLoss Stop fault"

# Status bit 0 = Running1, the default ramp profile. A start on ramp 2 reports
# on bit 1 instead; if the installation uses Ramp2, running_check must move.
[running_check]
register = 300
bit = 0

# Active Faults & Warning List, printed p. 55: @301 is the latest code, @302
# and @303 the two before it. The ten-deep queue at 318-327 does not repeat
# codes; the ten-deep list at 370-379 does.
[faults]
register = 301
history = [302, 303]

# Table 20, printed p. 30. Codes 2, 12, 15-17, 19-31, 33-35, 37, 45-53, 62,
# 67-70 are not printed in that table and are deliberately absent rather than
# guessed. Codes marked * in Table 21 (Watchdog, Watchdog Reset, FRam, Comm
# Failure, Flash CRC) carry no number in the manual at all.
[faults.codes]
1 = "Firmware incompatible"
3 = "Internal Com fault"
4 = "Low Control V"
5 = "Pole Overtemp"
6 = "PhaseLoss"
7 = "Phase Imbalance"
8 = "GND Fault"
9 = "Underload"
10 = "Overcurrent (contactor), Jam disabled"
11 = "Jam"
13 = "Bypass dropout"
14 = "Overload"
18 = "Inst I overcurrent"
32 = "Internal NV error"
36 = "ComLoss Stop fault"
38 = "Temperature sensor fault"
39 = "Internal CPU fault"
40 = "Motor Low Power"
41 = "Motor High Power"
42 = "UnderVoltage"
43 = "OverVoltage"
44 = "Phase Reversal Fault"
54 = "E-Stop"
55 = "MotorControl Device missing"
56 = "Internal Com2 fault"
57 = "Internal Fault"
58 = "SCR Not Firing"
59 = "Shorted SCR"
60 = "SCR Overcurrent (Stall disabled)"
61 = "Mains AC V Lost"
63 = "Motor Stall Fault"
64 = "V Zero cross"
65 = "Analog Input Out of range (high)"
66 = "Analog Input Out of range (low)"
71 = "Analog Input Overdrive"
72 = "External trip/warning"
73 = "Motor Load Disconnect"
74 = "Line Frequency (high)"
75 = "Line Frequency (low)"
76 = "Auto Reset Limit"

# NO [parameters] BLOCK, DELIBERATELY.
# The configuration space at 600-686 interleaves R/W settings with read-only
# values (@685 and @686 are timeouts marked R) and with 32-bit FLOAT pairs
# whose LSB/MSB split is vendor-specific. Table 50 was not read end to end for
# this profile, so no contiguous range is known to be safe to write. A clone
# that writes a read-only register NAKs; one that writes half a FLOAT pair
# corrupts a setting silently. Establish the safe ranges from printed pp. 58-60
# before adding this block.
#
# NO [rating] BLOCK: the S811+ frame rating is entered by the installer as
# Motor FLA (@602, 0.1 A) rather than reported by the unit, so there is no
# read-only frame-size register to compare before a restore.