# Property of PMA Electrical Solutions, LLC.
#
# ABB ACS 160, Modicon Modbus RTU through the CFB-RS RS485/RS232 Adapter
# Module.
#
# CLAIMED: ACS 160 only.
# NOT CLAIMED: ACS 100 (no serial interface exists on that frame — see
# docs/UNSUPPORTED.md), ACS 140, ACS 400, ACS 600, or any later ABB family.
# The register mapping and the control/status word layout are shared across
# ACS 140/160/400, but each is a separate document with its own parameter
# numbering and its own fault table, so each gets its own file. Nothing here
# was copied from a sibling family.
#
# COMMUNICATION PATH — OPTION MODULE, NOT EMBEDDED.
# The ACS 160 has no built-in serial port. The CFB-RS Adapter Module mounts on
# the drive and is powered through the control-panel connector; RS485 or RS232
# is selected with jumper S3, cabling on X1/X2 (RS485) or X4 (RS232)
# ([CFB] pp. 2-2..2-3, Figure 2-2; the module defaults to RS485 at 9600 bps).
# WITHOUT THE CFB-RS FITTED, NOTHING IN THIS FILE APPLIES.
#
# SOURCES — primary ABB documentation only:
#   [CFB]  ACS 160 Installation and Start-up Guide, RS485 and RS232 Adapter
#          Module CFB-RS, 3BFE 64390431 R0125 EN, effective 23.3.2001.
#          manuals/abb_acs160_cfb_rs_adapter_guide.pdf
# Also cached, but contributing NO register content to this file — it is an
# EMC / supply-voltage and motor-cable-length supplement, listed only for
# completeness of the ACS 160 document set:
#   [SUP]  Supplement to the ACS 160 User's Manual (applies to ACS 160 User's
#          Manual 3BFE 64364120 Rev C or prior).
#          manuals/abb_acs160_supplement_revC.pdf
# Page ranges each section came from (PRINTED page numbers, e.g. "4-5"):
#   [CFB] pp. 2-2..2-3   CFB-RS mounting, panel-connector power, S3, X1/X2/X4
#   [CFB] pp. 3-2..3-4   Group 52 SERIAL COMM parameters, comm-loss behaviour
#   [CFB] p.  3-5        control locations (groups 10, 11, 16 of the User's Manual)
#   [CFB] pp. 4-1..4-2   register mapping 4GGPP, Table 4-1
#   [CFB] pp. 4-3..4-4   Table 4-2 exception codes, Table 4-3 function codes
#   [CFB] pp. 4-4..4-5   Table 4-4 Control Word bits
#   [CFB] p.  4-6        Table 4-5 worked start sequence
#   [CFB] p.  4-7        Table 4-6 Status Word bits
#   [CFB] pp. 4-8..4-9   reference scaling
#   [CFB] p.  4-11       Actual Value 1 / 2 scaling
#   [CFB] p.  4-12       Figure 4-1 state machine
#   [CFB] pp. 4-13..4-15 Table 4-8 fault/alarm words, Table 4-9, Table 4-10
#
# NAMED GAP — NO NUMERIC FAULT-CODE TABLE, NO RATING REGISTER.
# The English ACS 160 User's Manual (3BFE 64364120 Rev C) could not be
# retrieved from library.e.abb.com; only translated editions resolved and the
# English filenames returned 403. [CFB] itself defers both the numeric fault
# codes ("See also the Diagnostics section in the ACS 160 User's Manual",
# p. 4-14) and the motor-rating parameters to that manual. Consequently:
#   * [faults] below is the FAULT WORD 1 BITFIELD ONLY — no numeric code table
#     is filled in, because none was sourced. Do not add one by analogy to the
#     ACS 140 or ACS 400; those are different fault lists on different drives.
#   * There is NO [rating] block. The ACS 140 and ACS 400 both use 9906 MOTOR
#     NOM CURR and the ACS 160 very likely does too, but "very likely" is not
#     a source, and a wrong rating register makes the restore guard fail OPEN
#     (an unreadable value compares equal and waves the clone through).
#     Confirm 99xx against the ACS 160 User's Manual before adding one.
#   * NO [faults] history. [CFB] p. 4-2 Table 4-1 does publish 40130 OLDEST
#     FAULT (0-based 129) and it is addressable, but it returns a NUMERIC code
#     and [faults] here is the FAULT WORD 1 BITFIELD. Listing 129 as history
#     under bitfield = true would decode a fault number as sixteen flags. It
#     stays out until the numeric code table is sourced, at which point the
#     whole [faults] block should move to the numeric register.
#
# DRIVE-SIDE SETUP. Without these the drive ACKs writes and ignores them
# ([CFB] p. 3-5 points at groups 10, 11 and 16 of the User's Manual):
#   1001 EXT1 COMMANDS  = COMM     start/stop/direction from the serial link
#   1102 EXT1/EXT2 SEL             so Control Word bit 11 picks EXT1/EXT2
#   1103 EXT REF1 SELECT = COMM (or COMM+AI1 / COMM*AI1, [CFB] p. 4-9)
#   1601 RUN ENABLE     Control Word bit 3 ALSO requires the Run Enable signal
#                       on a DIGITAL INPUT — Status Word bit 12 must read 1 or
#                       run_fwd stalls at OPERATION ENABLED with no error
#                       ([CFB] pp. 4-5, 4-12). Unlike the ACS 140, no COMM
#                       source is documented for 1601 on this drive, so this is
#                       a WIRING prerequisite, not a parameter one.
#   group 16 (fault-reset source) — NOT SOURCED. [CFB] p. 3-5 defers groups 10,
#                       11 and 16 to the ACS 160 User's Manual, which could not
#                       be retrieved. Table 4-4 (p. 4-5) states NO gate on
#                       Control Word bit 7. If the ACS 160 follows the ACS
#                       140/400 pattern, a reset-source parameter must be set
#                       to COMM before the reset sequence below does anything —
#                       but that is not sourced here. CONFIRM BEFORE RELYING ON
#                       reset. (An earlier revision of this file named "1604
#                       FAULT RESET SEL" here. That number appears nowhere in
#                       either ACS 160 document — it was carried in from the
#                       ACS 140/400 manuals, and it was carried in incomplete:
#                       those manuals default it to 6 START/STOP and require
#                       7 COMM for bit-7 reset to work at all.)
#   5201 STATION NUMBER = 1..247 (default 1)
#   5202 COMM SPEED     = 3..192 (default 96 = 9600 bps)
#   5203 PARITY         = 0 NONE / 1 EVEN / 2 ODD (default 0)
#   5204 COMM FAULT TIME / 5205 COMM FAULT FUNC — see the watchdog note below
# NOTE: 5201/5202/5203 changes "take effect only on the next power up"
# ([CFB] pp. 3-3..3-4).
#
# ADDRESSING FORMULA — 0-BASED PROTOCOL ADDRESSES THROUGHOUT, never 4xxxx.
# [CFB] p. 4-2 Table 4-1 publishes the Modicon mapping as 4GGPP, where GG is
# the drive parameter group and PP the parameter index within it. Modbus
# holding register 40001 is protocol address 0, so:
#     0-based = (4xxxx number) - 40001 = 100 * group + index - 1
# Worked examples:
#     Control Word  40001 -> 40001 - 40001 = 0
#     Status Word   40004 -> 40004 - 40001 = 3
#     0305 FAULT WORD 1   -> 40305 - 40001 = 100*3 + 5 - 1 = 304
#     1105 EXT REF1 MAX   -> 41105 - 40001 = 100*11 + 5 - 1 = 1104
# "The register addresses between the groups are invalid" and answer with
# exception 02 ILLEGAL DATA ADDRESS ([CFB] pp. 4-2..4-3). Function codes 03,
# 06 and 16 (0x10) only ([CFB] p. 4-4).
#
# CONFIGURATION-DEPENDENT, do not treat any of this as fixed:
#   - Reference 1 scaling is 20000 = parameter 1105 EXT REF1 MAX, a Hz value
#     the site sets ([CFB] p. 4-9). This profile therefore writes PERCENT of
#     1105, which is what the register actually takes. It is NOT Hz.
#     THE MANUAL CONTRADICTS ITSELF ON WHICH PARAMETER IS FULL SCALE. p. 4-9
#     states 1105 explicitly, which is why the scale below follows it — but
#     the worked example on the facing p. 4-10 uses 2008 MAXIMUM FREQ instead
#     ("Assume that 2008 MAXIMUM FREQ = 50 Hz ... fieldbus reference 1 is 5000
#     (corresponding to 25 % of full scale)"). Set 1105 = 2008 on the drive to
#     remove the ambiguity; otherwise a commanded 50% lands somewhere else.
#   - If 1103 is set to COMM+AI1 or COMM*AI1, analogue input AI1 CORRECTS the
#     fieldbus reference ([CFB] p. 4-9, Table 4-7) — the commanded value is
#     then not the value the drive runs at. Use plain COMM for predictable
#     remote control.
#   - Actual Value 1 / 2 (registers 4 and 5) are the one pair with a fixed
#     documented scaling: 5000 = 50 Hz and 10 = 1 A ([CFB] p. 4-11).

name = "ABB ACS160"
vendor = "ABB"
device_type = "vfd"
verified = false
probe_register = 3  # 40004 Status Word, readable whenever the link is alive

# [CFB] pp. 3-2, 3-3: default 9600 bps, parity NONE. "In Modbus communication,
# the number of stop bits is 2 with no parity bit, and 1 with even or odd
# parity" — so the default combination is N,2.
[serial]
baudrate = 9600
parity = "N"
stopbits = 2

[monitor]
# Drive control registers, [CFB] Table 4-1. Bit names from Table 4-4 / 4-6.
# Bit 10 REMOTE_CMD of the ABB Drives profile is explicitly NOT USED on this
# drive ([CFB] p. 4-4 note) and is deliberately not named.
control_word = { address = 0, bits = { 0 = "ON_OFF1", 1 = "OFF2_N", 2 = "OFF3_N", 3 = "START", 5 = "RAMP_HOLD_N", 6 = "RAMP_IN_ZERO_N", 7 = "RESET", 11 = "EXT_CTRL_LOC" } }
reference_1 = { address = 1, signed = true, scale = 0.005, unit = "%" }  # 20000 = par 1105 EXT REF1 MAX
reference_2 = { address = 2, signed = true, scale = 0.01, unit = "%" }   # 10000 = par 1108 EXT REF2 MAX
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", 11 = "EXT_CTRL_LOC", 12 = "RUN_ENABLE" } }
# Fixed fieldbus scaling, [CFB] p. 4-11.
output_frequency = { address = 4, signed = true, scale = 0.01, unit = "Hz" }  # 5000 = 50 Hz
motor_current = { address = 5, signed = true, scale = 0.1, unit = "A" }       # 10 = 1 A

# Group 3 fault/alarm status words, [CFB] p. 4-13 Table 4-8. Read-only, except
# that writing 0 to an ALARM word clears it.
main_command_word = { address = 300 }
main_status_word = { address = 301 }
# Table 4-9. Fault Word 2 carries only bits 0, 2 and 8 on this drive; bits 1
# and 3 are printed as Reserved and the rest are blank, so only the three
# named bits appear here.
fault_word_2 = { address = 305, bits = { 0 = "Underload", 2 = "DDCS Link", 8 = "Hardware error" } }
alarm_word_1 = { address = 307, bits = { 0 = "Overcurrent controller alarm", 1 = "Overvoltage controller alarm", 2 = "Undervoltage controller alarm", 3 = "Direction lock alarm", 4 = "Serial communication loss", 5 = "Modbus exception", 6 = "Analogue input 1 loss", 7 = "Analogue input 2 loss", 8 = "Panel loss", 9 = "ACS 160 overtemperature", 10 = "Motor overtemperature", 11 = "Underload" } }
alarm_word_2 = { address = 308, bits = { 0 = "Overload alarm", 1 = "Autoreset alarm", 2 = "PID sleep alarm", 5 = "Brake resistor overload alarm" } }

# ABB Drives profile, Control Word at 40001 -> 0-based 0 ([CFB] p. 4-4).
# The start sequence is printed LITERALLY in [CFB] p. 4-6 Table 4-5:
#   Step 1  CW = 0000 0000 0000 0110 = 0x0006 -> READY TO SWITCH ON
#   Step 2  wait at least 100 ms
#   Step 3  CW = 0000 0000 0000 0111 = 0x0007 -> READY TO OPERATE
#   Step 4  CW = 0000 0000 0000 1111 = 0x000F -> OPERATION ENABLED (starts,
#                                                but does not accelerate)
#   Step 5  CW = 0000 0000 0010 1111 = 0x002F -> RFG: ACCELERATOR ENABLED
#   Step 6  CW = 0000 0000 0110 1111 = 0x006F -> OPERATING, follows reference
# step_delay is 0.1 s to honour the manual's explicit "wait at least 100 ms".
[control]
command_register = 0
speed_register = 1
speed_scale = 0.005     # write %, 20000 raw = 100% of par 1105
speed_signed = true     # direction IS the sign of the reference
speed_unit = "%"        # NOT Hz — percent of 1105, whatever the site set it to
max_ref = 100.0
step_delay = 0.1
# Stop is the manual's own Step 1 word: bit 0 = 0 is OFF1, "Ramp to stop
# according to parameter 2203 DECELER TIME 1". Bits 1 and 2 stay HIGH, so this
# is NOT the Emergency OFF coast-to-stop (bit 1 low) or the Emergency stop on
# 2205 (bit 2 low) — [CFB] p. 4-5.
stop = [0x0006]
run_fwd = [0x0006, 0x0007, 0x000F, 0x002F, 0x006F]
# Reset is Control Word BIT 7 on a 0->1 EDGE ([CFB] p. 4-5), not a separate
# register, so there is no reset_register. The edge is raised on top of the
# idle word: 0x0086 sets bit 7 while OFF2/OFF3 (bits 1, 2) stay released.
reset = [0x0006, 0x0086, 0x0006]
# run_rev is deliberately absent. "A negative reference (indicating reversed
# direction of rotation) is formed by calculating the two's complement"
# ([CFB] p. 4-8) — direction is the SIGN of the reference, so a "reverse"
# control word would be byte-identical to forward. Reverse with a negative
# reference, and check 1003 DIRECTION allows it.

# 5205 COMM FAULT FUNC DEFAULTS TO 0 (NOT SEL), so out of the box this drive
# does NOT trip on comm loss. When 5205 is set to 1 (FAULT) the drive coasts
# to stop after 5204 COMM FAULT TIME (default 1.0 s). "The master device ...
# must signal its presence to every slave device ... by periodically writing
# Command Word, External Reference 1 or External Reference 2" ([CFB] p. 3-3).
# The fault appears as FAULT WORD 1 bit 13 Serial communication loss; its
# numeric panel code lives in the User's Manual that could not be sourced, so
# only the bit name is claimed. 300 ms is well inside the 1.0 s default;
# shorten it if the site has lowered 5204.
[control.watchdog]
interval_ms = 300
fault = "Serial communication loss (ONLY if 5205 COMM FAULT FUNC = 1 Fault; the factory default is 0 NOT SEL and the drive keeps running), timeout 5204"

# Status Word bit 2 OPERATION ENABLED — the bit the state machine
# ([CFB] p. 4-12, Figure 4-1) sets on the run transition and clears on
# OFF1/OFF2/OFF3. Bit 8 AT_SETPOINT is stricter and reads false while
# accelerating.
[running_check]
register = 3
bit = 2

# 0305 FAULT WORD 1 as a BITFIELD, [CFB] p. 4-14 Table 4-9. See the header:
# no numeric fault-code table is claimed for this drive, because the ACS 160
# Diagnostics section was not sourced. Nothing is to be filled in here from
# another family's manual or from memory.
[faults]
register = 304
bitfield = true
bits = { 0 = "Overcurrent", 1 = "DC overvoltage", 2 = "ACS160 overtemperature", 3 = "Fault current", 4 = "Output overload", 5 = "DC undervoltage", 6 = "Analogue input 1 fault", 7 = "Analogue input 2 fault", 8 = "Motor overtemperature", 9 = "Panel loss", 10 = "Parameters inconsistent", 11 = "DC bus ripple too large", 12 = "Motor stall", 13 = "Serial communication loss", 14 = "External fault", 15 = "Output earth fault" }

# NO [rating] BLOCK — see the NAMED GAP note in the header. The restore guard
# fails OPEN, so a guessed rating register is worse than none.
#
# NO [parameters] BLOCK, DELIBERATELY. [CFB] p. 4-2 publishes the 4GGPP
# mapping but prints only four example group rows and then "…"; addresses in
# the gaps between groups are invalid and answer with exception 02, so a blind
# range sweep for a clone/restore would stall on the first gap. Group 01
# actual values never accept writes and group 99 only accepts them while
# stopped ([CFB] p. 4-1), so the ranges are not uniform either.

[connection]
summary = "The ACS160 requires the side-mounted CFB-RS adapter, which supports either RS-485 multidrop or RS-232 point-to-point Modbus."
warnings = ["The CFB-RS is powered from the panel connector; leave its drive connection cable disconnected until setup is complete.","RS-232 uses a straight-through cable, not a null-modem crossover."]

[[connection.methods]]
id = "cfb_rs485"
title = "CFB-RS adapter in RS-485 mode"
transport = "serial"
hardware = "option"
port = "CFB-RS terminals X1 or X2"
connector = "X1/X2 (parallel): 1 NC, 2 C Common, 3 A negative, 4 B positive, 5 Shield"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Belden 9841 or equivalent 120-ohm single shielded twisted pair"
parts = ["ABB CFB-RS adapter","Isolated USB-to-RS-485 adapter","Belden 9841 or equivalent"]
steps = ["Lock out the ACS160, set S3 to RS485, S2 to the selected baud and S1 for the bus termination position.","Mount CFB-RS on the drive with its two screws but leave the drive connection cable disconnected.","Wire X1/X2 and use the control panel to configure group 52.","Remove power, disconnect the panel, connect the CFB-RS drive cable, then restore power with the motor inhibited and verify a read."]
setup = ["Set 5201 station, 5202 speed and 5203 parity; changes take effect after power-up.","Set command/reference/reset source parameters for serial control and configure 5204/5205."]
warnings = ["The adapter cover and mounting screws provide its housing earth.","Enable S1 termination only at a physical bus end."]
source = "ABB CFB-RS 3BFE64390431 R0125, pp. 2-2 through 3-5."

[[connection.methods.wiring]]
adapter = "COM / signal common"
device = "X1/X2:2 C"
signal = "Common"

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

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

[[connection.methods.wiring]]
adapter = "Cable shield"
device = "X1/X2:5 Shield"
signal = "Shield"
required = false

[[connection.methods]]
id = "cfb_rs232"
title = "CFB-RS adapter in RS-232 mode"
transport = "serial"
hardware = "option"
port = "CFB-RS DB9 connector X4"
connector = "DB9 X4: 2 TxD, 3 RxD, 5 SGND; 1/9 NC; handshake pairs internally connected"
adapter = "PC RS-232 port or isolated USB-to-RS-232 adapter"
cable = "Straight-through DB9 serial cable, maximum 3 m"
parts = ["ABB CFB-RS adapter","RS-232 port/adapter","Straight-through DB9 cable"]
steps = ["Lock out the drive, set S3 to RS232 and mount the CFB-RS.","Use the control panel to configure communication if required, then remove power.","Disconnect the panel, connect the CFB-RS drive cable and plug the straight-through RS-232 cable into X4.","Restore power with the motor inhibited and verify a read."]
setup = ["Match 5201/5202/5203 and configure serial command/reference sources.","Configure 5204/5205 communication-loss handling."]
warnings = ["Do not cross TxD and RxD.","Maximum RS-232 cable length is 3 m and the adapter cover cannot be closed while X4 is used."]
source = "ABB CFB-RS 3BFE64390431 R0125, pp. 2-8 through 3-5."

[[connection.methods.wiring]]
adapter = "DB9 pin 2 TxD"
device = "X4 pin 2 TxD"
signal = "Transmit data, straight through"

[[connection.methods.wiring]]
adapter = "DB9 pin 3 RxD"
device = "X4 pin 3 RxD"
signal = "Receive data, straight through"

[[connection.methods.wiring]]
adapter = "DB9 pin 5 signal ground"
device = "X4 pin 5 SGND"
signal = "Signal ground"