# Property of PMA Electrical Solutions, LLC.
#
# Benshaw EMX4e low-voltage soft starter using the optional Modbus RTU or
# Modbus TCP communications card. The card manuals explicitly cover both
# EMX4e and EMX4i, but this separate profile keeps the distinct Benshaw product
# families selectable by their actual name. Do not apply it to CSXi/EMX3.
#
# Sources (Benshaw primary documentation):
#   710-21970-00B, "Modbus RTU Communications option for EMX4e/EMX4i soft
#   starters, User Guide" (2020), printed pp. 2-13:
#     pp. 2-3 setup, network control and timeout behavior
#     pp. 4-10 standard/legacy maps and RTU examples
#     pp. 11-12 trip codes; p. 13 communications specifications
#   710-21971-00A, equivalent Modbus TCP card guide, printed pp. 7-14:
#     same legacy holding-register map; explicit legacy-mode initialization
#   710-21918-00C, "EMX4e User Manual", printed pp. 32 and 72:
#     Command Source = Network; RTU defaults 9600, no parity, timeout Off
#
# MAP MODE: vfd-core reads holding registers (FC03), while the card's Standard
# Mode puts status in the FC04-only 3xxxx space. This profile therefore uses
# the documented Legacy Mode, which mirrors status at 4xxxx and commands via
# 40002. On the TCP card, initialize Legacy Mode after changing modes by
# cycling control power or writing zero to 40001 (TCP guide p. 10).
#
# ADDRESSING: Benshaw prints traditional 4xxxx register references. All values
# below are 0-based protocol addresses: 4xxxx - 40001. Thus 40002 -> 1,
# 40604 -> 603, and 40619 -> 618.
#
# DRIVE-SIDE SETUP: parameter 1A Command Source = Network. A closed
# reset/enable input is also required. The transports have different
# communication-loss settings:
#   * RTU: 12A-12D set address, baud, parity and timeout. 12D defaults Off;
#     set it to at least 10 s. The card reads changes only at power-up.
#   * TCP: 6I Network Communications (user manual p. 62) controls the loss
#     response and defaults to Soft Trip and Log. Parameter 12D does not apply.
#
# The starter-state register is an enumeration, not a running bit, so this
# profile deliberately has no [running_check]. A soft starter has no speed
# reference. Reverse/jog commands appear in state reporting but the documented
# command register exposes no reverse command, so run_rev is absent.

name = "Benshaw EMX4e"
vendor = "Benshaw"
device_type = "soft_starter"
verified = false
probe_register = 603

[connection]
summary = "EMX4e/EMX4i do not have embedded Modbus. Select and install either the vendor RTU card or the vendor TCP card."
warnings = ["A closed reset/enable input is required; if no reset switch is used, follow the manual instruction for terminals 10 and 11."]

[[connection.methods]]
id = "modbus_rtu_card"
title = "Optional Modbus RTU expansion card"
transport = "serial"
hardware = "option"
port = "Five-way plug on the EMX4 Modbus RTU expansion card"
connector = "Removable five-position plug"
adapter = "Isolated USB-to-RS-485 adapter, 2-wire half-duplex"
cable = "Shielded twisted-pair RS-485 cable, 120 ohm nominal impedance"
parts = ["Isolated two-wire RS-485 adapter", "Shielded twisted-pair RS-485 cable, 120 ohm nominal impedance", "EMX4 Modbus RTU communications option card"]
steps = ["Lock out line and control power, wait the vendor-specified discharge time, and verify the DC bus is de-energized before opening a cover or landing conductors.", "Match the adapter's Data A conductor to card Data A and its Data B conductor to card Data B; use the adapter manual because A/B polarity naming is not standardized.", "Route the communications cable away from motor and mains conductors. Terminate the two physical ends of a long multidrop trunk only.", "Restore control power with the motor area clear, configure the starter from its keypad, then verify identity and read-only monitor data before enabling remote control."]
setup = ["Set 1A Command Source=Network; for RTU set 12A address, 12B baud, 12C parity, and 12D timeout, then cycle control power. For TCP configure 12H-12U and the network-loss response."]
warnings = ["Benshaw labels these conductors only Data A and Data B; the source does not assign + or - polarity. Match like-for-like labels using the adapter documentation.", "Do not use protective earth as the data return unless the vendor drawing explicitly calls for it.", "Pins 1/2 are internally duplicated Data A and pins 4/5 are internally duplicated Data B for daisy chaining; do not treat them as separate buses.", "Isolate the soft starter from mains voltage before removing the expansion-port cover."]
source = "Benshaw 710-21970-00B Modbus RTU Card guide, printed pp. 1-3 (installation, five-way pinout, setup); 710-21971-00A Modbus TCP Card guide, printed pp. 1-4 (installation, Ethernet and IP setup)"

[[connection.methods.wiring]]
adapter = "Adapter Data B (per adapter manual)"
device = "Card pins 4 and 5 (Data B)"
signal = "RS-485 Data B; polarity is not assigned by Benshaw"
required = true

[[connection.methods.wiring]]
adapter = "Adapter Data A (per adapter manual)"
device = "Card pins 1 and 2 (Data A)"
signal = "RS-485 Data A; polarity is not assigned by Benshaw"
required = true

[[connection.methods.wiring]]
adapter = "Adapter signal ground / shield"
device = "Card pin 3 (Common)"
signal = "Signal reference or shield drain"
required = false

[[connection.methods]]
id = "modbus_tcp_card"
title = "Optional Modbus TCP expansion card"
transport = "tcp"
hardware = "option"
port = "Either Ethernet port on the EMX4 Modbus TCP card"
connector = "Two switched RJ45 Ethernet ports"
adapter = "Computer Ethernet interface or Ethernet switch"
cable = "Category 5, 5e, 6, or 6e Ethernet patch cable"
parts = ["EMX4 Modbus TCP communications option card", "Category-rated Ethernet patch cable"]
steps = ["Lock out and isolate the equipment before fitting an option module or opening the enclosure.", "Install and fully seat the specified communications module according to its installation instructions.", "Connect the computer or switch with the specified Ethernet cable; keep it separated from motor and mains wiring.", "Restore control power, assign an IP address on the same subnet, discover the device, and verify read-only data before enabling network control."]
setup = ["Set 1A Command Source=Network; for RTU set 12A address, 12B baud, 12C parity, and 12D timeout, then cycle control power. For TCP configure 12H-12U and the network-loss response.", "A new card defaults to 192.168.0.2/24; configure the computer on the same subnet, then store permanent addressing through starter parameters 12H-12U."]
warnings = ["An Ethernet link does not make remote motor control safe. Verify the drive-side communication-loss action and the independent hardwired stop circuit before commanding run.", "Keep Ethernet cable at least 200 mm from motor and mains cables; cross them at 90 degrees when unavoidable.", "Isolate mains voltage before fitting or removing the card."]
source = "Benshaw 710-21970-00B Modbus RTU Card guide, printed pp. 1-3 (installation, five-way pinout, setup); 710-21971-00A Modbus TCP Card guide, printed pp. 1-4 (installation, Ethernet and IP setup)"

# EMX4e user manual p. 72 defaults. With no parity, the RTU card guide p. 3
# requires two stop bits for standard 11-bit Modbus transmission.
[serial]
baudrate = 9600
parity = "N"
stopbits = 2

[monitor]
# 40604 low five bits: 1 Ready, 2 Starting, 3 Running, 4 Stopping, 5 Not ready,
# 6 Tripped, 7 Programming, 8 Jog forward, 9 Jog reverse. Kept raw because it
# is an enum; interpreting individual bits as independent flags is unsafe.
starter_state = { address = 603 }
# The card reports current 10x actual for starter models 0064B and smaller,
# but reports whole amperes on larger models. No conditional scale exists in
# the profile schema, so retain raw counts rather than mislabel either class.
motor_current_raw = { address = 604 }
motor_current_pct = { address = 605, unit = "% FLC" }
motor_thermal = { address = 606, unit = "%" }
# Power embeds a two-bit scale selector in bits 12-13; expose the word raw.
power_raw = { address = 607 }
power_factor = { address = 608, scale = 0.01 }
line_voltage = { address = 609, unit = "V" }
l1_current_raw = { address = 610 }
l2_current_raw = { address = 611 }
l3_current_raw = { address = 612 }
l1_voltage = { address = 613, unit = "V" }
l2_voltage = { address = 614, unit = "V" }
l3_voltage = { address = 615, unit = "V" }
input_status = { address = 617, bits = { 0 = "StartStop", 2 = "Reset", 3 = "InputA", 4 = "InputB" } }

# Legacy command register 40002: 1 Start, 2 Stop, 3 Reset, 4 Quick Stop,
# 5 Forced Communication Trip, 6/7 Start with parameter set 1/2.
[control]
command_register = 1
step_delay = 0.05
stop = [2]
run_fwd = [1]
# Finish on Stop because the core keepalive re-sends the last command. Leaving
# 3 latched would issue Reset on every keepalive cycle.
reset = [2, 3, 2]

[control.watchdog]
backstop_requires_setup = true
interval_ms = 2500
fault = "RTU: 12D timeout defaults Off; TCP: 6I network loss defaults Soft Trip and Log"

[faults]
register = 618

[faults.codes]
0 = "No trip (Modbus TCP card)"
1 = "Excess start time"
2 = "Motor overload"
3 = "Motor thermistor"
4 = "Current imbalance"
5 = "Frequency"
6 = "Phase sequence"
7 = "Overcurrent (RTU) / Instantaneous overcurrent (TCP)"
8 = "Power loss"
9 = "Undercurrent"
10 = "Heatsink overtemperature"
11 = "Motor connection"
12 = "Input A trip"
13 = "FLC too high"
14 = "Unsupported option in inside-delta mode"
15 = "Communications card fault"
16 = "Network communication (RTU) / Forced network trip (TCP)"
17 = "Internal fault (Modbus TCP card)"
18 = "Overvoltage"
19 = "Undervoltage"
23 = "Parameter out of range"
24 = "Input B trip"
26 = "L1 phase loss"
27 = "L2 phase loss"
28 = "L3 phase loss"
29 = "L1-T1 shorted"
30 = "L2-T2 shorted"
31 = "L3-T3 shorted"
33 = "Time-overcurrent (bypass overload)"
34 = "SCR overtemperature"
35 = "Battery / clock"
36 = "Thermistor circuit"
47 = "Overpower"
48 = "Underpower"
56 = "Keypad disconnected"
57 = "Zero speed detect"
58 = "SCR Itsm"
59 = "Instantaneous overcurrent"
60 = "Rating capacity"
70 = "Current read error L1"
71 = "Current read error L2"
72 = "Current read error L3"
73 = "Remove mains volts (Modbus TCP card)"
74 = "Motor connection T1"
75 = "Motor connection T2"
76 = "Motor connection T3"
77 = "Firing fail P1"
78 = "Firing fail P2"
79 = "Firing fail P3"
80 = "VZC fail P1"
81 = "VZC fail P2"
82 = "VZC fail P3"
83 = "Low control volts"
84 = "Internal fault 84"
85 = "Internal fault 85"
86 = "Internal fault 86"
87 = "Internal fault 87"
88 = "Internal fault 88"
89 = "Internal fault 89"
90 = "Internal fault 90"
91 = "Internal fault 91"
92 = "Internal fault 92"
93 = "Internal fault 93"
94 = "Internal fault 94"
95 = "Internal fault 95"
96 = "Internal fault 96"
255 = "No trip (Modbus RTU card)"

# No [parameters]: the card exposes a model/version-dependent parameter block
# beginning at 40009, and warns that Advanced group writes can cause
# unpredictable behavior. The card guide does not publish a stable, complete
# register-to-parameter table suitable for cross-unit clone/restore.
# No [rating]: 40601 is a model ID, but the cited documents do not map those
# IDs to electrical frame ratings.