# Property of PMA Electrical Solutions, LLC.
#
# Benshaw RediStart MX3 SOFT STARTER — not a VFD. Low-voltage line, sourced
# from the manual that covers the **RB3, RC3 and RX3E models** only (the model
# list is on that manual's cover). The medium-voltage MX3 (MVRMX/MVRXE, doc
# 890034-03-00) is a separate manual with its own register map and is not
# claimed here. Within the packaged RX line, only the explicitly sourced RX3E
# model is covered; no other RX sibling is implied.
#
# SOURCE: Benshaw doc **890034-02-02**, "RediStart Solid State Starter Control,
# RB3, RC3, RX3E Models, User Manual", February 2008 (242 pp), for card set
# BIPC-400100-01-05 / software 810023-02-05 + 810024-01-01. Printed pages:
#   §7.15  Remote Modbus Communications ............ pp. 180-181
#   QST04 Local Source / QST05 Remote Source ....... p. 74
#   FUN16-FUN19 comm address/baud/timeout/framing .. pp. 132-133
#   FUN22 Miscellaneous Commands ................... p. 134
#   Appendix C, Fault Codes ........................ pp. 207-208
#   Appendix F, Modbus Register Map ................ pp. 211-224
#     (control/status register bit meanings, p. 224)
#
# COMMS PATH: **embedded Modbus RTU on terminal block TB4** (B+, A-, COM),
# §7.15.7 / Figure 62, p. 181. No option card — the MXDE3 DeviceNet/Ethernet
# module is a gateway in front of this same port and is not assumed here.
# Function codes supported: 03, 04, 06, 10 hex; up to 64 registers per
# transaction (§7.15.1, p. 180). `dump` reads one register at a time, so that
# 64-register ceiling is never approached.
#
# ADDRESSING — the conversion that matters:
#   Appendix F prints every entry as a PAIR, "30020/40020". §7.15.2 (p. 180)
#   states the convention outright: "The Modbus specification defines holding
#   registers to begin at 40001 and input registers to begin at 30001", and
#   "the register maps are identical for both the holding registers and the
#   input registers" — the same datum is holding 40101 AND input 30101.
#   So the two numbers are the SAME offset in two address spaces, and:
#
#       0-based protocol address = <4xxxx number> - 40001
#                                = <3xxxx number> - 30001
#
#   Every address below is that 0-based value, used with FC03/FC06/FC10.
#   Worked: Starter Control 40020 -> 19. Starter Status 40021 -> 20.
#   Present Fault Code 40027 -> 26. Motor FLA 40101 -> 100.
#
#   RESIDUAL RISK, un-eliminable from documentation alone: Benshaw heads the
#   column "Absolute Register Address", and the MXDE3 manual's EZPLC example
#   (doc 01-890041-01-02, p. 99) says "start with address 40020 by setting the
#   offset to 20" — a PLC-side field whose own base is ambiguous. If Benshaw
#   firmware actually decodes 40020 as PDU 20 rather than 19, every address
#   here is one low. The map is dense enough that adjacent registers could
#   still answer, so the error may be silent; confirm on a bench before arming.
#   verified=false.
#
# DRIVE-SIDE SETUP — without this the starter ACKs writes and ignores them:
#   * QST05 Remote Source = **Serial** (p. 74). "The control source must be
#     serial for the starter to be started through Modbus" (p. 224).
#   * Control-register bit 3 selects Local vs Remote and every command word
#     below asserts bit 3 = 1 (Remote). That bit only has effect if NO digital
#     input is configured as Local/Remote (I/O01-I/O08 value 9); if one is, the
#     terminal wins and the bit does nothing (pp. 74, 224). If your site runs
#     serial as the LOCAL source instead (QST04 = Serial), drop bit 3 from the
#     sequences below — 0xFC00/0xFC01 instead of 0xFC08/0xFC09.
#   * FUN16 address (default 1), FUN17 baud (default 19200), FUN19 byte
#     framing (default Even parity, 1 stop) — see [serial].
#
# EDGE-TRIGGERED START: "The Run/Stop bit must transition from 0 to 1 for a
# start to occur", and likewise the fault-reset bit (p. 224). That is why
# run_fwd and reset are two- and three-step sequences rather than single
# writes, and why arming a starter that is ALREADY running will drop it for
# one step before restarting it.
#
# NO SPEED REFERENCE AND NO REVERSE. A soft starter has neither over Modbus:
# the control register carries no reference field, and Slow Speed Forward /
# Reverse are digital-input functions only (register 40169 config values 13
# and 14, p. 217). speed_register and run_rev are therefore absent, so
# `control speed` and `control run_rev` refuse rather than misbehave.
#
# WATCHDOG — and its default is the dangerous direction. FUN18 Communication
# Timeout is **Off from the factory** (p. 133, register 40188 enable /
# 40189 value). With it Off the MX3 keeps the motor running indefinitely after
# the master goes silent. Enable it (1-120 s) before commissioning serial
# control; then silence declares F82 Modbus Timeout and the starter performs a
# controlled stop. The keepalive below is sized for a 1 s FUN18 setting.
#
# RELAY BITS: control-register bits 10-15 map to relays 6..1. Those bits are
# only WRITABLE when the corresponding relay is configured "Off"; otherwise
# they read back the relay state (p. 224). Their polarity is safety-critical:
# 0 = ENERGIZE, 1 = DE-ENERGIZE. Every command below therefore holds all six
# bits high (0xFC00) so a site-configured remote relay cannot energize merely
# because the app sends a motor command.

name = "Benshaw RediStart MX3"
vendor = "Benshaw"
device_type = "soft_starter"
verified = false
probe_register = 20  # 40021 Starter Status — readable whenever the port is alive

[connection]
summary = "Embedded Modbus RTU is on terminal block TB4; no communications option card is required."
warnings = []

[[connection.methods]]
id = "tb4_rs485"
title = "Built-in TB4 Modbus RTU"
transport = "serial"
hardware = "built_in"
port = "Terminal block TB4"
connector = "TB4 three-position terminal block"
adapter = "Isolated USB-to-RS-485 adapter, 2-wire half-duplex"
cable = "Shielded twisted-pair RS-485 cable"
parts = ["Isolated two-wire RS-485 adapter", "Shielded twisted-pair RS-485 cable"]
steps = ["Lock out line and control power, wait the vendor-specified discharge time, and verify the DC bus is de-energized before opening a cover or landing conductors.", "Land the positive and negative data conductors exactly as shown; connect the cable shield or signal common only where the method identifies it.", "Route the communications cable away from motor and mains conductors. Terminate the two physical ends of a long multidrop trunk only.", "Restore control power with the motor area clear, configure the drive from its keypad, then verify identity and read-only monitor data before enabling remote control."]
setup = ["Set QST05 Remote Source=Serial, FUN16=node, FUN17=baud, FUN19=framing, and set FUN18 timeout to about 1 s."]
warnings = ["RS-485 A/B naming is not consistent between manufacturers. Follow the + and - signal mapping in this guide, not the letter printed on an unfamiliar adapter.", "Do not use protective earth as the data return unless the vendor drawing explicitly calls for it.", "The reset/enable and local/remote hardwired inputs can override or inhibit network commands; verify their state before troubleshooting the bus."]
source = "Benshaw 890034-02-02 MX3 User Manual, printed pp. 17 and 180-181 (TB4), pp. 132-133 (setup)"

[[connection.methods.wiring]]
adapter = "Adapter D+ / +"
device = "TB4-1 B+"
signal = "RS-485 data positive"
required = true

[[connection.methods.wiring]]
adapter = "Adapter D- / -"
device = "TB4-2 A-"
signal = "RS-485 data negative"
required = true

[[connection.methods.wiring]]
adapter = "Adapter signal ground / shield"
device = "TB4-3 COM"
signal = "Signal reference or shield drain"
required = false

# FUN17 default 19200, FUN19 default "Even, 1 Stop" (pp. 132-133).
# 19200 is also the maximum the MX3 supports (§7.15.4, p. 180).
[serial]
baudrate = 19200
parity = "E"
stopbits = 1

# Appendix F, pp. 211-213 and 224. Currents are whole Arms, voltages whole
# Vrms — the fieldbus carries no extra decimal for either.
[monitor]
# 40021 Starter Status. Bit 0 "Ready" is 1 in the healthy case and 0 when
# initializing, locked out, or faulted/decelerating/braking/stopped (p. 224).
status_word = { address = 20, bits = { 0 = "Ready", 1 = "Running", 2 = "UpToSpeed", 3 = "Alarm", 4 = "Fault", 5 = "Lockout" } }
input_status = { address = 21, bits = { 0 = "Start", 1 = "DI1", 2 = "DI2", 3 = "DI3", 4 = "DI4", 5 = "DI5", 6 = "DI6", 7 = "DI7", 8 = "DI8" } }

# Alarms are warnings, not trips; the trip is in [faults]. Names are the
# manual's own A-codes (pp. 211-212).
alarm_status_1 = { address = 22, bits = { 0 = "A OL motor overload", 1 = "A5 motor PTC", 2 = "A6 stator RTD", 3 = "A7 bearing RTD", 4 = "A8 other RTD", 5 = "A10 phase rotation not ABC", 6 = "A11 phase rotation not CBA", 7 = "A12 low line frequency", 8 = "A13 high line frequency", 9 = "A14 phase rotation not 1PH", 10 = "A15 phase rotation not 3PH", 11 = "A21 low line L1-L2", 12 = "A22 low line L2-L3", 13 = "A23 low line L3-L1", 14 = "A24 high line L1-L2", 15 = "A25 high line L2-L3" } }
alarm_status_2 = { address = 23, bits = { 0 = "A26 high line L3-L1", 1 = "A27 phase loss", 2 = "noL no line", 3 = "A29 PORT timeout", 4 = "A31 overcurrent", 5 = "A34 undercurrent", 6 = "A35 PF too leading", 7 = "A36 PF too lagging", 8 = "A37 current imbalance", 9 = "A38 ground fault", 10 = "A47 stack overtemperature", 11 = "A53 tach loss", 12 = "A60 DI1", 13 = "A61 DI2", 14 = "A62 DI3", 15 = "A63 DI4" } }
alarm_status_3 = { address = 24, bits = { 0 = "A64 DI5", 1 = "A65 DI6", 2 = "A66 DI7", 3 = "A67 DI8", 4 = "A71 analog input trip" } }
# Why a start is being refused. Worth reading before anyone reaches for the
# fault-reset button.
lockout_status = { address = 25, bits = { 0 = "motor overload", 1 = "motor PTC", 2 = "RTD stator", 3 = "RTD bearing", 4 = "RTD other", 5 = "run interlock", 6 = "disconnect open", 7 = "stack overtemperature", 8 = "control power", 9 = "RTD open/short", 10 = "time between starts", 11 = "backspin", 12 = "starts per hour", 13 = "RTD comm loss" } }

motor_current = { address = 27, unit = "A" }         # 40028 average, Arms
l1_current = { address = 28, unit = "A" }
l2_current = { address = 29, unit = "A" }
l3_current = { address = 30, unit = "A" }
current_imbalance = { address = 31, scale = 0.1, unit = "%" }
residual_ground_current = { address = 32, unit = "% FLA" }
zero_seq_ground_current = { address = 33, scale = 0.1, unit = "A" }
line_voltage = { address = 34, unit = "V" }          # 40035 average, Vrms
l1_l2_voltage = { address = 35, unit = "V" }
l2_l3_voltage = { address = 36, unit = "V" }
l3_l1_voltage = { address = 37, unit = "V" }
motor_thermal = { address = 38, unit = "%" }         # 40039 accumulated OL content; trips at 100
power_factor = { address = 39, scale = 0.01, signed = true }   # -99..+100, two's complement
# 32-bit meters: "the least significant 16 bits are in the first register
# followed by the most significant 16 bits" (p. 224) — hence low_first.
# Reading the LOW register latches the high one, so read the pair in one
# transaction, which a 2-word point does.
active_power = { address = 40, words = 2, word_order = "low_first", unit = "W" }
energy = { address = 46, words = 2, word_order = "low_first", unit = "kWh" }
phase_order = { address = 48 }                       # 0=no line 1=ABC 2=CBA 3=SPH
line_frequency = { address = 49, scale = 0.1, unit = "Hz" }
analog_input = { address = 50, scale = 0.1, signed = true, unit = "%" }
analog_output = { address = 51, scale = 0.1, unit = "%" }
run_hours = { address = 52, unit = "h" }
starts = { address = 54 }
trutorque = { address = 55, unit = "%" }
power_pct = { address = 56, unit = "%" }
peak_starting_current = { address = 57, unit = "A" }
last_start_duration = { address = 58, scale = 0.1, unit = "s" }
# Motor FLA (QST01), the configured motor nameplate current. This is a
# writable setting, NOT the starter's own frame rating — see the gap noted
# above [parameters].
motor_nominal_current = { address = 100, unit = "A" }

# 40020 Starter Control (p. 224). Bit 0 Run/Stop, bit 1 Fault Reset,
# bit 2 Emergency OL Reset, bit 3 Local/Remote, bit 4 Heat Disable,
# bit 5 Ramp Select, bits 10-15 relays 6..1.
#
# Every word holds bit 3 = 1 (Remote) and leaves bits 2, 4, 5 clear:
#   0xFC08 = Remote, stopped, relays de-energized, heater enabled, Ramp 1
#   0xFC09 = 0xFC08 + Run
#   0xFC0A = 0xFC08 + Fault Reset (Run/Stop stays 0 — not a run word)
# run_fwd and reset are sequences because both bits are edge-triggered.
# The keepalive re-sends the last word of the sequence, so a run latches
# 0xFC09 (bit 0 held high = keep running) and a reset latches 0xFC08 (stop).
[control]
command_register = 19
step_delay = 0.05
stop = [0xFC08]
run_fwd = [0xFC08, 0xFC09]
reset = [0xFC08, 0xFC0A, 0xFC08]

# FUN18 Communication Timeout, 1-120 s, DEFAULT OFF. Set it to 1 s and the
# starter trips F82 and performs a controlled stop when the master goes quiet.
# Leave it Off and the motor runs on regardless — so this interval is only a
# real backstop once FUN18 has been enabled on the starter.
[control.watchdog]
backstop_requires_setup = true
interval_ms = 250
fault = "F82 Modbus Timeout"

[running_check]
register = 20
bit = 1                   # Starter Status bit 1 = Running

# 40027 Present Fault Code; 40601-40609 are the fault log, newest first
# (p. 222). Codes are Appendix C, pp. 207-208, verbatim — the manual lists no
# others, and the gaps in the numbering are the manual's own.
[faults]
register = 26
history = [600, 601, 602, 603, 604, 605, 606, 607, 608]

[faults.codes]
0 = "F00 no fault"
1 = "F01 UTS time limit expired"
2 = "F02 motor thermal overload trip"
3 = "F03 slow speed time limit expired"
4 = "F04 speed switch time limit expired"
5 = "F05 motor PTC overtemperature"
6 = "F06 stator RTD overtemperature"
7 = "F07 bearing RTD overtemperature"
8 = "F08 other RTD overtemperature"
10 = "F10 phase rotation error, not ABC"
11 = "F11 phase rotation error, not CBA"
12 = "F12 low line frequency"
13 = "F13 high line frequency"
14 = "F14 input power not single phase"
15 = "F15 input power not three phase"
21 = "F21 low line L1-L2"
22 = "F22 low line L2-L3"
23 = "F23 low line L3-L1"
24 = "F24 high line L1-L2"
25 = "F25 high line L2-L3"
26 = "F26 high line L3-L1"
27 = "F27 phase loss"
28 = "F28 no line"
29 = "F29 PORT timeout"
30 = "F30 instantaneous overcurrent (IOC)"
31 = "F31 overcurrent"
34 = "F34 undercurrent"
35 = "F35 power factor leading"
36 = "F36 power factor lagging"
37 = "F37 current imbalance"
38 = "F38 ground fault"
39 = "F39 no current at run"
40 = "F40 shorted / open SCR"
41 = "F41 current at stop"
46 = "F46 disconnect fault"
47 = "F47 stack overtemperature / power supply failure"
48 = "F48 bypass / 2M contactor fault"
49 = "F49 inline contactor fault"
50 = "F50 control power low"
51 = "F51 current sensor offset error"
53 = "F53 tachometer signal loss"
54 = "F54 BIST fault"
55 = "F55 BIST CT fault"
56 = "F56 RTD open or shorted"
60 = "F60 external fault on DI1"
61 = "F61 external fault on DI2"
62 = "F62 external fault on DI3"
63 = "F63 external fault on DI4"
64 = "F64 external fault on DI5"
65 = "F65 external fault on DI6"
66 = "F66 external fault on DI7"
67 = "F67 external fault on DI8"
71 = "F71 analog input #1 level fault trip"
80 = "F80 RTD module communication fault"
81 = "F81 keypad communication fault"
82 = "F82 Modbus timeout fault"
84 = "F84 MX3 to I/O card communication fault"
85 = "F85 I/O card software version fault"
86 = "F86 I/O card current offset error"
87 = "F87 I/O card error"
88 = "F88 I/O card error"
89 = "F89 I/O card software watchdog"
90 = "F90 I/O card error"
91 = "F91 I/O card program EPROM checksum fault"
94 = "F94 CPU error - software fault"
95 = "F95 CPU error - parameter EEPROM checksum fault"
96 = "F96 CPU error"
97 = "F97 CPU error - software watchdog"
98 = "F98 CPU error"
99 = "F99 CPU error - program EPROM checksum fault"

# No [rating]: Appendix F documents no read-only frame-size / stack-rating
# register, so the app cannot compare a source starter against a target the
# way it does on the ATS48. Check the nameplate by hand before restoring a
# config onto different hardware.
#
# Settings block, 40101-40198 and 40221-40299 (pp. 213-222). Deliberately
# excludes:
#   * 40199 (-> 198) Misc. Commands — value 8 is FACTORY RESET, 5 is Reflash
#     Mode, 1/2 run BIST. Never in a bulk restore (FUN22, p. 134).
#   * 40190 (-> 189) CT Ratio — this describes the current transformers
#     physically in THAT starter. Copying it to a different frame silently
#     rescales every current reading and the overload with it.
#   * 40200-40220, undocumented hole between the two blocks.
#   * everything below 40101, which is the read-only meter block.
[parameters]
ranges = [[100, 188], [190, 197], [220, 298]]