# Property of PMA Electrical Solutions, LLC.
#
# ABB ACS310 ONLY. Pump/fan drive, embedded fieldbus (EFB).
# NOT claimed: ACS355, ACS150, ACS550, ACS580 or any other ABB family. The
# ABB drives profile control/status word LAYOUT is shared across the portfolio,
# but the actual-signal numbers, the fault code table and the PFC/SPFC groups
# in this file were read out of the ACS310 manual and are claimed for the
# ACS310 alone.
#
# Communication path: embedded Modbus RTU on the drive itself — no option
# module. Either EIA-485 on I/O terminals 23-26 (multipoint, what this profile
# assumes) or RS-232 on the panel connector X2 (point-to-point, needs drive
# firmware 4.02A or later). Doc p. 288, p. 54.
#
# Source: ABB User's manual, ACS310 drives, doc 3AUA0000044201 rev D (EN),
# 376 pp. Page numbers below are PRINTED pages.
#   pp. 288-292   communication path and drive-side setup parameters
#   p.  294-297   fieldbus reference selection, scaling and direction handling
#   p.  299-301   register mapping, function codes, addressing formula
#   pp. 303-306   ABB drives profile control word, status word, state diagram
#   pp. 170-176   groups 01 / 03 / 04 actual signals and their FbEq scaling
#   p.  217       3018 COMM FAULT FUNC / 3019 COMM FAULT TIME
#   p.  285       9906 MOTOR NOM CURR range and scale
#   pp. 320-326   fault code table (complete — ends at 1017 PAR SETUP 1)
#
# Drive-side setup. Without these the drive ACKs writes and ignores them:
#   9802 COMM PROT SEL = STD MODBUS      (EIA-485)  — p. 289
#   5302 EFB STATION ID = slave address (factory default 1, p. 259; the
#        AC500 MODBUS application macro sets it to 2, p. 114)
#   5303 EFB BAUD RATE  (DEFAULT 9.6 kbit/s, not 19.2)
#   5304 EFB PARITY     (default 8 NONE 1)
#   5305 EFB CTRL PROFILE = ABB DRV FULL — REQUIRED for this profile. The
#        control-word values below set bits 4 and 10, which exist only in ABB
#        DRV FULL (p. 303-304). Under ABB DRV LIM those bits are "not in use";
#        under DCU PROFILE the control word is 32 bits at 40031-40034 and
#        NOTHING in this file applies.
#   1001 EXT1 COMMANDS = COMM            (start/stop from the fieldbus)
#   1103 REF1 SELECT   = COMM            (REF1 from register 40002)
#   1604 FAULT RESET SEL = COMM          (enables control-word bit 7 reset)
#   1601 RUN ENABLE = COMM if the Run-enable interlock is to come from bit 3.
#   1102 EXT1/EXT2 SEL = COMM only if control-location switching is wanted.
#   Settings take effect at the next power-up, or when 5302 is re-written (p. 290).
#
# ADDRESSING FORMULA — 0-based protocol addresses throughout, never 4xxxx.
# The manual publishes 4xxxx (Modicon) numbers and then states the conversion
# itself on p. 301: "In the Modbus data message, register 4xxxx is addressed as
# xxxx-1. For example register 40002 is addressed as 0001."
#   Fixed profile registers (p. 300):  0-based = (4xxxx suffix) - 1
#     40001 Control Word  -> 0
#     40002 Reference 1   -> 1
#     40004 Status Word   -> 3
#   Drive parameters (p. 299): "40101...49999 are reserved for drive parameters
#   0101...9999 (eg 40102 is parameter 0102)", so
#     0-based = 100 * group + index - 1
#     0103 OUTPUT FREQ    -> 100*1 + 3 - 1  = 102
#     0401 LAST FAULT     -> 100*4 + 1 - 1  = 400
#     9906 MOTOR NOM CURR -> 100*99 + 6 - 1 = 9905
#   Addresses that do not correspond to a real parameter are invalid and the
#   drive answers exception 02 (p. 299, p. 301). All reads/writes are FC03 /
#   FC06 / FC16 on the 4x holding space; FC04 is a DIFFERENT space here (the
#   two analog inputs, p. 298) and is not used.
#
# CONFIGURATION-DEPENDENT, do not treat as fixed:
#   - REF1 scaling is 20000 = parameter 1105 REF1 MAX (p. 296). The Hz per raw
#     count therefore depends on the operator's 1105 setting. This profile
#     writes PERCENT (20000 = 100%), which is what the register actually takes;
#     it is not Hz.
#   - The final reference is limited by 1104/1105 and the motor speed by
#     2007/2008 (p. 296), so a commanded 100% is not necessarily 100% of the
#     motor's capability.
#   - Registers 40005-40012 (0-based 4-11) are eight operator-selected actual
#     value slots, chosen by parameters 5310-5317, which default to "not
#     selected" (p. 300). They are DELIBERATELY ABSENT from [monitor] below —
#     the monitor points here address the parameters directly through the
#     40101-49999 mapping instead, which needs no site commissioning.

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

[serial]
baudrate = 9600   # 5303 EFB BAUD RATE default, doc p. 260
parity = "N"      # 5304 EFB PARITY default 8 NONE 1, doc p. 260
stopbits = 1

[monitor]
# Fixed profile registers, doc p. 300 and pp. 303-305.
control_word = { address = 0, bits = { 0 = "OFF1", 1 = "OFF2_N", 2 = "OFF3_N", 3 = "INHIBIT_OPERATION_N", 4 = "RAMP_OUT_ZERO_N", 5 = "RAMP_HOLD_N", 6 = "RAMP_IN_ZERO_N", 7 = "RESET", 10 = "REMOTE_CMD", 11 = "EXT_CTRL_LOC", 12 = "MOTOR_HEAT" } }
reference_1 = { address = 1, signed = true, scale = 0.005, unit = "%" }  # 20000 = 100% of par 1105
status_word = { address = 3, bits = { 0 = "RDY_ON", 1 = "RDY_RUN", 2 = "RDY_REF", 3 = "TRIPPED", 4 = "OFF_2_STA", 5 = "OFF_3_STA", 6 = "SWC_ON_INHIB", 7 = "ALARM", 8 = "AT_SETPOINT", 9 = "REMOTE", 10 = "ABOVE_LIMIT", 11 = "EXT_CTRL_LOC", 12 = "EXT_RUN_ENABLE", 13 = "MOTOR_HEAT" } }

# Group 01 OPERATING DATA, FbEq column on doc p. 170. Addressed as parameters.
motor_speed = { address = 100, signed = true, scale = 1.0, unit = "rpm" }  # 0101 SPEED & DIR — negative = reverse
output_frequency = { address = 102, scale = 0.1, unit = "Hz" }    # 0103, 1 = 0.1 Hz
motor_current = { address = 103, scale = 0.1, unit = "A" }        # 0104, 1 = 0.1 A
motor_torque = { address = 104, signed = true, scale = 0.1, unit = "%" }   # 0105, 1 = 0.1%
output_power = { address = 105, scale = 0.1, unit = "kW" }        # 0106, 1 = 0.1 kW
dc_voltage = { address = 106, scale = 1.0, unit = "V" }           # 0107, 1 = 1 V
output_voltage = { address = 108, scale = 1.0, unit = "V" }       # 0109, 1 = 1 V
drive_temp = { address = 109, scale = 0.1, unit = "C" }           # 0110, 1 = 0.1 degC
external_ref_1 = { address = 110, scale = 0.1, unit = "Hz" }      # 0111, 1 = 0.1 Hz
run_time_hours = { address = 113, scale = 1.0, unit = "h" }       # 0114, 1 = 1 h

# Group 03 fault/alarm bitfields, doc pp. 173-175. Bit names are the manual's.
fault_word_1 = { address = 304, bits = { 0 = "OVERCURRENT", 1 = "DC OVERVOLT", 2 = "DEV OVERTEMP", 3 = "SHORT CIRC", 5 = "DC UNDERVOLT", 6 = "AI1 LOSS", 7 = "AI2 LOSS", 8 = "MOT OVERTEMP", 9 = "PANEL LOSS", 11 = "MOTOR STALL", 13 = "EXT FAULT 1", 14 = "EXT FAULT 2", 15 = "EARTH FAULT" } }
# 0306 bit 14 = MOTOR PHASE per the group-03 signal list (p. 174). The fault
# tracing entry for fault 0034 on p. 322 cross-references "0306 bit 4", which
# contradicts p. 174 (bit 4 = CURR MEAS); p. 174 is the authority and is
# self-consistent, so p. 322 is treated as a manual erratum.
fault_word_2 = { address = 305, bits = { 1 = "THERM FAIL", 4 = "CURR MEAS", 5 = "SUPPLY PHASE", 7 = "OVERSPEED", 9 = "DRIVE ID", 10 = "CONFIG FILE", 11 = "SERIAL 1 ERR", 12 = "EFB CON FILE", 13 = "FORCE TRIP", 14 = "MOTOR PHASE", 15 = "OUTP WIRING" } }
fault_word_3 = { address = 306, bits = { 0 = "EFB 1", 1 = "EFB 2", 2 = "EFB 3", 3 = "INCOMPATIBLE SW", 4 = "USER LOAD CURVE", 5 = "UNKNOWN EXTENSION", 6 = "INLET VERY LOW", 7 = "OUTLET VERY HIGH", 8 = "INLET LOW", 9 = "OUTLET HIGH", 15 = "PARAM SETTING" } }   # 0307; bits 10-14 = "System error"
alarm_word_1 = { address = 307, bits = { 0 = "OVERCURRENT", 1 = "OVERVOLTAGE", 2 = "UNDERVOLTAGE", 3 = "DIR LOCK", 4 = "IO COMM", 5 = "AI1 LOSS", 6 = "AI2 LOSS", 7 = "PANEL LOSS", 8 = "DEVICE OVERTEMP", 9 = "MOTOR TEMP", 11 = "MOTOR STALL", 12 = "AUTORESET", 13 = "AUTOCHANGE", 14 = "PFC I LOCK" } }   # 0308
alarm_word_2 = { address = 308, bits = { 1 = "PID SLEEP", 4 = "START ENABLE 1 MISSING", 5 = "START ENABLE 2 MISSING", 6 = "EMERGENCY STOP", 8 = "FIRST START", 10 = "USER LOAD CURVE", 11 = "START DELAY", 13 = "INLET LOW", 14 = "OUTLET HIGH", 15 = "PIPE FILL" } }   # 0309
alarm_word_3 = { address = 309, bits = { 0 = "INLET VERY LOW", 1 = "OUTLET VERY HIGH" } }   # 0310, bits 2-15 reserved

# ABB drives profile, control word at 40001 -> 0-based 0.
# The state diagram on doc p. 306 gives the transitions literally:
#   READY TO SWITCH ON needs CW = xxxx x1*xx xxxx x110
#   READY TO OPERATE   needs CW = xxxx x1*xx xxxx x111
#   OPERATING          needs CW = xxxx x1*xx x111* 1111  (bits 4,5,6 then bit 3)
# 0x0476 = bits 1,2,4,5,6,10 — every interlock released, OFF1 (bit 0) still low.
# 0x047F additionally sets bits 0 and 3, which is the RUN word.
[control]
command_register = 0
speed_register = 1
speed_scale = 0.005     # write %, 20000 raw = 100% of par 1105 REF1 MAX (p. 296)
speed_signed = true     # direction IS the sign of the reference (p. 297)
speed_unit = "%"        # NOT Hz — percent of 1105, whatever the site set it to
max_ref = 100.0
step_delay = 0.05
stop = [0x0476]
run_fwd = [0x0476, 0x047F]
# Reset is control-word BIT 7 on a 0->1 edge (p. 303), not a separate register,
# so there is no reset_register here. The edge is raised on top of the normal
# 0x0476 idle word: 0x04F6 sets bit 7 while OFF1/OFF2/OFF3 stay released.
# Writing a "reset value" that drops bits 1 or 2 would be an Emergency-OFF /
# Emergency-stop command, which the manual carries a WARNING against (p. 303).
reset = [0x0476, 0x04F6, 0x0476]
# run_rev is deliberately absent. Direction on this profile comes from the SIGN
# OF THE REFERENCE (doc p. 297, "Direction determined by the sign of COMM",
# with 1003 DIRECTION = REQUEST), so a reverse control word would be
# byte-identical to forward. Reverse with a negative reference.

# 3018 COMM FAULT FUNC DEFAULTS TO "NOT SEL" (p. 217) — out of the box this
# drive does NOT trip on comm loss, it keeps running. Set 3018 = FAULT to get
# the trip; 3019 COMM FAULT TIME then defaults to 3.0 s. The keepalive below is
# well inside that window either way.
[control.watchdog]
interval_ms = 500
fault = "0028 SERIAL 1 ERR (only if 3018 COMM FAULT FUNC = FAULT)"

# Status word bit 2 RDY_REF = OPERATION ENABLED, the bit the state diagram
# (p. 306) sets on entering OPERATION ENABLED and clears on stop.
[running_check]
register = 3
bit = 2

# 0401 LAST FAULT -> 400; history is 0412/0413 PREVIOUS FAULT 1/2 (pp. 175-176).
[faults]
register = 400
history = [411, 412]

# Complete table from doc pp. 320-326; it ends at 1017 PAR SETUP 1. Codes are
# decimal, as the manual prints them (0001 = 1).
[faults.codes]
0 = "No fault / history clear"
1 = "OVERCURRENT"
2 = "DC OVERVOLT"
3 = "DEV OVERTEMP"
4 = "SHORT CIRC"
6 = "DC UNDERVOLT"
7 = "AI1 LOSS"
8 = "AI2 LOSS"
9 = "MOT OVERTEMP"
10 = "PANEL LOSS"
12 = "MOTOR STALL"
14 = "EXT FAULT 1"
15 = "EXT FAULT 2"
16 = "EARTH FAULT"
18 = "THERM FAIL"
21 = "CURR MEAS"
22 = "SUPPLY PHASE"
24 = "OVERSPEED"
26 = "DRIVE ID"
27 = "CONFIG FILE"
28 = "SERIAL 1 ERR"
29 = "EFB CON FILE"
30 = "FORCE TRIP"
31 = "EFB 1"
32 = "EFB 2"
33 = "EFB 3"
34 = "MOTOR PHASE"
35 = "OUTP WIRING"
36 = "INCOMPATIBLE SW"
38 = "USER LOAD CURVE"
39 = "UNKNOWN EXTENSION"
40 = "INLET VERY LOW"
41 = "OUTLET VERY HIGH"
42 = "INLET LOW"
43 = "OUTLET HIGH"
101 = "SERF CORRUPT"
103 = "SERF MACRO"
201 = "DSP T1"
202 = "DSP T2"
203 = "DSP T3"
204 = "DSP STACK ERROR"
206 = "CB ID ERROR"
1000 = "PAR HZRPM"
1001 = "PAR PFC REF NEG"
1003 = "PAR AI SCALE"
1004 = "PAR AO SCALE"
1006 = "PAR EXT RO"
1012 = "PAR PFC IO 1"
1013 = "PAR PFC IO 2"
1014 = "PAR PFC IO 3"
1015 = "PAR USER DEFINED U/F"
1016 = "PAR USER LOAD C"
1017 = "PAR SETUP 1"

# 9906 MOTOR NOM CURR, range 0.2...2.0 x I2N, "Current 1 = 0.1 A" (doc p. 285).
# Address 100*99 + 6 - 1 = 9905 by the p. 299 parameter mapping.
[rating]
register = 9905
words = 1
scale = 0.1
unit = "A"
label = "9906 MOTOR NOM CURR"

# NO [parameters] BLOCK, DELIBERATELY, even though the address mapping for
# arbitrary parameters IS documented (p. 299, 40101-49999 = 0101-9999).
# Two reasons out of the manual itself:
#   1. Doc p. 300 note: "Parameter writes through standard Modbus are always
#      volatile, ie modified values are not automatically stored to permanent
#      memory. Use parameter 1607 PARAM SAVE to save all changed values."
#      A restore that swept a range would leave the drive looking correct until
#      the next power cycle, which is the worst possible failure mode for a
#      drive-replacement clone. 1607 PARAM SAVE is itself reachable at 41607
#      -> 0-based 1606 (p. 292); supporting restore here needs a write there
#      as its final step, which this profile format has no place for.
#   2. The writable parameter space is sparse (groups 10-99, with gaps inside
#      every group), and p. 299/301 say an address with no matching parameter
#      returns exception 02. Group 01/03/04 are read-only actual signals sitting
#      inside the same mapping. A blind range sweep would write into read-only
#      addresses and stall on exceptions. Enumerating the valid indexes means
#      transcribing ~110 pages of parameter tables (pp. 177-286) and verifying
#      each on a bench; that has not been done.

[connection]
summary = "The ACS310 embedded Modbus interface is available as EIA-485 on X1C terminals 23-26 or, with firmware 4.02A or later, as point-to-point RS-232 on panel connector X2."
warnings = ["Select the matching 9802 mode; the two physical paths are alternatives, not simultaneous masters.","The cached exact-family manual does not publish X2 conductor pins, so use only an ABB-approved preterminated panel cable."]

[[connection.methods]]
id = "x1c_eia485"
title = "X1C EIA-485"
transport = "serial"
hardware = "built_in"
port = "I/O terminal block X1C"
connector = "X1C:23 SCR, 24 B positive, 25 A negative, 26 GND_A; J701 termination"
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 I/O terminal block X1C.","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 J701 termination only at a bus end.","Set 9802 = STD MODBUS and configure 5302/5303/5304/5305 = ABB DRV FULL.","Set the fieldbus command/reference/reset sources; rewrite 5302 or power-cycle to apply."]
warnings = []
source = "ABB 3AUA0000044201 Rev D, pp. 54 and 288-292."

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

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

[[connection.methods.wiring]]
adapter = "COM / signal common"
device = "X1C:26 GND_A"
signal = "Fieldbus common"

[[connection.methods.wiring]]
adapter = "Cable shield"
device = "X1C:23 SCR"
signal = "Shield"
required = false

[[connection.methods]]
id = "x2_rs232"
title = "Panel connector X2 RS-232"
transport = "serial"
hardware = "built_in"
port = "control-panel connector X2"
connector = "RJ-45 control-panel connector; exact conductor pin assignment is not published in 3AUA0000044201"
adapter = "PC RS-232 port or isolated USB-to-RS-232 adapter"
cable = "ABB-approved preterminated RJ-45 control-panel cable, shorter than 3 m"
parts = ["RS-232 port/adapter","ABB-approved preterminated panel cable"]
steps = ["Confirm drive firmware is 4.02A or later.","Lock out the drive and remove the control panel.","Connect the preterminated panel cable to X2 without repinning it.","Restore power with the motor inhibited and verify a point-to-point read."]
setup = ["Set 9802 to the manual's MODBUS RS232 selection.","Match 5302/5303/5304 and set 5305 = ABB DRV FULL.","Set fieldbus command/reference sources and apply the settings."]
warnings = ["Do not fabricate an X2 lead from pin assignments for another ABB family.","Point-to-point only; cable must be shorter than 3 m."]
source = "ABB 3AUA0000044201 Rev D, pp. 54 and 288-292."

[[connection.methods.wiring]]
adapter = "ABB preterminated RS-232 panel cable"
device = "X2 panel connector"
signal = "Complete point-to-point RS-232 path; exact X2 pins not published"