# Property of PMA Electrical Solutions, LLC.
#
# ABB PSTX SOFT STARTER — not a VFD. Built-in Modbus RTU on the starter's own
# terminals 23/24 (Com3). No option module.
#
# Source: ABB "Softstarter type PSTX — Fieldbus communication, Built-in Modbus
# RTU", document 1SFC132089M0201 Rev F.
#   pp. 3-4   drive-side setup parameters, comm-loss protection
#   pp. 4-5   addressing conventions
#   p. 8      status word (0x01FF) bit table
#   pp. 9-10  analog input scaling table
#   pp. 11-13 digital output telegram and control words (0x02FE / 0x02FF)
#   p. 18     worked example naming the DEFAULT Fieldbus AI 1 / AI 2 content
#   pp. 20-23 Fieldbus Tasks (parameter mailbox)
# Claims only PSTX. PSE is a different family and is NOT covered here.
#
# ADDRESSING. The manual prints both notations side by side and states the
# conversion itself (p. 5): "Modicon address 40002 selects the holding register
# at protocol address 0001". So:
#   holding register: protocol = Modicon - 40001    (40767 -> 766 = 0x02FE)
#   input register:   protocol = Modicon - 30001    (30512 -> 511 = 0x01FF)
#   coil:             protocol = Modicon - 1        (  257 -> 256 = 0x0100)
# Every address below is the 0-based protocol address. Note that the status
# word and the analog inputs are listed under 3xxxx (input registers) but the
# manual explicitly says FC03 Read Holding Registers works too, at the SAME
# protocol address — this is not the usual 3xxxx/4xxxx offset trap.
#
# DRIVE-SIDE SETUP — without these the starter ACKs writes and ignores them:
#   12.1  Com3 function        = Modbus RTU slave
#   12.2  FB interface conn.   = Modbus RTU
#   12.3  Fieldbus control     = On   (Off = monitoring only, no commands)
#   12.4  Fieldbus address     = 1-247
#   12.9/12.10/12.11           = baud / parity / stop bits
# A power cycle (or toggling 12.2 to None and back) is required before any of
# these take effect. The DX111/DX112 expansion IO module shares terminals 23/24
# and CANNOT be used at the same time as the built-in Modbus RTU.
#
# AUTO MODE — read this before arming. Auto mode can be asserted either by coil
# 0x0103 or by bit 3 of control word 1. The manual is explicit (p. 13): if it
# is set in BOTH places the starter will not acknowledge start/stop at all.
# This profile drives the control-word path only, so coil 0x0103 must be left
# at 0.
#
# STOP IS ACTIVE-LOW. Control word 1 bit 1 "commences a stop when the signal is
# NEGATED", while bit 0 starts when set. That is why the run sequence releases
# the stop bit first and the resting/stop word holds it low.

name = "ABB PSTX (soft starter)"
vendor = "ABB"
device_type = "soft_starter"
verified = false
probe_register = 511  # 0x01FF status word — fixed address, alive whenever the fieldbus is

# NOT SOURCED. 1SFC132089M0201 lists the supported baud rates (9600, 19200,
# 38400, 57600, 76800, 115200) but never states the factory default, and says
# nothing about default parity or stop bits. Read 12.9/12.10/12.11 off the HMI;
# these are only the app's fallback.
[serial]
baudrate = 9600
parity = "N"
stopbits = 1

[monitor]
# 0x01FF. Bits 0-5 are fixed; bits 6-15 mirror the ten PROGRAMMABLE digital
# inputs, whose meaning is whatever the Fieldbus DI 1..10 parameters select.
# "Run status" and "TOR status" are selectable functions, not fixed bits —
# which is why this profile ships no [running_check]; see the note below.
status_word = { address = 511, bits = { 0 = "AUTO_MODE", 1 = "EVENT_ACTIVE", 2 = "READY_TO_START", 3 = "FBT_RESP_0", 4 = "FBT_RESP_1", 5 = "FBT_TOGGLE", 6 = "PROG_DI_1", 7 = "PROG_DI_2", 8 = "PROG_DI_3", 9 = "PROG_DI_4", 10 = "PROG_DI_5", 11 = "PROG_DI_6", 12 = "PROG_DI_7", 13 = "PROG_DI_8", 14 = "PROG_DI_9", 15 = "PROG_DI_10" } }

# 0x0201-0x020A are TEN PROGRAMMABLE analog inputs. There is no fixed current,
# power or temperature register on this starter — the content of each is chosen
# by the Fieldbus AI 1..10 parameters, so the scales below hold only while the
# mapping does. The manual's own worked example (p. 18) reads 0x0201 and 0x0202
# and names them Phase L1 / Phase L2 current "with default settings"; that is
# the only default this document states. AI 3..10 have no documented default,
# so they are exposed raw and unscaled.
# Current scaling per the p. 9 table: value 1000 = 100 A, i.e. 0.1 A per count.
phase_l1_current = { address = 513, scale = 0.1, unit = "A" }   # Fieldbus AI 1, default
phase_l2_current = { address = 514, scale = 0.1, unit = "A" }   # Fieldbus AI 2, default
fieldbus_ai_3 = { address = 515 }
fieldbus_ai_4 = { address = 516 }
fieldbus_ai_5 = { address = 517 }
fieldbus_ai_6 = { address = 518 }
fieldbus_ai_7 = { address = 519 }
fieldbus_ai_8 = { address = 520 }
fieldbus_ai_9 = { address = 521 }
fieldbus_ai_10 = { address = 522 }

# Control word 1, protocol address 0x02FE = 766. Written with FC06/FC16.
# Bits used here: 0 Start, 1 Stop (active low), 2 Fault reset, 3 Auto mode.
#   0x0008  auto mode, stop asserted (bit 1 low), start clear   -> STOP
#   0x000A  auto mode, stop released, start clear               -> armed idle
#   0x000B  auto mode, stop released, start set                 -> RUN
#   0x000C  auto mode, fault reset, stop still asserted         -> RESET
# The reset word deliberately carries bit 0 clear, so nothing on this register
# doubles as a run command.
#
# A soft starter has no speed reference: no speed_register is defined, so
# `control speed` refuses rather than writing somewhere harmless-looking.
#
# run_rev is deliberately absent. Control word 1 bit 12 IS "Start reverse", but
# reverse on a PSTX needs reversing contactors and the matching starter
# configuration, and 1SFC132089M0201 documents neither. Do not add it from
# this document alone.
[control]
command_register = 766
step_delay = 0.05
stop = [0x0008]
run_fwd = [0x000A, 0x000B]
reset = [0x0008, 0x000C, 0x0008]

# Go quiet longer than parameter 19.12 (fieldbus failure timeout) and the
# starter trips protection P1E00 "fieldbus communication failure"; with the
# default configuration that STOPS the motor. 19.12's own default value is not
# given in 1SFC132089M0201, so this interval is a conservative guess, not a
# sourced one — confirm 19.12 on the unit. Sites that only poll occasionally
# are expected to set 19.4 Fieldbus failure op = Off instead.
[control.watchdog]
interval_ms = 200
fault = "P1E00 fieldbus communication failure"

# The event/fault CODE is not at a fixed address on this starter — it is only
# readable by mapping a Fieldbus AI to the "Top event code" function, or
# through the Fieldbus Task parameter mailbox. What is always available is
# status word bit 1, which tells you an event exists but not which one.
# The PSTX event code list lives in 1SFC132081M0201, which is not in hand;
# [faults.codes] is therefore deliberately empty rather than filled in.
[faults]
register = 511
bitfield = true
bits = { 1 = "Active fault, warning or protection — read the code at the HMI" }

# No [running_check]. "Run status" is a selectable Fieldbus DI function, not a
# fixed status-word bit, so there is no bit this profile can assert for every
# PSTX. Commands come back marked unverified, which is the honest answer. If
# the starter has Fieldbus DI 1 set to "Run status", add:
#     [running_check]
#     register = 511
#     bit = 6
#
# No [parameters]. PSTX parameters are not register-mapped; they are reached
# through the Fieldbus Task mailbox (FBT control word 0x0300 + argument
# registers, toggle-bit handshake), which this app does not speak. Clone and
# restore are therefore unsupported on this starter.
#
# No [rating]. The starter's frame rating is a parameter, not a register.

[connection]
summary = "The PSTX has built-in Modbus RTU on Com3 terminals 23 and 24, with a required digital-ground reference to terminal 19, 22 or 30."
warnings = ["Com3 cannot simultaneously serve a DX111/DX112 extension-I/O module.","Terminals 23-29 are non-isolated; if master and starter grounds differ, ABB requires an isolated master supply with no ground offset.","Changing control mode with a start signal present can start the motor unexpectedly."]

[[connection.methods]]
id = "built_in_rs485"
title = "Built-in Modbus RTU"
transport = "serial"
hardware = "built_in"
port = "Com3 terminal group"
connector = "23 +(B), 24 -(A); digital ground to 19, 22 or 30"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded twisted-pair RS-485 cable with signal common"
parts = ["Isolated USB-to-RS-485 adapter","Shielded twisted-pair RS-485 cable with signal common","Termination hardware if required"]
steps = ["Lock out all power, verify the motor cannot start, and wait for the DC bus to discharge.","Open the control compartment and locate Com3 terminal group.","Land the conductors exactly as shown below, preserving the shield through each daisy-chain node.","Enable termination only if this device is at a physical end of the RS-485 trunk.","Restore control power with the motor inhibited and verify a read before enabling fieldbus control."]
setup = ["Set 12.01 Com3 function = Modbus RTU slave and 12.02 FB interface connector = Modbus RTU.","Set 12.03 Fieldbus control, 12.04 address and 12.09/12.10/12.11 baud/parity/stop bits.","Power-cycle or toggle 12.02 to apply communication changes."]
warnings = ["Do not apply more than the documented low-level RS-485 voltage to terminals 23/24.","Use only one of terminals 19, 22 or 30 for the PLC digital-ground reference."]
source = "ABB 1SFC132081M0201, p. 47; ABB 1SFC132089M0201 Rev F, pp. 3-4."

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

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

[[connection.methods.wiring]]
adapter = "COM / digital ground"
device = "19, 22 or 30 GND"
signal = "Digital-ground reference"