# Property of PMA Electrical Solutions, LLC.
#
# ABB ACS280 machinery (coldplate) drive — embedded fieldbus (EFB), Modbus RTU.
#
# CLAIMS ONLY THE ACS280. This file is mined end to end from the ACS280's own
# firmware manual. NOT claimed: ACS180, ACS380, ACS580, ACH580 or any other ABB
# family. The ACS280 has its own dedicated firmware manual and its own
# Read Device Identification product name ("ACS280", p.372); nothing in that
# document states that it shares the ACS180 manual or map, so no such claim is
# made here. The control-word / status-word shape is the common ABB Drives
# profile, but every address below was read out of the ACS280 document.
#
# Source: ABB "ACS280 coldplate drives firmware manual", document
# 3AXD50001017729 Rev A (EN), 430 pp. Applies to ACS280 machinery control
# program 2.18 or later. In this PDF the printed page number equals the PDF
# page index (offset 0, checked on p.262).
#   pp. 351-355  connection, group 58 defaults, fieldbus-enable parameters
#   p.  262      58.33 Addressing mode (the addressing formula)
#   pp. 359-364  ABB Drives control word / status word bit tables
#   p.  367      the manual's own start / stop / reset control-word sequence
#   pp. 367-369  reference and actual-value scaling (20000 / 10000)
#   pp. 369-370  fixed Modbus holding register map
#   pp.  93-95   group 01 actual values and their FbEq16
#   pp. 103-105  06.16 Drive status word 1
#   p.   97      group 04 warnings and faults
#   pp. 248-249  group 46 scaling parameters and their defaults
#   p.  289      99.06 Motor nominal current
#   pp. 340-350  fault message table
#
# COMMUNICATION PATH: the drive's built-in EIA-485 terminal (front J2
# connector), p.353. No option module. This manual documents no other fieldbus
# path for the ACS280, and whether an external Modbus TCP adapter exists for
# this family was NOT established — do not assume one.
#
# DRIVE-SIDE SETUP (without these the drive ACKs writes and ignores them):
#   58.01 = Modbus RTU, 58.03 node address, 58.04 baud, 58.05 parity,
#   58.25 = ABB Drives (default), 58.33 = Mode 0 (default),
#   20.01 / 20.06 = Embedded fieldbus  (start-stop source)
#   22.11 / 22.18 = EFB ref1           (speed reference source)
#   28.11 / 28.15 = EFB ref1           (frequency reference source)
#   then 58.06 = Refresh settings to validate.   (pp. 353-356)
#
# ADDRESSING (58.33 Mode 0, p.262). The manual uses 6-digit registers:
#   6-digit register = 400000 + 100 * group + index
# Register 400001 is the fixed control word, which is 0-based protocol address
# 0, so 0-based = (6-digit) - 400001, i.e.
#   0-BASED REGISTER = 100 * group + index - 1
# Worked examples:
#   par 01.06 Output frequency -> 100*1  + 6  - 1 = 105
#   par 06.16 Drive status word 1 -> 100*6 + 16 - 1 = 615
#   the manual's own example 22.80 -> 402280 -> 402280 - 400001 = 2279
# 32-bit parameters use a different Mode 0 formula (420000 + 200*group +
# 2*index); nothing below uses it, everything here is 16-bit.
#
# SCALING IS FIELDBUS (FbEq16), NOT PANEL DECIMALS, and it is CONFIGURATION-
# DEPENDENT. Group 01 actual values are scaled by group 46 (pp. 93-95). The
# scales below use the group 46 DEFAULTS read on pp. 248-249:
#   46.01 Speed scaling     default 1500.00 rpm = 20000  -> 0.075 rpm/count
#   46.02 Frequency scaling default   50.00 Hz  = 20000  -> 0.0025 Hz/count
#   46.03 Torque scaling    default  100.0 %    = 10000  -> 0.01 %/count
#   46.04 Power scaling     default 1000.00     = 10000  -> 0.1 kW/count
#   46.05 Current scaling   default 10000 A     = 10000  -> 1.0 A/count
# If 46.01-46.05 have been changed on the unit, these scales are WRONG.
# Confirm them on the actual drive. Only 01.11 (10 = 1 V) and 01.13 (1 = 1 V)
# are fixed by the manual and independent of group 46.

name = "ABB ACS280"
vendor = "ABB"
device_type = "vfd"
verified = false
probe_register = 3  # fixed status word, readable whenever the fieldbus is alive

# 58.04 / 58.05 defaults, p.354.
[serial]
baudrate = 19200
parity = "E"
stopbits = 1

[monitor]
control_word = { address = 0, bits = { 0 = "OFF1", 1 = "OFF2_N", 2 = "OFF3_N", 3 = "RUN", 4 = "RAMP_OUT_ZERO_N", 5 = "RAMP_HOLD_N", 6 = "RAMP_IN_ZERO_N", 7 = "RESET", 8 = "JOGGING_1", 9 = "JOGGING_2", 10 = "REMOTE_CMD", 11 = "EXT_CTRL_LOC" } }
reference_1 = { address = 1, signed = true, scale = 0.005, unit = "%" }  # 20000 = 100% of the active group 46 scaling (p.368)
status_word = { address = 3, bits = { 0 = "RDY_ON", 1 = "RDY_RUN", 2 = "RDY_REF", 3 = "TRIPPED", 4 = "OFF_2_INACTIVE", 5 = "OFF_3_INACTIVE", 6 = "SWC_ON_INHIB", 7 = "ALARM", 8 = "AT_SETPOINT", 9 = "REMOTE", 10 = "ABOVE_LIMIT" } }
motor_speed = { address = 100, signed = true, scale = 0.075, unit = "rpm" }   # 01.01 via 46.01. CONFIG-DEPENDENT.
output_frequency = { address = 105, signed = true, scale = 0.0025, unit = "Hz" }  # 01.06 via 46.02. CONFIG-DEPENDENT.
motor_current = { address = 106, scale = 1.0, unit = "A" }        # 01.07 via 46.05, default 10000 = 10000 A
motor_torque = { address = 109, signed = true, scale = 0.01, unit = "%" }   # 01.10 via 46.03, default 10000 = 100.0%
dc_voltage = { address = 110, scale = 0.1, unit = "V" }           # 01.11, 10 = 1 V (fixed, p.93)
output_voltage = { address = 112, unit = "V" }                    # 01.13, 1 = 1 V (fixed, p.93)
output_power = { address = 113, signed = true, scale = 0.1, unit = "kW" }   # 01.14 via 46.04, default 10000 = 1000.00 kW
# 01.14's unit follows 96.16 Unit selection (p.94) — "kW" assumes the default.
# 06.16 Drive status word 1 (p.104). This is a PARAMETER register, not the
# fixed fieldbus status word at address 3, and it is the only place the manual
# states an unambiguous "1 = Drive is running" bit.
drive_status_word_1 = { address = 615, bits = { 0 = "ENABLED", 1 = "INHIBITED", 2 = "DC_CHARGED", 3 = "READY_TO_START", 4 = "FOLLOWING_REFERENCE", 5 = "STARTED", 6 = "MODULATING", 7 = "LIMITING", 8 = "LOCAL_CONTROL", 10 = "EXT1_ACTIVE", 11 = "EXT2_ACTIVE", 13 = "START_REQUEST", 14 = "RUNNING" } }
# 04.01-04.03 are three CONCURRENT active faults, not a history (p.97).
active_fault_2 = { address = 401 }
active_fault_3 = { address = 402 }

# ABB Drives profile. Control-word values are the manual's own, p.367:
#   start  476h -> (when SW bit0 = 1) 477h -> 47Fh
#   stop   477h = "stop according to 21.03 Stop mode"
#          47Eh = OFF1 ramp stop (uninterruptible) — not used here, 477h obeys
#          the drive's configured stop mode
# The master must keep refreshing the control word or the drive trips 6681
# EFB comm loss after 58.16 Communication loss time (default 3.0 s, p.354).
[control]
command_register = 0
speed_register = 1
speed_scale = 0.005     # write %, 20000 raw = 100% of the active group 46 scaling
speed_signed = true     # direction IS the sign of the reference here
speed_unit = "%"        # NOT Hz — percent of the drive's max reference
max_ref = 100.0
step_delay = 0.05
stop = [0x0477]
run_fwd = [0x0476, 0x0477, 0x047F]
# Reset is a RISING EDGE of control-word bit 7 (p.367, and the bit table on
# p.360), laid on top of the stopped word — there is no separate reset
# register on this drive, so reset_register is deliberately absent. A value
# such as 0x0480 would drive OFF1/OFF2/OFF3 low, which is Emergency OFF /
# Emergency stop, not a reset.
reset = [0x0477, 0x04F7, 0x0477]
# run_rev is deliberately absent. On the ABB Drives profile the reference is a
# sign bit plus a 15-bit integer and a negative reference is the two's
# complement (p.367), so direction comes from the SIGN OF THE REFERENCE and a
# "reverse" control word would be byte-identical to forward.

[control.watchdog]
interval_ms = 300
fault = "6681 EFB comm loss"

# 06.16 Drive status word 1 bit 14 "1 = Drive is running" (p.104). Preferred
# over status-word bit 2 (RDY_REF / OPERATION ENABLED), which means the drive
# will accept a reference, not that the motor is turning. Note that other
# pages of this manual loosely call bit 6 "Running"; bit 6 is Modulating in
# the bit table itself, and the bit table is what is used here.
[running_check]
register = 615
bit = 14

# 04.01 Tripping fault; stored history is 04.11-04.13 (addresses 410-412), p.97.
[faults]
register = 400
history = [410, 411, 412]

# 99.06 Motor nominal current, p.289. FbEq16 is stated as "1 = 1 A (see par.
# 46.05)", and 46.05 defaults to 10000 A = 10000 counts (p.249), so 1 count =
# 1 A with default scaling. RESOLUTION CAVEAT: at 1 A per count a 4.6 A and a
# 5.4 A motor both read 5, so this guard catches a gross frame mismatch, not a
# near-miss. If 46.05 has been changed on the unit this scale is wrong.
[rating]
register = 9905
words = 1
scale = 1.0
unit = "A"
label = "Motor nominal current (99.06)"

# [parameters] is deliberately absent. GAP: this manual publishes the Mode 0
# addressing formula but no consolidated writable-parameter table for cloning;
# the read-only flag lives per parameter across the ~200-page group listing.
# Asserting a range here would be a judgment call, not a vendor citation, and
# a clone range that swept in read-only or hardware-identity parameters is
# exactly the restore hazard the guard exists to prevent. Needs a bench pass.

# ABB reports faults as hex codes; TOML keys here are the decimal equivalents
# and the hex is repeated in the text. Taken only from the "Fault messages"
# table, pp. 340-350 of this manual. The WARNING table (A-codes, pp. 330-339)
# is a different table and is NOT included — a warning code decoded here would
# be a misdecode. Auxiliary sub-codes are not represented.
[faults.codes]
0 = "No fault"
4224 = "0x1080 Backup/Restore timeout"
4225 = "0x1081 Rating ID fault"
8833 = "0x2281 Calibration"
8976 = "0x2310 Overcurrent"
9008 = "0x2330 Earth leakage"
9024 = "0x2340 Short circuit"
9089 = "0x2381 IGBT overload"
12592 = "0x3130 Input phase loss"
12673 = "0x3181 Cross connection"
12816 = "0x3210 DC link overvoltage"
12832 = "0x3220 DC link undervoltage"
13185 = "0x3381 Output phase loss"
13189 = "0x3385 Autophasing"
16656 = "0x4110 Control board temperature"
16768 = "0x4180 Excess temperature difference"
16912 = "0x4210 IGBT overtemperature"
17040 = "0x4290 Cooling"
17137 = "0x42F1 IGBT temperature"
17168 = "0x4310 Excess temperature"
18817 = "0x4981 External temperature 1"
20624 = "0x5090 STO hardware failure"
20625 = "0x5091 Safe torque off"
20626 = "0x5092 PU logic error"
20627 = "0x5093 Rating ID mismatch"
20628 = "0x5094 Measurement circuit"
20632 = "0x5098 I/O communication"
20640 = "0x50A0 Fan"
22145 = "0x5681 PU communication"
22146 = "0x5682 Power unit lost"
22160 = "0x5690 PU communication"
22161 = "0x5691 Measurement circuit"
22162 = "0x5692 PU board powerfail"
22163 = "0x5693 Measurement circuit"
22166 = "0x5696 PU state feedback"
22167 = "0x5697 Charging feedback"
24961 = "0x6181 FPGA version"
25088 = "0x6200 Checksum mismatch"
25729 = "0x6481 Task overload"
25735 = "0x6487 Stack overflow"
25761 = "0x64A1 Internal file load"
25766 = "0x64A6 Adaptive program"
25778 = "0x64B2 User set fault"
25825 = "0x64E1 Kernel overload"
25985 = "0x6581 Parameter system"
26241 = "0x6681 EFB comm loss"
26242 = "0x6682 EFB config file"
26243 = "0x6683 EFB invalid parameterization"
26244 = "0x6684 EFB load fault"
26245 = "0x6685 EFB fault 2"
26246 = "0x6686 EFB fault 3"
26754 = "0x6882 Text 32-bit table overflow"
26757 = "0x6885 Text file overflow"
28801 = "0x7081 Control panel loss"
28802 = "0x7082 I/O module comm loss"
28806 = "0x7086 I/O module AI overvoltage"
28961 = "0x7121 Motor stall"
28962 = "0x7122 Motor overload"
29059 = "0x7183 BR excess temperature"
29456 = "0x7310 Overspeed"
29616 = "0x73B0 Emergency ramp failed"
29680 = "0x73F0 Overfrequency"
32769 = "0x8001 ULC underload fault"
32770 = "0x8002 ULC overload fault"
32928 = "0x80A0 AI supervision"
32944 = "0x80B0 Signal supervision 1"
32945 = "0x80B1 Signal supervision 2"
32946 = "0x80B2 Signal supervision 3"
32947 = "0x80B3 Signal supervision 4"
32948 = "0x80B4 Signal supervision 5"
32949 = "0x80B5 Signal supervision 6"
36993 = "0x9081 External fault 1"
36994 = "0x9082 External fault 2"
36995 = "0x9083 External fault 3"
36996 = "0x9084 External fault 4"
36997 = "0x9085 External fault 5"
64129 = "0xFA81 Safe torque off 1"
64130 = "0xFA82 Safe torque off 2"
65377 = "0xFF61 ID run"
65422 = "0xFF8E EFB force trip"

[connection]
summary = "Connect Modbus RTU directly to the ACS280 front EIA-485 terminals 13-15."
warnings = ["The physical order is A-, B+, GND; follow the printed labels rather than assuming the common B/A terminal order.","Ground the outer shield 360 degrees under the control-cable grounding clamp."]

[[connection.methods]]
id = "built_in_rs485"
title = "Built-in Modbus RTU"
transport = "serial"
hardware = "built_in"
port = "front EIA-485 terminal group"
connector = "13 A-, 14 B+, 15 GND; J2 termination"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded twisted pair, 100-130 ohm characteristic impedance, plus signal reference"
parts = ["Isolated USB-to-RS-485 adapter","Shielded twisted pair, 100-130 ohm characteristic impedance, plus signal reference","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 front EIA-485 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 J2 termination only at a physical bus end.","Set 58.01 = Modbus RTU, node address, baud and parity.","Select Embedded fieldbus for commands/references and apply the communication settings."]
warnings = []
source = "ABB 3AXD50001017729, pp. 22 and 352-353."

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

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

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

[[connection.methods.wiring]]
adapter = "Cable shield"
device = "360-degree grounding clamp"
signal = "Outer shield bond"
required = false