# Property of PMA Electrical Solutions, LLC.
#
# ABB PSE18...PSE370 SOFT STARTER — not a VFD. No speed reference, no reverse.
#
# COMMUNICATION PATH THIS PROFILE ASSUMES: the **internal / built-in Modbus
# RTU** interface, which on a PSE means the optional PSE Modbus RTU adaptor
# (1SFC132367M0201 §2, p.4) plus parameter *Fieldbus interface type* =
# Modbus RTU. Modbus is NOT on the bare starter — the keypad menu itself is
# titled "FieldBus Control (optional hardware required)" (1SFC132057M0201
# §7.5.12, p.70).
#
# The OTHER PSE Modbus path — the MRP21-FBP / MRP31-FBP FieldBusPlug kit
# (1SFC132068M0201 §2, p.4) — is a DIFFERENT map and this profile does not
# cover it: that document has no status-word and no control-word register at
# all (its §3 goes digital-input telegram -> digital-output telegram -> analog
# telegram, and start/stop there exist ONLY as coils at 0x0101/0x0102), so
# registers 0x0300/0x0400 used below exist only on the internal Modbus RTU
# path. If the unit has a FieldBusPlug fitted, do not use this profile.
#
# PSTX is a different family with its own document (1SFC132089M0201) and is
# NOT claimed here.
#
# Sources — ABB primary only:
#   1SFC132367M0201 rev C "Fieldbus Communication, Internal Modbus RTU":
#     p.3    drive-side setup parameters
#     p.5-6  coil telegrams (NOT used here — see addressing note)
#     p.7    status word 0x0300
#     p.8    control word 0x0400
#     p.9    analog input telegram 0x0200-0x020C
#     p.9-10 diagnostic bitmap 0x2000 / 0x2003
#     p.12-13 parameter block 0x3000-0x301E
#     p.21-22 fieldbus fault EF40 behaviour
#   1SFC132057M0201 "PSE18...PSE370 Installation and commissioning manual":
#     p.70-73 fieldbus parameters, p.84-85 event list (EF/SF/P codes)
#
# ADDRESSING: ABB prints these as "Protocol Address" in hex and they are
# already 0-based protocol addresses. 0-based register = the hex value, e.g.
#   control word 0x0400 -> 1024, status word 0x0300 -> 768.
# No 4xxxx/PLC offset anywhere. Note ABB explicitly allows BOTH FC03 (read
# holding registers) and FC04 (read input registers) against this same map, so
# unlike most vendors there is no separate 3xxxx space to get wrong.
# The 0x0000-0x000F and 0x0100-0x011F telegrams are the COIL address space
# (FC01/FC02 read, FC05/FC15 write), a mirror of the status/control word —
# they are not
# registers. This app is register-based, so it drives 0x0300/0x0400.
#
# DRIVE-SIDE SETUP (1SFC132367M0201 p.3, p.14). Without these the starter
# answers reads and silently ignores commands:
#   - Fieldbus interface type   = Modbus RTU  (internal, "Int" on the display)
#   - Fieldbus control          = On          (OFF = monitoring only)
#   - Fieldbus address          = 1-247
#   - Internal Modbus RTU baud rate / frame format to match the bus
# AUTO MODE: the start and stop bits are only acknowledged when the auto-mode
# bit is set — which is why every sequence below carries bit 5. Do NOT also
# set the auto-mode COIL at 0x0105: ABB states that if auto mode is set in
# BOTH 0x0105 and control-word bit 5, "start/stop commands will not be
# acknowledged by the device due to incorrect configuration" (p.8). Pick one
# place; this profile picks bit 5.
#
# SCALING is integer engineering units on this map, not panel decimals:
# currents are whole amps, frequency whole Hz, so a 17 A starter reports
# 1 A resolution. Motor current at 0x0200 is percent of Ie, and Ie is itself
# parameter 0x3000 — that reading is therefore relative to how the unit is
# configured, not absolute.

name = "ABB PSE (soft starter)"
vendor = "ABB"
device_type = "soft_starter"
verified = false
probe_register = 768  # 0x0300 status word, readable whenever the fieldbus is up

# Factory defaults per 1SFC132367M0201 p.13: par 0x301D = 1 (19200) and
# par 0x301E = 1 (8e1). NOT 9600 8N1 — check this before blaming the wiring.
# A parity mismatch announces itself as event EF41, not as silence (p.21).
[serial]
baudrate = 19200
parity = "E"
stopbits = 1

[monitor]
# 0x0300. Bit 1 is MOTOR STOPPED (1 = stopped), bit 2 is running — they are
# separate bits, not each other's inverse, so read both before believing either.
status_word = { address = 768, bits = { 1 = "MotorStopped", 2 = "Running", 5 = "AutoMode_Modbus", 6 = "Fault", 11 = "DI_Start", 12 = "DI_Stop", 13 = "DI_Reset", 14 = "TopOfRamp", 15 = "ReadyToStart" } }
control_word = { address = 1024, bits = { 1 = "Stop", 2 = "Start", 5 = "AutoMode", 6 = "FaultReset", 12 = "ClearDiagnostics" } }
# 0x0200-0x020A analog input telegram.
motor_current_pct = { address = 512, unit = "%" }   # of Ie (par 0x3000), 0-800%
motor_thermal = { address = 513, unit = "%" }       # of trip temperature
phase_current_l1 = { address = 514, unit = "A" }
phase_current_l2 = { address = 515, unit = "A" }
phase_current_l3 = { address = 516, unit = "A" }
motor_current = { address = 517, unit = "A" }       # max phase current, 1 A/count
line_frequency = { address = 518, unit = "Hz" }     # measured, 1 Hz/count
power_factor = { address = 519, scale = 0.01 }      # 100 = 1.00
output_voltage_pct = { address = 520, unit = "%" }  # of line voltage
start_count = { address = 521, scale = 100.0 }      # 1 count = 100 starts
run_hours = { address = 522, scale = 10.0, unit = "h" }  # 1 count = 10 h
# 0x2003. Why the last parameter write failed — read this when a restore NAKs.
# Bits 8-15 carry the parameter number in that case (1SFC132367M0201 p.10).
param_write_diag = { address = 8195, bits = { 4 = "ParamReadOnly", 5 = "ParamNotSettableNow", 6 = "ParamOutOfRange", 7 = "ExtendedDiagAvailable" } }

# Control word 0x0400. Bit 5 (auto mode) must be held for the starter to take
# either command. Stop has priority over start, so the stop word is the safe
# resting word and is what the keepalive holds after a reset.
# A soft starter has no speed reference and no reverse: neither speed_register
# nor run_rev is defined, so `control speed` and `control run_rev` refuse
# rather than misbehave.
[control]
command_register = 1024
step_delay = 0.05
stop = [0x0022]              # auto mode + stop
run_fwd = [0x0020, 0x0024]   # auto mode, then auto mode + start
# Reset is a rising edge on bit 6 held between two STOP words. It deliberately
# never contains the start bit — writing a start with the reset would make the
# reset a run command.
reset = [0x0022, 0x0062, 0x0022]

# The starter trips EF40 "Fieldbus fault" if the master neither reads nor
# writes for longer than the *Internal Modbus RTU timeout* (par 0x301C,
# 0.5-60.0 s, DEFAULT 0.5 s) — hence a 200 ms keepalive. A READ feeds this
# timer too, not only a write. Two things make it worse than a normal
# comm-loss trip:
#   - after an EF40 the link must be continuously stable for 10 s before the
#     starter accepts any command, including the reset itself;
#   - if *Fieldbus fault reaction* is LocC instead of trIP the starter does not
#     trip, it hands control back to the hardwire terminals — going quiet then
#     means the Modbus stop command is no longer connected to anything.
# WHICH OF THOSE TWO IS THE FACTORY DEFAULT IS UNRESOLVED IN ABB'S OWN
# DOCUMENTATION: 1SFC132367M0201 p.13 gives par 0x3019 default 0 = Trip, while
# 1SFC132057M0201 §7.5.12.3 p.72 gives the same setting default LocC. The two
# behaviours differ in whether losing the link stops the motor or silently
# re-arms the hardwire terminals, so read it off the unit — do not assume.
# (1SFC132367M0201 p.13, p.21-22.)
[control.watchdog]
interval_ms = 200
fault = "EF40 fieldbus fault"

[running_check]
register = 768
bit = 2                       # status word bit 2 = Run status

# 0x2000 is a BITMAP of active faults and protections, not a numeric code, so
# several can be set at once. Bit 0 is not a fault — it says whether whatever
# is active can be reset. 0x2001/0x2002 are Reserved, so there is no history.
# The parenthesised codes are the LCD event codes from the install manual's
# event list (1SFC132057M0201 Table 10.2, p.85), matched to these bits by
# wording — all 13 line up one-for-one, EF3x being "Current lost" there and
# "Current loss" here. Only EF40 is stated outright by the Modbus manual, so
# treat the rest as a strong inference. `x` in EF1x/EF3x
# /EF6x/SF3x/SF4x is the phase number on the display, 4 = multiple/unknown.
[faults]
register = 8192
bitfield = true

[faults.bits]
0 = "Reset possible on active event (not itself a fault)"
1 = "Software fault (SF20)"
2 = "Shunt fault (SF3x)"
3 = "By-pass open (SF4x)"
4 = "Softstarter overload (SF50)"
5 = "Phase loss (EF1x)"
6 = "Bad network quality (EF20)"
7 = "Current loss (EF3x)"
8 = "Fieldbus fault (EF40)"
9 = "Low supply voltage (EF50)"
10 = "High current (EF6x)"
11 = "Motor overload (P1)"
12 = "Locked rotor protection (P3)"
13 = "Underload protection (P2)"

# Read/write settings block only: 0x3000-0x3015 (12288-12309). Stops short of
# 0x3016-0x301E, which ABB marks Read only — they are the fieldbus/comm
# settings, and a restore that walked into them would NAK or cut the link it
# is being restored over.
#
# WARNING for clone/restore: 0x3000 is Motor rated current Ie, and this map
# exposes NO register for the starter's own frame rating, so nothing here can
# catch a PSE370 config being pushed onto a PSE18. Check the type label by eye
# before restoring. (A parameter write is also rejected outright during a soft
# start or soft stop — only standby and top-of-ramp accept writes; 0x2003
# says which parameter was refused and why.)
[parameters]
ranges = [[12288, 12309]]

[connection]
summary = "The PSE internal Modbus profile requires the optional PSE Modbus RTU Adaptor fitted to the starter; the bare PSE has no Modbus terminal."
warnings = ["Do not use this profile with an MRP21-FBP/MRP31-FBP FieldBusPlug; that path has a different map.","Changing control type with a start signal present can start the motor unexpectedly."]

[[connection.methods]]
id = "pse_internal_modbus_adapter"
title = "PSE internal Modbus RTU Adaptor"
transport = "serial"
hardware = "option"
port = "PSE Modbus RTU Adaptor fitted to the starter"
connector = "Adaptor screw terminals marked -(A), +(B), GND"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded twisted pair plus signal common"
parts = ["ABB PSE Modbus RTU Adaptor","Isolated USB-to-RS-485 adapter","Shielded twisted pair plus common"]
steps = ["Lock out the starter and verify that no start command is present.","Fit the PSE Modbus RTU Adaptor exactly as illustrated in the ABB adaptor manual.","Land the three conductors on the adaptor's -(A), +(B) and GND markings.","Restore control power with the motor circuit inhibited and verify a status-word read."]
setup = ["Set Fieldbus interface type = internal Modbus RTU.","Set Fieldbus address, Internal Modbus RTU baud rate and frame format.","Set Fieldbus control = On only after monitoring is proven and remote starting is intended."]
warnings = ["The adaptor terminal markings are shown graphically on page 4; do not substitute FieldBusPlug wiring."]
source = "ABB 1SFC132367M0201 Rev C, pp. 3-4 and 14."

[[connection.methods.wiring]]
adapter = "D- / A / negative"
device = "Adaptor -(A)"
signal = "RS-485 negative"

[[connection.methods.wiring]]
adapter = "D+ / B / positive"
device = "Adaptor +(B)"
signal = "RS-485 positive"

[[connection.methods.wiring]]
adapter = "COM / signal common"
device = "Adaptor GND"
signal = "Signal reference"