# Property of PMA Electrical Solutions, LLC.
#
# Allen-Bradley SMC Flex SOFT STARTER (Bulletin 150). NOT a VFD, and NOT the
# SMC-50, SMC-3 or SMC-2 — the SMC-50 is a different controller with a
# different parameter set and its own profile (rockwell_smc50.toml). Nothing
# here was carried across from it.
#
# MODBUS PATH ASSUMED BY THIS PROFILE
# The SMC Flex has NO embedded Modbus. It speaks DPI and needs a 20-COMM-x
# module. This profile assumes the **20-COMM-H RS-485 adapter with its protocol
# selector set to Modbus RTU**, in its default **16-bit parameter mode**
# (adapter par 32 [RTU Param Mode] = 0). 150-UM008J p. 91 names 20-COMM-H among
# the supported modules. Nothing here applies to a 20-COMM-M (Modbus/TCP).
#
# SOURCES — Rockwell primary documentation only:
#   150-UM008J-EN-P, SMC Flex Soft Starters User Manual (April 2025)
#     pp. 93-98    Logic Mask, control enable, I/O configuration, DataLinks,
#                  scale-factor rule, Reference/Feedback
#     p. 96        Table 39 Logic Status Word, Table 40 Logic Command Word
#     p. 100       Table 42, the fault code cross-reference below
#     pp. 100-101  Table 43, fault definitions
#   150-RD001A-EN-E, SMC Flex Soft Starter Parameters (April 2025, xlsx)
#     "Parameters" sheet — every parameter number, unit and range used here
#   20COMM-UM009D-EN-P, 20-COMM-H RS-485 HVAC Adapter User Manual
#     p. 4-2       the addressing rule
#     p. 4-4       Table 4.C, register map and parameter direct access
#     pp. B-1…B-6  adapter parameter defaults, Network Timeout, Comm Flt Action
#
# ADDRESSING — 0-BASED PROTOCOL ADDRESSES, FC03/06/16 HOLDING REGISTERS.
# 20COMM-UM009D p. 4-2 states it outright: "you must address it to one less
# than the Modbus address in the manual", worked as Logic Command 4x0001 ->
# data address 0000. Drive parameter direct access is "4x1000 + param #"
# (Table 4.C) in 16-bit mode, so:
#     0-based address = 999 + parameter number
#   par 4  [Current Phase A] -> 999 + 4   = 1003
#   par 124 [Fault 1]        -> 999 + 124 = 1123
# CAUTION: p. 4-9 of the same manual writes the formula as "41000 + (Drive
# Parameter #)" and then says parameter 1 is at 41000, one less than its own
# formula. Table 4.C and the formula agree on 999 + param#, so the worked
# example is treated as the error — the same contradiction is flagged in
# rockwell_smc50.toml. CONFIRM ON HARDWARE by reading par 14 [SMC Option] at
# 1013 and checking it returns 0, 1 or 2 before trusting any other address.
# 32-bit parameters are not reachable in 16-bit mode; adapter par 32 = 1 shifts
# the formula to 999 + 2*param# for everything, which this profile does NOT model.
#
# ROCKWELL CONTRADICTS ITSELF ON CURRENT PHASE A, RESOLVED AGAINST THE
# SPREADSHEET. 150-UM008J p. 95 footnote calls it "Parameter 4"; p. 97 calls it
# "Parameter 1, Current in Phase A". 150-RD001A settles it: parameter 1 is
# [Volts Phase A-B] and parameter 4 is [Current Phase A]. p. 97 is wrong.
#
# SCALING — 150-UM008J p. 97: values on the wire are unscaled integers and the
# divisor is that parameter's own decimal-place count from 150-RD001A. par 11
# [Power Factor] stores 85 for 0.85; par 46 [Motor FLC] stores 750 for 75.0 A.
# It is not a fixed fieldbus scale and it is not the HIM display format.
#
# NO SPEED REFERENCE. 150-UM008J p. 97: "The SMC Flex controller does not offer
# the analog Reference feature." The adapter reserves 4x0002/4x0003 for a
# reference the starter ignores. So [control] has no speed_register, and there
# is no run_rev — a soft starter does not reverse.
#
# ############ READ THIS BEFORE ARMING ############
# THIS PROFILE HAS NO [running_check], AND THAT IS NOT AN OVERSIGHT.
# The SMC Flex publishes its Logic Status word ONLY through the DPI I/O image.
# On the 20-COMM-H that lands at 3x0001 — an INPUT register, function code 04.
# vfd-core reads holding registers (FC03) only; Point carries no function-code
# field, so FC04 is unreachable. Unlike the SMC-50, which mirrors its status
# into par 43 [Product Status], the SMC Flex has no equivalent: 150-RD001A
# lists parameters 1-134 and not one of them is a logic status word, and the
# 20-COMM-H's own 32 adapter parameters do not mirror it either (its LOGIC STS
# LO/HI at points 95/96 are Metasys N2 points, not Modbus registers).
#
# CONSEQUENCE: ops::running_state returns RunState::Unknown permanently, so
# every control command comes back "could not read the drive's run state, so
# this command is unverified" (control.rs). registry.rs already warns that a
# permanent Unknown trains the operator to tick "force" on every restore.
# Treat this profile as MONITOR-AND-CONFIGURE. Do not arm it for routine motor
# control until either FC04 support exists in core or the status word is
# confirmed reachable some other way on real hardware.
# #################################################

name = "Allen-Bradley SMC Flex (soft starter)"
vendor = "Allen-Bradley"
device_type = "soft_starter"
verified = false
probe_register = 1013  # par 14 [SMC Option], read-only identity, no mains needed

# 20-COMM-H defaults, 20COMM-UM009D Appendix B: par 05 [Net Rate Cfg] = 1
# (9600), par 07 [Net Parity Cfg] = 0 (None), par 30 [Stop Bits Cfg] = 0
# (1 bit). 4800/9600/19200/38400 and N/O/E are all selectable, so confirm
# against the module actually installed.
[serial]
baudrate = 9600
parity = "N"
stopbits = 1

[monitor]
# Metering group, 150-RD001A. Volts are phase-to-phase and are measured "at all
# times, including during bypass operation". No decimals on any of them.
voltage_ab = { address = 1000, unit = "V" }   # par 1
voltage_bc = { address = 1001, unit = "V" }   # par 2
voltage_ca = { address = 1002, unit = "V" }   # par 3
# par 4-6. Always LINE current regardless of Wye or Delta motor connection.
# par 4 is also the DPI feedback word. No decimals.
motor_current = { address = 1003, unit = "A" }
current_b = { address = 1004, unit = "A" }
current_c = { address = 1005, unit = "A" }
# par 7. UNIT DEPENDS ON FRAME SIZE — kW on 5…135 A units, MW on 201…1250 A
# units, and 150-RD001A says that cannot be changed. Firmware 6.001 moved the
# large frames from kW to MW, so the same register means different things on
# two units in the same panel. Confirm the frame before trusting the number.
power = { address = 1006, unit = "kW/MW" }
energy = { address = 1007, unit = "kWh/MWh" }  # par 8, same frame caveat
elapsed_time = { address = 1008, unit = "h" }  # par 9
# par 11, range 0.00…0.99 -> two decimals. Displacement power factor.
power_factor = { address = 1010, scale = 0.01 }
# par 12, 0…100 %MTU. The starter faults on overload at 100%.
motor_thermal = { address = 1011, unit = "%" }
# par 13. Only meaningful when linear ramp is selected AND an external
# tachometer is fitted; otherwise it does not track real speed.
motor_speed = { address = 1012, unit = "%" }
# par 14, control module identity: 0 = Standard, 1 = Brake, 2 = Pump Control.
smc_option = { address = 1013 }
# par 16, the configured base voltage for the under/over-voltage protection —
# a SETTING, not a measurement.
line_voltage_setting = { address = 1015, unit = "V" }
# par 46 [Motor FLC], one decimal place per 150-RD001A (1.0…2200.0 A).
motor_flc = { address = 1045, scale = 0.1, unit = "A" }
# par 87 [Logic Mask]. Read this to confirm the comm port is actually enabled
# for control — see the drive-side setup note below.
logic_mask = { address = 1086 }
#
# NO status_word POINT. The Logic Status word is FC04-only on this controller;
# see the block comment in the header. 150-UM008J p. 96 Table 39 documents its
# bits (0 Enabled, 1 Running, 2 Phasing ABC, 3 Phasing Active, 4 Starting,
# 5 Stopping, 6 Alarm, 7 Fault, 8 At Speed, 9 Start/Isolation, 10 Bypass,
# 11 Ready, 12 Option 1 Input, 13 Option 2 Input, 14-15 unused) and they are
# recorded here so they are ready the day FC04 becomes reachable.

# DPI Logic Command word: adapter holding register 4x0001 -> 0-based 0
# (20COMM-UM009D p. 4-4 Table 4.C). Bit meanings are the SMC Flex's own,
# 150-UM008J p. 96 Table 40 — NOT the PowerFlex 70/700 bits used as examples
# throughout the adapter manual:
#   0 Stop/Inhibit   1 Start   2 Option #1 Input (stop maneuver/inhibit)
#   3 Clear Faults   4 Option #2 Input
#
# DRIVE-SIDE SETUP — without this the starter ACKs control writes and ignores
# them. par 87 [Logic Mask] must have the bit for the comm module's DPI port
# set to 1; the factory default is 0, meaning out of the box the SMC Flex
# accepts NO start command from any DPI port (150-UM008J p. 93). Stop and coast
# are honoured from the hardwired inputs and from any port regardless of the
# mask. Note the manual's warning: with the Logic Mask enabled, disconnecting a
# HIM causes a Comms Loss fault, so set the mask back to 0 before unplugging.
[control]
command_register = 0
step_delay = 0.05
# Bit 0 = Stop/Inhibit. Unconditional, and it holds the starter inhibited until
# cleared. Bit 2 would instead run the configured Option #1 stop maneuver,
# which only does something if par 132 [Option Input 1] is set for it.
stop = [0x0001]
# 0x0000 first releases a latched Stop/Inhibit — Start is ignored while bit 0
# is held — then bit 1 issues the start. 0x0000 is the neutral word, so the
# keepalive that follows re-asserts nothing.
run_fwd = [0x0000, 0x0002]
# Bit 3 [Clear Faults], pulsed. 0x0008 has bit 1 (Start) clear, so this reset
# value is NOT a run command — the Delta MS300 trap does not apply here.
reset = [0x0000, 0x0008, 0x0000]

# 20COMM-UM009D Appendix B: adapter par 11 [Network Timeout] is 10 s by default
# and par 15 [Comm Flt Action] is 0 = Fault, so a master that goes quiet trips
# the starter rather than leaving the motor running. On DPI port 5 (adapter par
# 01 [DPI Port], default 5) that surfaces as fault 29 [Coms Loss P5] or 32
# [Network P5]. 1 s keepalive sits an order of magnitude inside the timeout.
# Note par 18 [Flt Cfg Logic] defines the logic command the adapter sends the
# starter on a fault — factory 0x0000, i.e. neutral; if someone has set a run
# bit in it, comm loss becomes a START. Check it before arming.
[control.watchdog]
interval_ms = 1000
fault = "29 Coms Loss P5 / 32 Network P5"

# NO [running_check] — see the header. RunState is permanently Unknown.

# par 124 [Fault 1] is the current fault; par 125-128 are the four older ones,
# oldest last (150-UM008J p. 100). Range 0…255 each.
[faults]
register = 1123
history = [1124, 1125, 1126, 1127]

# Table 42, 150-UM008J p. 100, transcribed complete. Codes 44 and 47 are not
# printed in that table and are deliberately absent rather than guessed.
# Codes 128…209 are "System Faults" as a block, with no per-code breakdown
# published, so they are not enumerated here.
# Codes 41, 42 and 43 are a second set of Line Loss faults distinguished from
# 1/2/3 by Table 43; the manual does not say what distinguishes them beyond
# referring back to that table.
[faults.codes]
1 = "Line Loss A"
2 = "Line Loss B"
3 = "Line Loss C"
4 = "Shorted SCR A"
5 = "Shorted SCR B"
6 = "Shorted SCR C"
7 = "Open Gate A"
8 = "Open Gate B"
9 = "Open Gate C"
10 = "PTC Pwr Pole"
11 = "SCR Overtemp"
12 = "Motor PTC"
13 = "Open Bypass A"
14 = "Open Bypass B"
15 = "Open Bypass C"
16 = "No Load A"
17 = "No Load B"
18 = "No Load C"
19 = "Line Unbalance"
20 = "Overvoltage"
21 = "Undervoltage"
22 = "Overload"
23 = "Underload"
24 = "Jam"
25 = "Stall"
26 = "Phase Reversal"
27 = "Coms Loss P2"
28 = "Coms Loss P3"
29 = "Coms Loss P5"
30 = "Network P2"
31 = "Network P3"
32 = "Network P5"
33 = "Ground Fault"
34 = "Excess Starts"
35 = "Power Loss A"
36 = "Power Loss B"
37 = "Power Loss C"
38 = "Hall ID"
39 = "NVS Error"
40 = "No Load"
41 = "Line Loss A (see Table 43)"
42 = "Line Loss B (see Table 43)"
43 = "Line Loss C (see Table 43)"
45 = "V24 Loss"
46 = "V Control Loss"
48 = "Input 1"
49 = "Input 2"

# NO [parameters] BLOCK, DELIBERATELY.
# A clone would have to write the settings group, and the SMC Flex interleaves
# read-only metering (par 1-13), a read-only module identity (par 14), a
# read-only fault buffer (par 124-128) and reserved holes (par 21, 29) with the
# writable settings. 150-RD001A carries the per-parameter R/W behaviour needed
# to draw safe ranges, but it was not walked end to end for this profile, so no
# range is known-safe. Writing a read-only parameter NAKs; writing a reserved
# one is undefined. Establish the ranges from the spreadsheet's Behavior Code
# column before adding this block.
#
# NO [rating] BLOCK: par 46 [Motor FLC] is the installer-entered motor rating,
# not the controller's own frame size, so it is not a safe pre-restore
# comparison. The frame rating appears only in the catalog number.

[connection]
summary = "The SMC Flex has no compatible embedded Modbus port for this profile; install a Rockwell 20-COMM-H RS-485 adapter and connect it through DPI."
warnings = ["Lock out the drive/starter, verify stored energy is discharged, and use ESD precautions before installing the adapter.", "The 20-COMM-H must be set to Modbus RTU, not N2 or P1.", "The optional 20-COMM-M Modbus TCP module is not this profile and is not interchangeable.", "Confirm parameter width/memory-map mode exactly as the profile requires before trusting an address."]

[[connection.methods]]
id = "20_comm_h_rs485"
title = "20-COMM-H Modbus RTU option"
transport = "serial"
hardware = "option"
port = "DPI communications port supported by the starter"
connector = "20-COMM-H six-pin network plug: TERM, A, B, COM, SHIELD, GND"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Belden 3106A three-wire RS-485 cable or equivalent; Belden 3105A two-wire is allowed where COM is intentionally omitted"
parts = ["Rockwell 20-COMM-H RS-485 HVAC adapter", "Drive-specific DPI internal interface cable/carrier", "Isolated USB-to-RS-485 adapter", "Belden 3106A or equivalent", "Six-pin linear plug supplied for the adapter"]
steps = ["Remove drive/starter and network power and verify discharge.", "Set the 20-COMM-H node-address switches and the protocol selector to RTU before installation.", "Mount and ground the adapter, then connect its internal interface cable to the documented DPI port.", "Land A, B, COM and shield on the six-pin network plug exactly as shown below.", "At a bus end jumper TERM to A; at one network point only jumper SHIELD to GND.", "Restore control power with the motor inhibited, verify adapter status, and prove a read before enabling control."]
setup = ["Install the 20-COMM-H in the documented DPI communications location, select RTU and set a unique node.", "Keep adapter par 32 = 0 and par 16 bit 0 = 1.", "Enable the corresponding Logic Mask/control ownership on the SMC Flex.", "Configure timeout/fault action", " treat this profile as monitor/configure until FC04 status support exists."]
warnings = ["Do not install/remove the adapter with the drive energized.", "A = TxRxD- and B = TxRxD+ on this adapter; preserve those literal labels.", "Ground the shield at one point on the entire network."]
source = "Rockwell 150-UM008J-EN-P pp. 91-98; 20COMM-UM009D-EN-P pp. 2-1 to 2-7 and Appendix B."

[[connection.methods.wiring]]
adapter = "TxRxD- / A / -"
device = "20-COMM-H A — TxRxD-"
signal = "RS-485 A"

[[connection.methods.wiring]]
adapter = "TxRxD+ / B / +"
device = "20-COMM-H B — TxRxD+"
signal = "RS-485 B"

[[connection.methods.wiring]]
adapter = "COM / signal common"
device = "20-COMM-H COM — Signal Common"
signal = "Signal reference"

[[connection.methods.wiring]]
adapter = "Cable shield"
device = "20-COMM-H SHIELD"
signal = "Shield RC termination"
required = false

[[connection.methods.wiring]]
adapter = "Protective earth at one network point"
device = "20-COMM-H GND (jumper to SHIELD at one point only)"
signal = "Shield earth bond"
required = false