# Property of PMA Electrical Solutions, LLC.
#
# ABB ACH480 ONLY, HVAC control program. No other ABB family is claimed here —
# not ACS480, not ACH580, not ACS580. The ACS480 standard-program map happens
# to agree on group 01 and on the ABB Drives profile words; that agreement is
# not a citation, so each drive keeps its own file. Where the HVAC program DOES
# differ is the fault table: it carries HVAC/pump codes (D404…D40D, D420, D58B)
# that the standard program does not, and it does not list the ACS480's
# 0x3385 Autophasing / 0x5089 SMT circuit / 0xD401 / 0xD40C entries. Only the
# ACH480 HVAC manual was read this session; no side-by-side ACS480 diff was run
# beyond that observation.
#
# Communication path: the EMBEDDED fieldbus interface (EFB), Modbus RTU on the
# drive's own EIA-485 terminals, ABB Drives control profile (58.25 = ABB
# Drives, the default). The DCU profile (58.25 = DCU), BACnet MS/TP, N2 and the
# optional FBA-A adapter-module path are NOT documented here and do not use
# these register numbers.
#
# Source: ABB "ACH480 HVAC control program firmware manual", 3AXD50000247134
# EN (file ach480_hvac_fw_3AXD50000247134.pdf, PDF title verified), pages
# (printed page == PDF page in this file, no front-matter offset):
#   EFB setup + drive-side sources ....... 263-265
#   Control Word (ABB Drives profile) .... 270-271
#   Status Word (ABB Drives profile) ..... 274-275
#   State diagram, start/stop/reset words. 277-279
#   Reference and actual-value scaling ... 280-281
#   Default holding-register map ......... 282
#   Function codes ....................... 283
#   Addressing mode 58.33 ................ 264, 581
#   Group 01 actual values ............... 373-374
#   Group 04 fault codes ................. 377
#   Group 46 scaling defaults ............ 563
#   Fault message table .................. 246-260
#   99.06 additional parameter data ...... 691
#
# Drive-side setup (without these the drive ACKs writes and ignores them),
# p.263-265:
#   58.01 Protocol enable = Modbus RTU; 58.03 node address (default 1);
#   58.04 baud (default 19.2 kbps); 58.05 parity (default 8 EVEN 1);
#   58.25 Control profile = ABB Drives; 20.01 Ext1 commands = Embedded
#   fieldbus (20.06 for EXT2); 22.11 Ext1 speed ref1 = EFB ref1 in speed
#   control, or 28.11 Ext1 frequency ref1 = EFB ref1 in scalar/frequency
#   control (the common HVAC config); then 58.06 Communication control =
#   Refresh settings.
#
# Addressing (58.33 = Mode 0, the default, p.264/581). The manual gives 1-based
# 4xxxxx numbers: register = 400000 + 100*group + index. This repo uses 0-based
# protocol addresses, and 400001 is protocol address 0, so
#   0-based address = (400000 + 100*group + index) - 400001
#                   = 100*group + index - 1
#   manual's own example, par 22.80 -> 402280 -> 402280-400001 = 2279
#                                            and 100*22 + 80 - 1 = 2279
#   par 01.06 Output frequency -> 100*1 + 6 - 1 = 105
# Direct parameter access lives in 400101...465536 (0-based 100...65535);
# 0-based 0...13 are the Data I/O words (p.282). Holding registers via 03h/06h/
# 10h; the coil and discrete-input bit views of CW/SW (p.285-288) are not used.
#
# SCALING IS FIELDBUS (FbEq16), NOT PANEL DECIMALS, and the group 46 values it
# derives from are configuration-dependent (p.280-281, 563). Defaults used
# below: 46.02 = 50.00 Hz (60.00 Hz on a 95.20 b0 / North-America unit, which
# makes the frequency scale 0.003 instead), 46.03 = 100.0%, 46.04 = 1000.00
# units, 46.05 = 10000 A. Confirm 46.02-46.05 on the actual unit before
# trusting them. Note also that the Ref1/Act1 words at 0-based 1/4/5 use the
# ±20000 = 46.01/46.02 (or ±10000 = 46.03/46.04) mapping, selected by 58.26 /
# 58.28 — a different scaling from the raw group-01 registers.
#
# [rating] reads 07.03 Drive rating id — see the block at the end of the
# file. (An earlier revision omitted [rating] claiming 99.06's 16-bit width
# was ambiguous; it is not — p.641 states "For 16-bit scaling, see parameter
# 46.05 Current scaling", and the p.691 "10 = 1 A" is the FbEq32 column,
# which Mode 0 maps to a different address space entirely. 99.06 was still
# rejected as a guard: its resolution at the 46.05 default is a whole amp and
# it is operator-entered motor data, not drive hardware identity.)
# NOT INCLUDED: no [parameters] ranges — the writable range for clone/restore
# was not mined from the parameter table (p.373-693).

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

# 58.04 / 58.05 defaults, p.263.
[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", 10 = "REMOTE_CMD", 11 = "EXT_CTRL_LOC" } }
reference_1 = { address = 1, signed = true, scale = 0.005, unit = "%" }  # 20000 = 100% of 46.01/46.02
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" } }
# 01.06, scaled by 46.02 (default 20000 = 50.00 Hz). CONFIG-DEPENDENT.
output_frequency = { address = 105, signed = true, scale = 0.0025, unit = "Hz" }
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)
output_voltage = { address = 112, unit = "V" }                    # 01.13, 1 = 1 V (fixed)
output_power = { address = 113, signed = true, scale = 0.1, unit = "kW" }   # 01.14 via 46.04, default 10000 = 1000.00 units
# 04.01-04.03 are three CONCURRENT active faults, not a history (p.377).
active_fault_2 = { address = 401 }
active_fault_3 = { address = 402 }

# ABB Drives profile. Control-word values are the manual's own, p.279:
# start 476h -> 47Eh -> 47Fh, stop 477h ("Stop according to 21.03 Stop mode",
# the manual's preferred stop). The master must keep refreshing the control
# word or the drive trips 6681 EFB comm loss — but only if 58.14 Communication
# loss action is changed from its factory default of "No action" (p.263).
[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, 0x047E, 0x047F]
# Reset is a RISING EDGE of control-word bit 7 (p.279) laid on top of the
# stopped word, not a magic value written to the run register. 0x0480 would
# drive OFF1/OFF2/OFF3 low — Emergency OFF / Emergency stop, not a reset.
reset = [0x0477, 0x04F7, 0x0477]
# run_rev is deliberately absent. On the ABB Drives profile direction comes
# from the SIGN OF THE REFERENCE (p.280), so a "reverse" control word would be
# byte-identical to forward. Reverse with a negative reference.

# 58.16 Communication loss time defaults to 30.0 s on this program (p.263);
# 300 ms sits well inside that and inside a shortened setting.
[control.watchdog]
interval_ms = 300
fault = "6681 EFB comm loss"

# The ABB Drives profile Status Word (p.274-275) has NO bit named RUNNING —
# only the DCU profile's Status Word (p.275) has an explicit bit3 "RUNNING:
# drive is modulating". bit2 RDY_REF = OPERATION ENABLED is the closest
# documented proxy on the profile this file uses; it means the drive is in the
# run state, which is not literally "the shaft is turning". Unverified.
[running_check]
register = 3
bit = 2

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

# Fault message table, 3AXD50000247134 pp.246-260. ABB prints hex codes; TOML
# keys must be numeric, so these keys are the decimal equivalents and the hex
# is repeated in the text. Warnings (A-codes, pp.231-245) are NOT listed — they
# are a different table and are not reported in 04.01. Auxiliary codes (the
# 00xx sub-rows under 2340, 64A6, 7087, FF61, D40B, …) are not fault codes and
# are not listed either.
[faults.codes]
0 = "No fault"
4224 = "0x1080 Backup/Restore timeout"
4225 = "0x1081 Rating ID fault"
8976 = "0x2310 Overcurrent"
9008 = "0x2330 Earth leakage"
9024 = "0x2340 Short circuit"
9089 = "0x2381 IGBT overload"
12592 = "0x3130 Input phase loss"
12673 = "0x3181 Wiring or earth fault"
12816 = "0x3210 DC link overvoltage"
12832 = "0x3220 DC link undervoltage"
13185 = "0x3381 Output phase loss"
16656 = "0x4110 Control board temperature"
16912 = "0x4210 IGBT overtemperature"
17040 = "0x4290 Cooling"
17137 = "0x42F1 IGBT temperature"
17168 = "0x4310 Excess temperature"
17280 = "0x4380 Excess temperature difference"
18817 = "0x4981 External temperature 1"
18818 = "0x4982 External temperature 2"
20608 = "0x5080 Fan"
20624 = "0x5090 STO hardware failure"
20625 = "0x5091 Safe torque off"
20626 = "0x5092 PU logic error"
20627 = "0x5093 Rating ID mismatch"
20628 = "0x5094 Measurement circuit temperature"
20632 = "0x5098 I/O communication loss"
20640 = "0x50A0 Fan"
22145 = "0x5681 PU communication"
22146 = "0x5682 Power unit lost"
22161 = "0x5691 Measurement circuit ADC"
22162 = "0x5692 PU board powerfail"
22163 = "0x5693 Measurement circuit DFF"
22167 = "0x5697 Charging feedback"
22168 = "0x5698 Unknown PU fault"
24961 = "0x6181 FPGA version incompatible"
25088 = "0x6200 Checksum mismatch"
25350 = "0x6306 FBA A mapping file"
25729 = "0x6481 Task overload"
25735 = "0x6487 Stack overflow"
25761 = "0x64A1 Internal file load"
25764 = "0x64A4 Rating ID fault"
25766 = "0x64A6 Adaptive program"
25777 = "0x64B1 Internal SSW fault"
25778 = "0x64B2 User set fault"
25779 = "0x64B3 Macro parameterization error"
25825 = "0x64E1 Kernel overload"
25855 = "0x64FF Fault reset"
25985 = "0x6581 Parameter system"
26001 = "0x6591 Backup/Restore timeout"
26017 = "0x65A1 FBA A parameter conflict"
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"
28193 = "0x6E21 Macro parameterization error"
28801 = "0x7081 Control panel loss"
28802 = "0x7082 I/O module comm loss"
28805 = "0x7085 Incompatible option module"
28806 = "0x7086 AI Overvoltage"
28807 = "0x7087 I/O module configuration fault"
28928 = "0x7100 Excitation current"
28961 = "0x7121 Motor stall"
28962 = "0x7122 Motor overload"
29057 = "0x7181 Brake resistor"
29059 = "0x7183 BR excess temperature"
29060 = "0x7184 Brake resistor wiring"
29073 = "0x7191 BC short circuit"
29074 = "0x7192 BC IGBT excess temperature"
29456 = "0x7310 Overspeed"
29616 = "0x73B0 Emergency ramp failed"
29680 = "0x73F0 Overfrequency"
29968 = "0x7510 FBA A communication"
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"
54276 = "0xD404 Running dry"
54277 = "0xD405 Pipe fill-timeout"
54278 = "0xD406 Maximum flow protection"
54279 = "0xD407 Minimum flow protection"
54280 = "0xD408 Outlet minimum pressure"
54281 = "0xD409 Outlet maximum"
54282 = "0xD40A Inlet minimum pressure"
54283 = "0xD40B Damper timeout"
54285 = "0xD40D Multipump run permissive timeout"
54304 = "0xD420 Reverse flow detected"
54667 = "0xD58B Gas pressure outside limits"
64129 = "0xFA81 Safe torque off 1"
64130 = "0xFA82 Safe torque off 2"
65377 = "0xFF61 ID run"
65379 = "0xFF63 STO diagnostics failure"
65409 = "0xFF81 FB A force trip"
65422 = "0xFF8E EFB force trip"

# 07.03 Drive rating id, group 07 System info — "Type of the drive. (Rating
# ID in brackets.)", READ-ONLY ("All parameters in this group are read-only",
# p.389), FbEq 1=1, List 0…999 (p.656). A drive-HARDWARE identity, which is
# what the restore guard needs; the value is an opaque enumeration, so this is
# an equality guard, not a decoded amp figure. 0-based = 100*7 + 3 - 1 = 702.
[rating]
register = 702
words = 1
scale = 1.0
unit = ""
label = "Drive rating id (07.03)"

[connection]
summary = "The ACH480 uses its built-in EIA-485 fieldbus terminals marked B+, A- and DGND for Modbus RTU."
warnings = ["The cached exact-family firmware manual publishes the terminal markings but not a numeric terminal or connector designator; identify the block by the B+/A-/DGND markings and confirm it against the hardware manual for the installed frame."]

[[connection.methods]]
id = "built_in_rs485"
title = "Built-in Modbus RTU"
transport = "serial"
hardware = "built_in"
port = "embedded-fieldbus terminal block marked B+, A-, DGND"
connector = "Open terminals B+, A-, DGND with combined TERM&BIAS switch"
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 embedded-fieldbus terminal block marked B+, A-, DGND.","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 the TERM&BIAS switch only as required for the bus topology.","Set 58.01 = Modbus RTU, 58.03 node address, 58.04 baud, 58.05 parity and 58.25 = ABB Drives.","Select Embedded fieldbus for command and reference sources, then set 58.06 = Refresh settings."]
warnings = ["Do not infer a terminal number from ACS480, ACH580 or another ABB family."]
source = "ABB 3AXD50000247134, pp. 98-101 and 263-265."

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

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

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