# Property of PMA Electrical Solutions, LLC.
#
# Allen-Bradley PowerFlex 4M (22F) ONLY.
#
# NOT CLAIMED: PowerFlex 4, 40, 40P, 400, 4M-with-DeviceNet, 523, 525. The 4M
# shares Rockwell's DSI Logic Command layout with other PowerFlex 4-class
# drives, but this file was built from the 4M manual alone and the parameter
# numbering (the second address space below) is per-model. In particular the
# C30x numbers here are the 4M's Communications group (C301-C307) and have
# nothing to do with the 525's C30x scheme — see the note in
# profiles/powerflex_525.toml.
#
# COMMUNICATION PATH: the drive's own embedded RS-485 (DSI) port on the
# control terminal block (terminals 4/5, shield on 16), native Modbus RTU.
# No option module, no adapter card, no firmware level stated by the manual.
# Function codes supported: 03 read holding, 06 write single, 16 write
# multiple (22F-UM001E p.101). This is the drive's only Modbus path.
#
# SOURCE: Rockwell Automation publication 22F-UM001E-EN-E, Rev E,
# September 2024, "PowerFlex 4M Adjustable Frequency AC Drive User Manual".
# Cached as manuals/rockwell_powerflex4m_22F-UM001.pdf (114 pages; PDF page
# index equals printed page number, no front-matter offset).
#   p.99-101   RS-485 (DSI) path, network config parameters, function codes,
#              the 0-based/1-based note
#   p.102      Logic Command register 8192, full bit table
#   p.103      Reference 8193, Logic Status 8448, Feedback 8451
#   p.104      Drive Error Codes 8449 value table; "register address equals
#              the parameter number" rule
#   p.40       Parameter Organization (which parameters exist, by group)
#   p.41-45    Display group d001-d022 (all monitor scaling below)
#   p.46-49    P103/P105/P106/P108
#   p.55-56    C302-C307 serial defaults and comm-loss behaviour
#   p.68       A461 Motor NP FLA
#   p.73-74    Table 11 fault descriptions
#
# DRIVE-SIDE SETUP (without these the drive ACKs the writes and ignores them):
#   P106 [Start Source]    = 5 "Comm Port"   (p.47; p.101 calls the same
#                            option "RS485 (DSI) Port")
#   P108 [Speed Reference] = 5 "Comm Port"   (p.49)
#   C302 [Comm Data Rate], C303 [Comm Node Addr] (DEFAULT 100, range 1/247,
#        p.55 — a factory-fresh drive answers on unit 100, not 1),
#        C306 [Comm Format] —
#        POWER MUST BE CYCLED after changing any of these (p.55-56).
#   C304 [Comm Loss Action] default 0 "Fault" -> F81 Comm Loss, coast to stop.
#   C305 [Comm Loss Time]   default 5.0 s.
#   C307 [Comm Write Mode]  default 0 "Save" must be LEFT ALONE for a
#        clone/restore: RAM-only values are lost at power-down (p.56). The
#        p.56 EEPROM-wear ATTENTION does not apply to this tool's monitoring
#        or control paths — 8192/8193 are not parameter registers; only the
#        restore path writes parameters.
#   HAZARD (p.47 footnote to option 5): with the drive under network control,
#   if the master leaves Start or Jog asserted and never sends Stop, the drive
#   RESTARTS BY ITSELF on the next power-up.
#
# ADDRESSING FORMULA — two spaces coexist, both already 0-based protocol
# addresses as printed. No 4xxxx/PLC conversion is involved anywhere here.
#   1. Fixed control/status registers: the manual gives the decimal protocol
#      address directly. Worked example, p.102: "Function Code 06 writes to
#      register address 8192 (Logic Command)" -> 8192, used verbatim.
#   2. Drive parameters: address = the parameter's numeric part.
#      Worked example, p.104: "decimal '109' is used to address Parameter
#      P109 [Accel Time 1]" -> P109 = 109, d003 = 3, A461 = 461.
#   p.101 warns that some MASTERS number registers from 1 and therefore need
#   these values +1 (its example: PanelView asks for 8193 to reach Logic
#   Command). That is a master-side quirk, not a drive-side offset — this
#   stack speaks 0-based, so the numbers below are used as printed.
#
# SCALING is the panel display resolution from the Display group (p.41-45),
# which for this drive is also the fieldbus format: the Reference and Feedback
# registers are explicitly documented as fixed-point "xxx.x" (p.103, decimal
# 543 = 54.3 Hz), matching d001. Nothing here is scaled by a configuration
# parameter, unlike ABB FbEq16.
#
# CONFIGURATION-DEPENDENT: the usable reference ceiling is P105 [Maximum Freq]
# (default 60 Hz, range 0/400 Hz, p.46). max_ref below is the parameter's
# maximum, not the shipped default — the drive clamps to its own P105.
#
# NOT DOCUMENTED, DELIBERATELY ABSENT (do not fill from memory):
#   - No output power and no torque parameter exists anywhere in the Display
#     group (d001-d022, p.40 and p.41-45). This drive does not publish them.
#   - No read-only drive-frame / drive-rated-amps register is published.
#     [rating] below uses A461 and says what that costs.
#   - F48 "Params Defaulted" and F71 "Net Loss" are absent from the
#     register-8449 value table (p.104) but ARE decodable for the d007-d009
#     history registers: d007's value range is "F2/F122" (p.42) — the value IS
#     the F-number — and every Table 11 code that also appears in the p.104
#     table has value == F-number. They are in [faults.codes] on that basis;
#     only their appearance on LIVE register 8449 is unconfirmed.

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

# C302 default 3 = 9600; C306 default 0 = "RTU 8-N-1" (p.55-56).
[serial]
baudrate = 9600
parity = "N"
stopbits = 1

[monitor]
# p.103. Bit 1 is the running bit; bit 2 is the COMMANDED direction and bit 3
# the ACTUAL rotation, which is why both are named.
logic_status = { address = 8448, bits = { 0 = "READY", 1 = "ACTIVE_RUNNING", 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" } }
# 8451 Feedback returns the same data as d001 (p.103 footnote); both kept
# because 8451 costs nothing and survives a parameter renumber.
feedback_frequency = { address = 8451, scale = 0.1, unit = "Hz" }
output_frequency = { address = 1, scale = 0.1, unit = "Hz" }    # d001, p.41
commanded_frequency = { address = 2, scale = 0.1, unit = "Hz" } # d002, p.41
output_current = { address = 3, scale = 0.01, unit = "A" }      # d003, p.41
output_voltage = { address = 4, scale = 0.1, unit = "V" }       # d004, p.41
dc_bus_voltage = { address = 5, unit = "V" }                    # d005, p.41, 1 VDC/count
drive_status = { address = 6, bits = { 0 = "RUNNING", 1 = "FORWARD", 2 = "ACCELERATING", 3 = "DECELERATING" } }  # d006, p.42
comm_status = { address = 15, bits = { 0 = "RECEIVING", 1 = "TRANSMITTING", 2 = "DSI_OPTION_CONNECTED", 3 = "COMM_ERROR" } }  # d015, p.44
elapsed_run_time = { address = 18, scale = 10.0, unit = "h" }   # d018, p.44, counts in 10-hour increments
drive_temp = { address = 22, unit = "degC" }                    # d022, p.45

# Logic Command, register 8192 (p.102). Bit 0 = Stop, bit 1 = Start,
# bit 3 = Clear Faults, bits 5,4 = 00 none / 01 forward / 10 reverse.
[control]
command_register = 8192
speed_register = 8193
speed_scale = 0.1       # p.103: decimal 100 = 10.0 Hz, 543 = 54.3 Hz
speed_signed = false    # see the run_rev note below
speed_unit = "Hz"       # genuinely Hz here, not percent
max_ref = 400.0         # P105 [Maximum Freq] maximum, p.46; drive clamps to its own P105
step_delay = 0.05
stop = [0x0001]
# p.47: "the drive must receive a leading edge from the start input for the
# drive to start after a stop input, loss of power, or fault condition". The
# first word sets the direction field with Start still low so the second word
# is guaranteed to be that rising edge, whatever the previous control word was.
run_fwd = [0x0010, 0x0012]   # bits 5,4 = 01 forward; then + bit 1 Start
run_rev = [0x0020, 0x0022]   # bits 5,4 = 10 reverse; then + bit 1 Start
# run_rev IS declared, unlike the ABB profiles: direction on this drive is an
# explicit 2-bit field in the control word, not the sign of the reference, and
# register 8193 has no documented negative form. Hence speed_signed = false.
#
# Reset is bit 3 of the SAME register 8192, not a separate register, so
# reset_register is deliberately absent (Control::register_for falls back to
# command_register). Checked against the trap this repo hit on the Delta
# MS300: 0x0009 has bit 1 Start LOW, so the reset word is not a run command —
# it holds Stop asserted while it pulses Clear Faults, and returns to Stop.
reset = [0x0001, 0x0009, 0x0001]

# C304 defaults to Fault -> F81 Comm Loss + coast-to-stop after C305, default
# 5.0 s (p.55-56). Keepalive well inside that, and inside the 0.1 s minimum
# C305 a site may have configured.
[control.watchdog]
interval_ms = 500
fault = "F81 Comm Loss"

[running_check]
register = 8448
bit = 1  # 1 = Active (Running), p.103

# Live error code on 8449 (p.104); d007/d008/d009 are the stored history with
# d007 the most recent (p.42).
[faults]
register = 8449
history = [7, 8, 9]

# The register-8449 value table, p.104, verbatim, plus F48/F71 from Table 11
# (pp.73-74) via the d007 value range (p.42) — see the note above.
[faults.codes]
0 = "No Fault"
2 = "F2 Auxiliary Input"
3 = "F3 Power Loss"
4 = "F4 UnderVoltage"
5 = "F5 OverVoltage"
6 = "F6 Motor Stalled"
7 = "F7 Motor Overload"
8 = "F8 Heatsink OvrTmp"
12 = "F12 HW OverCurrent (300%)"
13 = "F13 Ground Fault"
29 = "F29 Analog Input Loss"
33 = "F33 Auto Rstrt Tries"
38 = "F38 Phase U to Ground Short"
39 = "F39 Phase V to Ground Short"
40 = "F40 Phase W to Ground Short"
41 = "F41 Phase UV Short"
42 = "F42 Phase UW Short"
43 = "F43 Phase VW Short"
48 = "F48 Params Defaulted"
63 = "F63 Software Overcurrent"
64 = "F64 Drive Overload"
70 = "F70 Power Unit Fail"
71 = "F71 Net Loss"
80 = "F80 AutoTune Fail"
81 = "F81 Communication Loss"
100 = "F100 Parameter Checksum Error"
122 = "F122 I/O Board Fail"

# WEAKER THAN A FRAME-SIZE REGISTER, ON PURPOSE. A461 [Motor NP FLA] (p.68)
# defaults to Drive Rated Amps and is bounded by it (0.1 / Drive Rated Amps
# x 2), but it is a WRITABLE motor nameplate value: the guard MATCHES — and
# waves the restore through — whenever two different-frame drives carry the
# same motor FLA, and it Mismatches a same-frame replacement still at its
# factory default. d017 [Drive Type] (p.44, read-only, 1001-9999) is the
# frame identity and the guard only needs equality, but its per-frame
# uniqueness is unprovable from this manual (the encoding is "used by
# Rockwell Automation field service personnel"), and every sibling profile
# (PF4/40/40P/400/525) makes the same motor-parameter compromise — change
# them together or not at all.
[rating]
register = 461
scale = 0.1
unit = "A"
label = "A461 Motor NP FLA"

# Reconstructed from the Parameter Organization table, p.40, which lists the
# parameters that EXIST rather than claiming a contiguous span — the Advanced
# group has real holes (no A406-A408, A414-A417, A420-A423, A426, A429-A432,
# A443, A445, A447, A449, A454-A456, A460). Only the enumerated numbers are
# spanned below. The Display group d001-d022 is read-only and excluded.
#
# TWO PARAMETERS ARE DELIBERATELY EXCLUDED from the clone/restore span:
#   P112 [Reset To Defalts] — writing option 1 factory-defaults the drive,
#        which is the opposite of restoring a configuration onto it.
#   A458 [Program Lock] — restoring a locked state would lock out the very
#        writes still to come in the same restore.
# p.40 also prints the 4-20 mA analog limits as "d213/d214"; they are t213/
# t214 (a typo — d021 on p.45 names t213/t214 as its related parameters), and
# 211-214 covers them either way.
[parameters]
ranges = [
  [101, 111],   # P101-P111  (P112 Reset To Defalts excluded, see above)
  [201, 202],   # t201-t202  Digital In1/In2 Sel
  [211, 214],   # t211-t214  analog input scaling
  [221, 222],   # t221-t222  relay out sel/level
  [301, 307],   # C301-C307  Communications group
  [401, 405],   # A401-A405
  [409, 413],   # A409-A413
  [418, 419],   # A418-A419
  [424, 425],   # A424-A425
  [427, 428],   # A427-A428
  [433, 442],   # A433-A442
  [444, 444],   # A444
  [446, 446],   # A446
  [448, 448],   # A448
  [450, 453],   # A450-A453
  [457, 457],   # A457       (A458 Program Lock excluded, see above)
  [459, 459],   # A459
  [461, 461],   # A461
]

[connection]
summary = "Connect directly to the PowerFlex 4M built-in RS-485 DSI terminals; no option module is required."
warnings = ["Lock out and verify the drive is de-energized before wiring.", "The exact drive terminals are 4 = TxRxD+, 5 = TxRxD-, and 16 = RS-485 shield.", "Keep the network at least 0.3 m from power wiring and terminate only the two ends."]

[[connection.methods]]
id = "built_in_dsi_terminal"
title = "Built-in DSI control terminals"
transport = "serial"
hardware = "built_in"
port = "I/O control terminal block"
connector = "Terminal 4 TxRxD+, terminal 5 TxRxD-, terminal 16 RS-485 Shield"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded two-conductor RS-485 cable"
parts = ["Isolated USB-to-RS-485 adapter", "Shielded two-conductor cable", "120 ohm terminators"]
steps = ["Lock out all power and verify the DC bus is discharged.", "Open the control cover and locate terminals 4, 5 and 16.", "Land TxRxD+, TxRxD- and the shield exactly as shown below.", "Connect terminal 16 to PE and bond the segment shield at one end only.", "Restore control power with the motor inhibited and verify a read."]
setup = ["P106 [Start Source] = 5 Comm Port.", "P108 [Speed Reference] = 5 Comm Port.", "Set C302 data rate, C303 unique node, C304 loss action, C305 loss time and C306 format."]
warnings = ["Do not carry the PowerFlex 4/40 RJ45 physical instructions onto this control-terminal connection.", "If the master uses opposite +/− naming, swap the pair only at the master after checking all settings."]
source = "Rockwell 22F-UM001E-EN-E (Sept 2024), pp. 99-101."

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

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

[[connection.methods.wiring]]
adapter = "Cable shield"
device = "Terminal 16 — RS-485 Shield, bonded to PE"
signal = "Shield"
required = false