# Property of PMA Electrical Solutions, LLC.
#
# Allen-Bradley OneGear MEDIUM VOLTAGE SMC-50 soft starter (10...15 kV).
# COVERAGE: Bulletins 7760F, 7761F, 7762F and 7763F, firmware release 6.xxx or
# later — 7760F-UM001A-EN-P p. 9 names exactly that family and says "This
# manual applies only to this series of products."
# NOT CLAIMED: the low-voltage Bulletin 150 SMC-50 (that is
# profiles/rockwell_smc50.toml, sourced from 150-UM011F), the SMC Flex, the
# SMC-3, and the 7703F OEM controller described in Chapter 1 — p. 9's own scope
# statement lists four bulletins and 7703F is not among them.
#
# WHY A SEPARATE FILE WHEN THE MAP IS THE SAME
# 7760F-UM001A-EN-P p. 11: the MV controller uses "the same control module as
# the Allen-Bradley Bulletin 1500 SMC-50 controller." Every register below was
# re-read out of the MV manual, not inherited: Logic Status (p. 120 Table 45)
# and Logic Command (p. 121 Table 46) are bit-for-bit the LV tables, the fault
# codes (pp. 130-131 Table 51) match, and the Appendix A parameter numbers
# match. Two things do NOT transfer, which is why this is its own file:
#   1. Appendix A here has NO parameters 69...74 — no Braking Current, Brake
#      Load Type, High Eff Brake, Slow Speed 1 or Slow Brake Cur (list jumps
#      68 -> 75, p. 168). The LV clone range [[1045,1072],[1074,1136]] would
#      address parameters this unit does not publish, so [parameters] below is
#      narrowed to 46-68 and 75-137.
#   2. Engineering ranges: par 1-4 volts and par 5-8 amps print 0/15000 here
#      (LV prints 0/700 V). Same 1 count = 1 unit, but 4160 on the panel is a
#      normal reading on this machine, not a fault.
#
# MODBUS PATH ASSUMED BY THIS PROFILE
# No embedded Modbus. The control module speaks DPI and needs a 20-COMM-x
# module in control-module hardware port 9, which reports as DPI port 4
# (7760F-UM001A-EN-P p. 39 Table 2 and its footnote, repeated p. 116). This
# profile assumes the **20-COMM-H RS-485 HVAC adapter with its protocol
# selector set to Modbus RTU**, in default **16-bit parameter mode** (adapter
# par 32 [RTU Param Mode] = 0). 7760F-UM001A-EN-P p. 115 lists RS485 HVAC =
# 20-COMM-H = 20COMM-UM009 as the available option.
# The MV manual does NOT re-derive the adapter's register map, serial defaults,
# or comm-loss behaviour — those come from 20COMM-UM009D, and no statement in
# 7760F-UM001A-EN-P contradicts it. Nothing here applies to a 20-COMM-M (Modbus
# TCP) or to any other module.
#
# SOURCES
#   Rockwell 7760F-UM001A-EN-P, OneGear Medium Voltage SMC-50 Motor Controller
#   (10...15 kV) User Manual, October 2019
#     p. 9         family/bulletin coverage, firmware level
#     p. 11        same control module as Bulletin 1500 (LV) SMC-50
#     pp. 38-40    DPI ports, 20-COMM-x in hardware port 9, MV control wiring
#     pp. 115-116  comm module / manual cross-reference, DPI port table
#     pp. 117-119  Logic Mask (par 148/149), Exp Removed on disconnect
#     pp. 120-122  Table 45 Logic Status, Table 46 Logic Command, scale-factor
#                  rule, "does not offer the analog Reference feature"
#     pp. 130-131  Table 51 fault/alarm code cross-reference
#     pp. 163-195  Appendix A, SMC-50 parameter list
#   Rockwell 20COMM-UM009D-EN-P, 20-COMM-H RS-485 HVAC Adapter User Manual
#     pp. 3-3...3-9  serial defaults, DPI I/O Cfg, Network Timeout, Comm Flt Action
#     pp. 4-2...4-9  Modbus register map, addressing rule, parameter direct access
#     p. B-4         par 32 [RTU Param Mode], default 16-bit
#
# ADDRESSING — 0-BASED PROTOCOL ADDRESSES, FC03/06/16 HOLDING REGISTERS.
# 20COMM-UM009D p. 4-2: "you must address it to one less than the Modbus
# address in the manual", so Logic Command 4x0001 -> 0-based 0.
# Drive parameter direct access (p. 4-4 Table 4.C "4x1000 + param #", p. 4-9),
# 16-bit mode:
#     0-based address = 999 + parameter number
#   par 5  [Current Phase Ave] -> 999 + 5  = 1004
#   par 43 [Product Status]    -> 999 + 43 = 1042
# CAUTION, off-by-one in the vendor manual: p. 4-9 gives the formula
# "41000 + (Drive Parameter #)" and then says parameter 1 is at 41000 — one
# less than its own formula. Formula and Table 4.C agree on 999 + param#, so
# that is used here and the worked example is treated as the error. CONFIRM ON
# HARDWARE by reading par 43 at 1042 and checking the bit pattern against a
# known starter state before trusting any parameter address.
# 32-bit parameters (real power, energies, elapsed times, peak currents) are
# NOT reachable in 16-bit mode; adapter par 32 = 1 switches everything to
# 999 + 2*param#, which this profile does not model.
# The I/O image (3x input registers, FC04) is a SEPARATE address space and is
# deliberately unused — every monitor point below is a holding register.
#
# DRIVE-SIDE SETUP — without these the starter ACKs and ignores control writes.
#   par 148 [Logic Mask] bit 4 = 1 (DPI port 4 = the comm module).
#     Factory default is 0: out of the box the starter accepts NO start command
#     from any DPI port (7760F-UM001A-EN-P p. 117 and p. 118 Table 42). Stop
#     commands are accepted from any port regardless of the mask ("Stop
#     commands override all start commands ... regardless of the logic mask",
#     p. 117).
#   par 150 [Write Mask Cfg] bit 4 = 1 to allow parameter writes from port 4
#     (default 7FFF already enables ports 1-4).
#   20-COMM-H par 16 [DPI I/O Cfg] bit 0 = 1 (Cmd/Ref), the default.
#   20-COMM-H node address: rotary switches, or switches at 00 and par 03.
#   Enabling the mask also makes pulling the module a fault: "Exp Removed
#   (X026)" where X is the DPI port number (p. 117 footnote 1).
#
# SCALING — 7760F-UM001A-EN-P p. 121: values on the wire are UNSCALED integers;
# the divisor is that parameter's own number of decimal places as printed in
# Appendix A. The manual's own examples: par 17 [Power Factor] stores 85 for
# 0.85; par 78 [Motor FLC] 75 A is written as 750. It is NOT a fixed fieldbus
# scale and NOT the HIM display format — re-check Appendix A per parameter.
#
# NO SPEED REFERENCE. p. 121: "The SMC-50 control module does not offer the
# analog Reference feature." The adapter reserves a reference word the starter
# ignores, so [control] has no speed_register, and there is no run_rev — a soft
# starter does not reverse.
#
# MV I/O WIRING DIFFERS FROM LV — labels only, no register changes.
# p. 40 Figures 26/27: Aux #1 is always External Bypass and Aux #2 always the
# line contactor; Start / Stop Option / Coast come from a 150-SM4 Digital I/O
# card in slot 7 (In A1/A2/A3), not the base control-module terminals. Status
# bits 14/15 [Input #1/#2] below are the CONTROL MODULE inputs, which on an MV
# unit are wired differently than on LV — do not read them as start/stop.

name = "Allen-Bradley OneGear SMC-50 MV (soft starter)"
vendor = "Allen-Bradley"
device_type = "soft_starter"
verified = false
probe_register = 1042  # par 43 Product Status, readable whenever DPI is alive

# 20-COMM-H defaults: 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 installed module.
[serial]
baudrate = 9600
parity = "N"
stopbits = 1

[monitor]
# par 43 [Product Status] — the DPI Logic Status word, 7760F-UM001A-EN-P p. 120
# Table 45. Bits 12-13 are reserved and always 0.
status_word = { address = 1042, bits = { 0 = "ENABLED_READY", 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", 14 = "INPUT_1", 15 = "INPUT_2" } }
# par 5-8 Current Phase Ave/A/B/C. Appendix A prints 0/15000 Amps with no
# decimal place, so 1 count = 1 A. par 78 [Motor FLC] carries one decimal
# (default prints 1.0, and p. 121 writes 75 A as 750) — different scale.
motor_current = { address = 1004, unit = "A" }
current_a = { address = 1005, unit = "A" }
current_b = { address = 1006, unit = "A" }
current_c = { address = 1007, unit = "A" }
# par 1-4 Volts Phase PP Ave / A-B / B-C / C-A, 0/15000 V, no decimals.
# MEDIUM VOLTAGE: a healthy reading here is thousands of volts (par 46
# [Line Voltage] defaults to 4160), not the hundreds an LV unit shows.
line_voltage = { address = 1000, unit = "V" }
voltage_ab = { address = 1001, unit = "V" }
voltage_bc = { address = 1002, unit = "V" }
voltage_ca = { address = 1003, unit = "V" }
# par 17, -1/1 with two decimals. Positive is LEADING, negative LAGGING.
power_factor = { address = 1016, scale = 0.01, signed = true }
motor_thermal = { address = 1017, unit = "%" }   # par 18 Motor Therm Usage, 0/200 %MTU
# par 34, estimated, only meaningful in linear-speed start/stop modes.
motor_speed = { address = 1033, unit = "%" }
line_frequency = { address = 1223, unit = "Hz" } # par 224, 0/100, no decimals
board_temp = { address = 1215, unit = "C", signed = true }  # par 216, -25/100 C

# DPI Logic Command word, adapter holding register 4x0001 -> 0-based 0
# (20COMM-UM009D p. 4-7 Table 4.F). Bit meanings are the SMC-50's own,
# 7760F-UM001A-EN-P p. 121 Table 46 — NOT the PowerFlex bits printed in the
# adapter manual. Bits 8-10 are reserved and must always be written 0.
#   0 Stop (Coast/Inhibit)  1 Start  2 Stop Option (stop maneuver)
#   3 Clear Fault  5 Emergency Run  11 Aux Enable  12-15 Network #1-#4 outputs
# The MV Table 46 leaves bits 4, 6 and 7 BLANK — it does not define the Slow
# Speed 1/2 and Motor Winding Heater functions the LV table names there. This
# profile writes none of those bits, so the omission does not matter here.
# NEITHER par 72 [Slow Speed 1] NOR par 350 is published in 7760F-UM001A-EN-P
# — its Appendix A jumps 68 -> 75 and 349 -> 351, and "Slow Speed" appears
# nowhere in it. The MV slow-speed feature is entirely undocumented here; do
# not assume it exists.
[control]
command_register = 0
step_delay = 0.05
# Bit 0 = Coast/Inhibit: removes power unconditionally and holds the starter
# inhibited until cleared. Bit 2 [Stop Option] would instead run the configured
# stop maneuver (par 65 [Stop Mode], default 0 = Coast anyway), gentler on a
# pump but dependent on drive configuration. The deterministic one is used.
stop = [0x0001]
# 0x0000 first clears 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 Fault], pulsed. 0x0008 has bit 1 clear, so this reset value is
# NOT also a run command.
reset = [0x0000, 0x0008, 0x0000]
# run_rev deliberately absent: a soft starter has no reverse.

# 20-COMM-H par 11 [Network Timeout] defaults to 10 s (range 0-180, 0 disables).
# On expiry the module applies par 15 [Comm Flt Action], which DEFAULTS TO
# "Fault" — the starter faults and stops. Other settings (Hold Last, Zero Data)
# leave a running motor running, so the failure direction depends entirely on
# how the module was commissioned. 1 s keepalive gives 10x margin at the
# default timeout; shorten if par 11 was reduced. 7760F-UM001A-EN-P names no
# MV-specific comm-loss parameter of its own; this is the adapter's behaviour.
[control.watchdog]
interval_ms = 1000
fault = "20-COMM-H Network Timeout (par 11) -> Comm Flt Action (par 15, default Fault)"

[running_check]
register = 1042
bit = 1                  # Logic Status bit 1 = Running (power applied to motor)

# par 138 [Fault 1] is the newest entry in the five-deep fault buffer;
# par 139-142 hold the older four (7760F-UM001A-EN-P p. 128).
# Codes from expansion modules and DPI peripherals are PREFIXED with the port
# number — p. 129 shows "9026 Exp Removed" and "7028 Exp" in a real buffer, and
# p. 117 writes the code as X026. Strip the leading digit before matching codes
# 26, 27, 28 and the TB Input codes 38-41.
[faults]
register = 1137
history = [1138, 1139, 1140, 1141]

# 7760F-UM001A-EN-P pp. 130-131, Table 51 cross-reference plus Table 52
# descriptions. Codes 71-77 are EVENT codes (Start, Stop Option, Coast, Clear
# Fault, Fault, Param Change) that land in the alarm buffer, not fault codes,
# and are omitted. 78-99 are reserved. 100-199 are generic "System Faults"
# with no per-code table published.
[faults.codes]
0 = "None"   # inferred from par 138 [Fault 1] default 0 (Appendix A p. 173), not a Table 51 row
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 = "SCR Overtemp"
11 = "Open Bypass A"
12 = "Open Bypass B"
13 = "Open Bypass C"
14 = "No Load"
15 = "Open Load A"
16 = "Open Load B"
17 = "Open Load C"
18 = "Voltage Unbalance"
19 = "Overvoltage"
20 = "Undervoltage"
21 = "Overload"
22 = "Underload"
23 = "Jam"
24 = "Stall"
25 = "Phase Reversal"
26 = "Exp Removed (port digit prefixes this code)"
27 = "Exp Incompat (port digit prefixes this code)"
28 = "Expansion (port digit prefixes this code)"
29 = "Excess Starts"
30 = "CT Loss A"
31 = "CT Loss B"
32 = "CT Loss C"
33 = "HAL ID"
34 = "NVS Error"
35 = "V24 Recovery"
36 = "V24 Loss"
37 = "VControl Loss"
38 = "TB Input 1"
39 = "TB Input 2"
40 = "TB Input 3"
41 = "TB Input 4"
42 = "Current Imbalance"
43 = "Under Power Real"
44 = "Over Power Real"
45 = "Under Power Reactive +"
46 = "Over Power Reactive +"
47 = "Under Power Apparent"
48 = "Over Power Apparent"
49 = "Frequency"
50 = "PM Hours"
51 = "PM Starts"
52 = "Power Quality A"
53 = "Power Quality B"
54 = "Power Quality C"
55 = "Power Quality THD V"
56 = "Power Quality THD I"
57 = "Config Change"
58 = "Ground Fault"
59 = "Motor PTC"
60 = "Power Pole PTC"
61 = "I/O Config"
62 = "Test Fault"
63 = "Under PF Lag"
64 = "Under PF Lead"
65 = "Over PF Lag"
66 = "Over PF Lead"
67 = "-MVAR Over"
68 = "-MVAR Under"
69 = "RTC Battery Low"
70 = "Locked Rotor"

# Starter and motor configuration only — the block an electrician actually
# clones. Ranges are parameter numbers mapped through 999 + param#:
#   par 46-68  (1045-1067) line voltage, motor data, start/stop modes, ramps,
#              kickstart, current limits, backspin, pump pedestal
#   par 75-137 (1074-1136) overload, FLC, service factor, and every protection
#              level/delay, plus fault/alarm enable bitfields
# PARAMETERS 69...74 DO NOT EXIST IN THIS MANUAL — Appendix A jumps 68 -> 75
# (p. 168), i.e. the LV braking and slow-speed parameters are not published for
# the MV unit. The adapter errors on a nonexistent parameter number, which is
# why this is two ranges and why the LV profile's upper bound of 1072 is NOT
# reused here.
# Deliberately excluded: par 1-45 metering and motor connection (read-only or
# commissioning-fixed), par 138-147 fault/alarm buffers (restoring them would
# forge history), par 148-152 logic/write masks (restoring these changes who is
# allowed to command the starter), par 153-168 Datalink pointers, par 195-198
# autotune results (read-only, unit-specific), par 216-231 and 240-296 metering
# (read-only), and everything on ports 7/8/9 — option-module parameters
# (150-SM2, 150-SM4) are NOT reachable through 4x1000 + param#, which addresses
# the control module only.
[parameters]
ranges = [[1045, 1067], [1074, 1136]]

# No [rating] block. Appendix A publishes no READ-ONLY parameter carrying the
# starter's own frame or current rating — par 78 [Motor FLC] is a writable
# nameplate entry, so it would be restored along with the clone and could not
# catch a mismatched target. The only per-unit sizing data in the manual, par
# 170 [User CT Ratio] and par 171 [I FDBK scale] ("set at the factory to
# achieve proper current ratio for FLC ratings", p. 177), were considered and
# rejected too: both are R/W, and both are correctly outside the clone ranges
# below. On a 10...15 kV machine, compare catalog numbers
# by hand before restoring a configuration onto a different unit.

[connection]
summary = "The OneGear MV SMC-50 has no compatible embedded Modbus port for this profile; install a Rockwell 20-COMM-H RS-485 adapter and connect it through DPI."
warnings = ["Medium-voltage equipment: only qualified personnel following the site MV switching, grounding, and arc-flash procedure may access this cabinet.", "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 = "Control-module hardware port 9 (reported as DPI port 4)"
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 = ["Follow the site MV isolation, test-for-dead and grounding procedure.", "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 = ["Have qualified MV personnel install the 20-COMM-H in hardware port 9, select RTU and set a unique node.", "Keep adapter par 32 = 0 and par 16 bit 0 = 1.", "Set par 148 Logic Mask bit 4 and par 150 Write Mask bit 4.", "Configure timeout/fault action and verify MV permissives before any command test."]
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 7760F-UM001A-EN-P pp. 38-40 and 115-122; 20COMM-UM009D-EN-P pp. 2-1 to 2-7."

[[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