# Property of PMA Electrical Solutions, LLC.
#
# Allen-Bradley PowerFlex 4 (bulletin 22A) ONLY.
# NOT claimed: PowerFlex 4M (22F), PowerFlex 40 (22B), 40P (22D), 400 (22C) or
# 525. Each has its own manual and its own map. A PowerFlex 4-family template
# ported into powerflex_525.toml carried the wrong parameter numbering and the
# wrong status bits; nothing here is carried in either direction. Every value
# below was read out of the PowerFlex 4's own manual.
#
# Communication path: the drive's embedded RS-485 (DSI) RJ45 port, Modbus RTU,
# multi-drop. No option module — this manual documents no network adapter for
# this drive. Only RJ45 pins 4 (TxRxD+) and 5 (TxRxD-) may be wired; the other
# pins carry power for Rockwell peripherals (p.100). Supported function codes:
# 03 read holding, 06 write single, 16 write multiple (p.101).
#
# Source: Rockwell publication 22A-UM001L-EN-E, September 2024, 114 pages.
#   pp.99-104  Appendix C "RS-485 (DSI) Protocol": function codes, Logic
#              Command 8192, Reference 8193, Logic Status 8448, Drive Error
#              Codes 8449, Feedback 8451, and the address = parameter rule
#   p.40       Parameter Organization table (the group bounds for [parameters])
#   pp.41-45   Display Group d001-d024, each parameter's "Display:" scale
#   p.46       P031-P035 including P033 [Motor OL Current] and P035 max 240 Hz
#   p.47       P036 [Start Source] option 5, and the firmware 1.02/1.03 note
#   pp.62-63   A103-A107 comm setup defaults, F81 comm-loss behaviour
#   p.66       A118 [Comm Write Mode] — NVS wear warning, matters for restore
#   pp.71-72   Chapter 4 fault table (code -> name)
#
# Drive-side setup, without which the drive ACKs writes and ignores them
# (p.101):
#   P036 [Start Source]     = 5 "Comm Port" / "RS485 (DSI) Port" -> 8192 obeyed
#   P038 [Speed Reference]  = 5 "RS485 (DSI) Port"               -> 8193 obeyed
#   A103 [Comm Data Rate]   3 = 9600 (default)
#   A104 [Comm Node Addr]   default 100, range 1-247
#   A107 [Comm Format]      0 = "RTU 8-N-1" (default)
#   A105 [Comm Loss Action] default 0 "Fault"; A106 [Comm Loss Time] default 5.0 s
# A103, A104 and A107 require a POWER CYCLE before they take effect (p.62-63).
#
# ADDRESSING. The manual prints "Address (Decimal)" values and states (p.101)
# that a 1-based master may need them offset by +1 — i.e. the printed numbers
# ARE the 0-based protocol addresses, which is what goes on the wire here.
# Formula: 0-based address = the decimal number exactly as printed. No 4xxxx /
# 40001 PLC notation anywhere, and no FC04 (3xxxx) space on this drive.
#   worked example 1: Logic Command, printed 8192 -> address 8192
#   worked example 2: "the Modbus register address equals the parameter number"
#     (p.104) -> d003 [Output Current] = 3, P033 [Motor OL Current] = 33,
#     P039 [Accel Time 1] = 39 (the manual's own worked example)
#
# SCALING is the fixed decimal point printed in each parameter's "Display:" row
# (pp.41-46). PowerFlex 4 has no group-46-style configurable fieldbus scale and
# no IEEE-754 point — everything here is a 16-bit fixed-point integer.
#
# CONFIGURATION-DEPENDENT: d003 and P033 run full scale to (Drive Rated Amps x
# 2) and d005's range is "Based on Drive Rating", so the same raw count means
# different amps/volts on different frames. The 0.01 A / 0.1 A / 1 V
# resolutions themselves are fixed.
#
# REVERSE is a discrete 2-bit field in the Logic Command (bits 5,4 = 10), NOT
# the sign of the reference. run_rev is therefore populated and speed_signed is
# false — do not copy the ABB sign-of-reference pattern onto this drive.
# A095 [Reverse Disable] = 1 makes the drive ignore every reverse command,
# including the serial one (p.61).
#
# RESET is bit 3 of the Logic Command itself, not a separate register, so it is
# a sequence on command_register. A100 [Fault Clear] (parameter address 100)
# is the alternative parameter-path reset but is marked "stop drive before
# changing"; bit 3 is the documented network path and is used here.
#
# FIRMWARE (p.47): on revision 1.02 and earlier a continuous serial start
# command needs a maintained stop input, and a serial Jog follows the direction
# on I/O terminal 03. On 1.03 and later the start bit must transition high-low-
# high after a stop before the drive restarts. Behavioural, not a register.
#
# NOT PRESENT ON THIS DRIVE: there is no output-power and no motor-torque
# point. The whole Display Group (d001-d024, pp.41-45) was read and contains
# neither. PowerFlex 40 exposes d022 [Output Power]; PowerFlex 4 does not.
# Nothing was substituted for them.

name = "Allen-Bradley PowerFlex 4"
vendor = "Allen-Bradley"
device_type = "vfd"
verified = false
probe_register = 8448  # Logic Status, readable whenever the DSI port is alive

[serial]
baudrate = 9600
parity = "N"
stopbits = 1

[monitor]
# Appendix C fixed registers (pp.102-103)
logic_command = { address = 8192, bits = { 0 = "STOP", 1 = "START", 2 = "JOG", 3 = "CLEAR_FAULTS", 4 = "FORWARD", 5 = "REVERSE" } }
speed_reference = { address = 8193, scale = 0.1, unit = "Hz" }  # "543" = 54.3 Hz
logic_status = { address = 8448, bits = { 0 = "READY", 1 = "ACTIVE", 2 = "CMD_FORWARD", 3 = "ROTATING_FORWARD", 4 = "ACCELERATING", 5 = "DECELERATING", 6 = "ALARM", 7 = "FAULTED", 8 = "AT_REFERENCE", 9 = "REF_BY_COMM", 10 = "CMD_BY_COMM", 11 = "PARAMS_LOCKED", 12 = "DIGITAL_IN_1", 13 = "DIGITAL_IN_2" } }
feedback = { address = 8451, scale = 0.1, unit = "Hz" }  # same data as d001

# Display group, register = parameter number (pp.41-45)
output_frequency = { address = 1, scale = 0.1, unit = "Hz" }     # d001
commanded_frequency = { address = 2, scale = 0.1, unit = "Hz" }  # d002
output_current = { address = 3, scale = 0.01, unit = "A" }       # d003
output_voltage = { address = 4, unit = "V" }                     # d004, 1 VAC
dc_bus_voltage = { address = 5, unit = "V" }                     # d005, 1 VDC
drive_status = { address = 6, bits = { 0 = "RUNNING", 1 = "FORWARD", 2 = "ACCELERATING", 3 = "DECELERATING" } }  # d006
control_sw_ver = { address = 16, scale = 0.01 }  # d016, p.44 — firmware 1.02 vs 1.03 changes the serial stop behaviour (p.47)
comm_status = { address = 15, bits = { 0 = "RECEIVING", 1 = "TRANSMITTING", 2 = "DSI_OPTION_CONNECTED", 3 = "COMM_ERROR" } }  # d015
elapsed_run_time = { address = 18, scale = 10.0, unit = "h" }    # d018, 1 = 10 Hrs
drive_temp = { address = 24, unit = "C" }                        # d024, 1 degC

# Logic Command word, p.102. Bit 0 Stop, bit 1 Start, bits 5,4 direction,
# bit 3 Clear Faults. Bits 14-12 are left 000 "No Command" so the frequency
# source stays as configured by P038 rather than being overridden per write.
[control]
command_register = 8192
speed_register = 8193
speed_scale = 0.1
speed_signed = false     # direction is bits 5,4, not the reference sign
speed_unit = "Hz"        # fixed decimal point, decimal 543 = 54.3 Hz (p.103)
max_ref = 240.0          # P035 [Maximum Freq] max is 240 Hz on this drive, p.46
step_delay = 0.05
stop = [0x0001]          # bit 0 Stop
run_fwd = [0x0012]       # bit 1 Start + bits 5,4 = 01 Forward
run_rev = [0x0022]       # bit 1 Start + bits 5,4 = 10 Reverse
# reset_register is deliberately absent: Clear Faults is bit 3 of the SAME
# register 8192, and validate() rejects reset_register == command_register.
# Bit 3 alone leaves bit 1 (Start) at 0, so this is not a run command.
reset = [0x0008, 0x0000]

# A105 [Comm Loss Action] defaults to Fault: the drive trips F81 and coasts
# after A106 [Comm Loss Time] (default 5.0 s, range 0.1-60.0 s, parameter
# address 106). Keep the keepalive well under whatever A106 is set to on the
# actual unit.
[control.watchdog]
interval_ms = 2000
fault = "F81 Comm Loss"

[running_check]
register = 8448
bit = 1          # Logic Status bit 1 = Active (Running)

# 8449 Drive Error Codes (p.104); history is d007/d008/d009 (addresses 7/8/9),
# d007 most recent, repeated faults recorded once (p.42). A100 [Fault Clear] =
# 2 "Clear Buffer" clears d007-d009.
[faults]
register = 8449
history = [7, 8, 9]

# The codes printed in the 8449 table (p.104), plus F48 and F71 which appear in
# the Chapter 4 fault table (p.72) that d007-d009 point at. Values absent from
# both tables (1, 9-11, 14-28, 30-32, 34-37, 44-47, ...) are not documented by
# Rockwell for this drive and are NOT invented here.
[faults.codes]
0 = "No Fault"
2 = "Auxiliary Input"
3 = "Power Loss"
4 = "Undervoltage"
5 = "Overvoltage"
6 = "Motor Stalled"
7 = "Motor Overload"
8 = "Heatsink Overtemperature"
12 = "HW Overcurrent (300%)"
13 = "Ground Fault"
29 = "Analog Input Loss"
33 = "Auto Restart Tries"
38 = "Phase U to Ground Short"
39 = "Phase V to Ground Short"
40 = "Phase W to Ground Short"
41 = "Phase UV Short"
42 = "Phase UW Short"
43 = "Phase VW Short"
48 = "Params Defaulted"
63 = "Software Overcurrent"
64 = "Drive Overload"
70 = "Power Unit Fail"
71 = "Net Loss"
80 = "AutoTune Fail"
81 = "Communication Loss"
100 = "Parameter Checksum Error"
122 = "I/O Board Fail"

# P033 [Motor OL Current], register 33. p.46: Display 0.1 Amps, min/max
# 0.0/(Drive Rated Amps x 2), default "Based on Drive Rating". This is the
# closest thing to a frame-size guard on this drive — there is no separate
# readable "Drive Rated Amps" register; that value only appears symbolically in
# min/max formulas (P033, A098).
[rating]
register = 33
words = 1
scale = 0.1
unit = "A"
label = "Motor OL Current (P033)"

# Writable configuration space, register = parameter number. Bounds are the
# Parameter Organization table on p.40, confirmed against the last parameter of
# each group in the body text: Basic Program P031-P043 (p.46-50), Advanced
# Program A051-A118 (p.51-66, A118 [Comm Write Mode] is the last).
# Display group d001-d024 is READ ONLY ("Default: Read Only" on every entry,
# pp.41-45) and is deliberately excluded.
# The ranges below enumerate the parameters the p.40 Parameter Organization
# table actually lists (P031-P041, P043; A051, A052, A055, A056, A067-A073,
# A078-A084, A088-A107, A110-A118) — numbers between them do not exist and a
# contiguous span would just fill the capture's `unreadable` list.
# DELIBERATE EXCLUSIONS:
#   P041 [Reset To Defalts] (register 41, p.50) — writing option 1
#     factory-defaults the drive, the opposite of restoring onto it (and
#     raises F48). Same exclusion as the PF4M's P112.
#   A101 [Program Lock] (register 101, p.62) — restoring a locked state would
#     lock out the very writes still to come in the same restore. Same
#     exclusion as the PF4M's A458.
#   A103 [Comm Data Rate], A104 [Comm Node Addr], A107 [Comm Format]
#     (pp.62-63) — the drive's serial identity; cloning them re-addresses the
#     target on the next power cycle and can create a duplicate node on a
#     multi-drop bus. A105/A106 (comm-loss action/time) are behaviour, not
#     identity, and stay cloneable.
#
# RESTORE CAUTION (A118, p.66): with A118 = 0 "Save" (default) every write
# lands in non-volatile storage. That is what a restore wants, but Rockwell
# warns that frequent NVS writes exceed its life cycle — do not poll-write
# these registers.
[parameters]
ranges = [[31, 40], [43, 43], [51, 52], [55, 56], [67, 73], [78, 84], [88, 100], [102, 102], [105, 106], [110, 118]]

[connection]
summary = "Connect directly to the PowerFlex 4 built-in RS-485 DSI port using Modbus RTU; no network option module is required."
warnings = ["Lock out and verify the drive is de-energized before opening its cover.", "Wire only RJ45 pins 4 and 5; Rockwell states the other pins carry power for peripherals.", "Keep the RS-485 cable at least 0.3 m (1 ft) from power conductors and cross at right angles.", "Rockwell notes that other manufacturers may interpret + and - differently; if a correctly configured two-wire link is silent, swap the pair at the master only."]

[[connection.methods]]
id = "built_in_dsi_rs485"
title = "Built-in RS-485 DSI"
transport = "serial"
hardware = "built_in"
port = "Drive RS-485 (DSI) RJ45"
connector = "RJ45; pin 4 TxRxD+, pin 5 TxRxD-; all other RJ45 pins must remain disconnected"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded two-conductor RS-485 cable, optionally through Rockwell AK-U0-RJ45-TB2P breakout"
parts = ["Isolated USB-to-RS-485 adapter", "Shielded two-conductor cable", "RJ45 plug wired only on pins 4/5 or AK-U0-RJ45-TB2P", "120 ohm terminators at the two bus ends"]
steps = ["Lock out all power and verify the DC bus is discharged.", "Locate the RS-485 (DSI) RJ45 port.", "Wire TxRxD+ to pin 4 and TxRxD- to pin 5; leave every other RJ45 pin open.", "Connect the cable shield as specified below, at one end of each segment only, and install 120 ohm termination at both physical ends.", "Restore control power with the motor inhibited and verify a holding-register read before enabling control."]
setup = ["P036 [Start Source] = 5 RS485 (DSI) Port.", "P038 [Speed Reference] = 5 RS485 (DSI) Port.", "Set A103 data rate, A104 unique node, A105 loss action, A106 loss time and A107 frame format."]
warnings = ["Never connect Power over Ethernet to this port.", "Do not use an ordinary fully wired Ethernet patch lead between the drive and a serial adapter."]
source = "Rockwell 22A-UM001L-EN-E (Sept 2024), pp. 99-101."

[[connection.methods.wiring]]
adapter = "TxRxD+"
device = "RJ45 pin 4 — TxRxD+"
signal = "RS-485 positive conductor"

[[connection.methods.wiring]]
adapter = "TxRxD-"
device = "RJ45 pin 5 — TxRxD-"
signal = "RS-485 negative conductor"

[[connection.methods.wiring]]
adapter = "Cable shield / PE"
device = "I/O terminal 16 (RS-485 Shield) to PE"
signal = "Shield bond"
required = false