# Property of PMA Electrical Solutions, LLC.
#
# Eaton PowerXL DE1 variable speed starter, embedded Modbus RTU.
#
# MODBUS IS BUILT IN — NO OPTION MODULE. MN040018EN §2.3 p. 11: "The integrated
# RJ45 port (COM port) in DA1 and DC1 variable frequency drives and DE1
# variable speed starters supports the Modbus RTU protocol, allowing for a
# direct network connection without the need for an additional interface
# module." RS485- is RJ45 pin 7, RS485+ is pin 8 (§2.3 p. 11). DX-CBL-RJ45…
# cable, DX-SPL-RJ45… splitters, 120 Ω (EASY-NT-R) at each physical end.
# The DX-NET-SWD3 module is for SmartWire-DT, NOT for Modbus.
#
# DE1 ONLY. This profile is built exclusively from the rows MN040018EN
# attributes to the DE1. The manual is shared across DA1 / DC1 / DC1…E1 / DE1
# and the families genuinely diverge — several process-data IDs and fault
# codes are marked "DA1, DC1…E1" and are NOT DE1 registers. Nothing here is
# carried across from a sibling profile.
#
# Source: Eaton MN040018EN, "PowerXL Modbus RTU Communication manual for
# Variable Frequency Drives / Variable Speed Starters DA1, DC1, DE1",
# Manual 09/16, 2nd edition 2016.
#   §2.3   p. 11      RJ45 pinout, embedded port
#   §2.3.1 p. 12      DI1 hardware enable for bus mode
#   §2.3.2 p. 12      data format (DE1 fixed 8N1)
#   §2.4.3 p. 17      DE1 communication parameters (P-12/P-34/P-35/P-36)
#   §2.5.4 pp. 23-24  DE1 control-terminal configuration, direction table
#   §2.6.1 p. 26      function codes: 03 and 06 ONLY
#   §2.6.3 p. 28      DE1 register mapping (in 1-2, out 6-24, param 129-169)
#   §2.6.4 pp. 29-30  input process data, command bits, speed reference
#   §2.6.5 pp. 31-39  output process data, status/fault word, type word
#   §2.6.5.7 p. 38    DE1 type-word decode (frame size, voltage class, rating)
#   §2.6.5.10 p. 39   device recognition: DE1 = 8, DE11 = 9
#   §2.6.6 pp. 40-41  worked telegrams that prove the addressing
#   Table 11 pp. 32-33 fault messages, per device series
#   §3.4   pp. 57-58  DE1 parameter register table
# Corroborating — Eaton MN040011EN, "DE1… Variable Speed Starter" user manual,
# 04/17, 175 pp. Carries a Modbus ID column, so it independently confirms the
# comms parameters rather than merely restating them:
#   p. 164   P-30..P-35 with their Modbus IDs. P-34 = ID 162, range 1-63,
#            default 1. P-35 = ID 163, default 4, and the value list spells the
#            baud rates out: 0 = 960 Bit/s (sic — almost certainly a typo for
#            9600), 1 = 19.2k, 2 = 38.4k, 3 = 57.6k, 4 = 115.2 kBit/s.
#   p. 165   P-36 = ID 164, "Modbus RTU0 COM Timeout", values 0-8, default 0.
#   p. 166   P-47/P-48 named but with NO Modbus ID — and this page is defective,
#            see the note below before using anything from it.
# Secondary (parameter semantics and defaults only, no register addresses):
# Eaton AP040092EN, "PowerXL DE1 Quick-Start-Guide", 03/2019, pp. 18-24.
#
# ADDRESSING. The manual numbers everything by "ID" / "Modbus Register", which
# is 1-based. 0-based protocol address = manual ID - 1. Proven twice by the
# manual's own telegrams: §2.6.6.1 p. 40 reads ID 6 with address field 0005
# ("the ID is 6, since the motor controller has an offset of +1"), and
# §2.6.6.2 p. 41 writes ID 1 with address field 0000. Every address below is
# already converted. No 4xxxx notation anywhere.
#
# ALL HOLDING REGISTERS. §2.6.1.2 p. 26 lists exactly two function codes:
# 03 Read Holding Registers and 06 Write Single Register. There is no FC04
# input-register space and no FC16 multi-write on this device. A read request
# may span at most 11 registers (§2.6.1.2 p. 26); keep polls short.
#
# THIS IS A REAL VARIABLE-FREQUENCY DEVICE, not a contactor-style starter.
# "Variable speed starter" is Eaton's market segmentation, not a limitation of
# the control interface: the DE1 takes a continuous frequency setpoint over the
# bus (ID 2, 0.1 Hz), reports a continuous output frequency (ID 7, 0.1 Hz), and
# exposes f-min/f-max, accel/decel ramps, V/f boost, DC braking and a 4-32 kHz
# switching frequency. Hence device_type = "vfd" and a speed_register.
#
# DRIVE-SIDE SETUP — command and reference both come from the serial port only
# when these are set:
#   P-12 = 3   Local Process Data Source = Modbus Control (§2.4.3 p. 17).
#              Default is 0 (terminal control): the drive will ACK writes to
#              ID 1 / ID 2 and ignore them.
#   P-34       slave address, 1-63 (§2.6.1.1 p. 26). Default 1. Confirmed
#              independently by MN040011EN p. 164, which gives it Modbus ID 162
#              and the same 1-63 range.
#   P-35       baud, default 4 = 115.2 kbit/s (§2.4.3 p. 17). NOT 9600.
#              Confirmed by MN040011EN p. 164, which prints the whole value
#              list and puts 115.2 kBit/s against the factory default of 4.
#   P-36       comm-loss timeout / action. Default 0 = NO ACTION.
#
#   THE P-34 vs P-47 QUESTION IS SETTLED — P-34 IS THE ADDRESS.
#   This was previously flagged as an unresolved firmware divergence, because
#   MN040018EN (2016) says the frame is fixed 8N1 and P-34 sets the address,
#   while AP040092EN (2019) lists P-47 "RS485-0 Address" (1-255) and P-48
#   "RS485-0 ParityType", demoting P-34 to a SmartWire "PDP-Address".
#   The DE1 user manual MN040011EN (04/17, 175 pp) resolves it, and it sits
#   between the two in date:
#     - p. 164, the parameter list: P-34 carries **Modbus ID 162**, access
#       RUN/rw, range **1-63**, default 1, described as "Unique drive address
#       in a communication network." Its printed NAME is "PDP-Address", but the
#       Modbus ID and the description are what matter, and it has both.
#     - p. 166: P-47 "RS485-0 Address" and P-48 "RS485-0 ParityType" appear as
#       names ONLY. Their Modbus ID, Value and DS cells are all EMPTY, and
#       P-47's Description cell is literally "–". They are not in the Modbus
#       map, so they cannot be written over the bus even if they exist.
#   So P-34 (Modbus ID 162 -> 0-based 161) is the address, capped at 63 — NOT
#   the 1-255 the quick-start implies, and well short of Modbus's own 247.
#
#   BEWARE p. 166 OF MN040011EN — IT IS DEFECTIVE. In the "DE11-… variable
#   speed starters only" block the Name column is copy-pasted from the rows
#   above while the Description column describes something else entirely:
#   P-54 is named "RS485-0 ParityType" but has range 0.0-250.0 s and is
#   described as "Delay time before the Relay switches from logic 0 to logic 1".
#   A parity type has no seconds. Rows P-50..P-54 there name AI1 Offset,
#   FireMode Function, Motor Stator Resistance R1, RS485-0 Address and
#   RS485-0 ParityType against relay and CANopen descriptions. Do not take any
#   name from that block. The p. 164 block, which carries real Modbus IDs, is
#   internally consistent and is what this profile uses.
#
# HARDWARE ENABLE IS MANDATORY — the bus alone cannot start this motor.
# §2.3.1 p. 12 and §2.5.4 p. 23: "If Modbus RTU is being used, there must
# always be an enable signal (ENA) present at DI1 control signal terminal (or
# DI2 = ENADIR) before the enable signal sent via Modbus RTU will be accepted."
# With DI1 and DI2 both low the drive stays stopped no matter what is written
# to ID 1. Read the digital_inputs point before concluding a run command failed.
#
# DIRECTION IS A CONTROL-WORD BIT (bit 1), not the sign of the reference, so
# run_rev is present and the reference stays unsigned. Caveat from Table 9
# p. 23: the commanded direction is the XOR of command bit 1 and which enable
# input is driven — with DI2 (ENADIR) high instead of DI1, bit 1 = 0 turns the
# motor REV and bit 1 = 1 turns it FWD. The profile's run_fwd/run_rev assume
# the normal DI1 = ENA wiring.
#
# SETPOINT CAN BE OVERRIDDEN FROM THE TERMINALS. §2.5.4 pp. 23-24: with
# P-15 = 0 or 8 a Modbus setpoint is ignored while DI3 is active; with P-15 = 3
# it is ignored while DI2 is active; with P-15 = 4/5/6 only UP/DOWN set the
# setpoint. Analog input AI1 is disabled in Modbus mode.
#
# SCALING WARNING — TWO DIFFERENT FREQUENCY SCALES. The process-data speed
# reference and actual speed (IDs 2 and 7) are 0.1 Hz per count (§2.6.4.2
# p. 30, §2.6.5.2 p. 33). The *parameter* frequency registers (P-01, P-02,
# P-20..P-23, P-28) are NOT: §3.4 p. 57 gives "3000 = 50.0 Hz", i.e. 60 counts
# per Hz. Do not reuse 0.1 when writing those parameters.
# Also §2.6.3 p. 28: "The decimal point is not taken into account when
# processing values" — the raw integer is the displayed digits without the
# point, which is what the scale factors here undo.

name = "Eaton PowerXL DE1"
vendor = "Eaton"
device_type = "vfd"
verified = false
# ID 17 device recognition, §2.6.5.10 p. 39: reads 8 on a DE1 (9 on a DE11).
# Constant, present whenever the port is alive, and it identifies the family.
probe_register = 16

[connection]
summary = "Use the DE1's integrated RJ45 COM port on RS-485 pins 7/8; no interface module is required."
warnings = ["Isolate the starter before accessing its control wiring.", "This is not Ethernet: RJ45 pins 1/2 and 4/5 carry other buses and must not be connected to the RS-485 adapter."]
[[connection.methods]]
id = "integrated_rj45_rs485"
title = "Integrated RJ45 Modbus RTU"
transport = "serial"
hardware = "built_in"
port = "RJ45 COM port: pin 7 RS485-, pin 8 RS485+"
connector = "Integrated 8P8C/RJ45 COM socket"
adapter = "Isolated USB-to-RS-485 adapter with a verified RJ45 breakout"
cable = "DX-CBL-RJ45/DX-SPL-RJ45 system or shielded breakout cable wired only to pins 7/8"
parts = ["Verified RJ45 breakout or Eaton splitter", "EASY-NT-R termination at bus endpoints"]
wiring = [{ adapter = "D- / A-", device = "RJ45 pin 7, RS485-", signal = "RS-485 negative" }, { adapter = "D+ / B+", device = "RJ45 pin 8, RS485+", signal = "RS-485 positive" }]
steps = ["Isolate the DE1 and locate its integrated COM port.", "Using a pin-verified breakout, connect adapter negative to pin 7 and positive to pin 8 only.", "Fit end termination only at the two physical bus ends.", "Restore power and select the USB adapter serial port."]
setup = ["Set P-12 = 3 Modbus Control, P-34 slave address, P-35 baud, and P-36 timeout/action.", "Maintain the required enable at DI1 (or the documented DI2 ENADIR arrangement); this guide assumes DI1."]
warnings = ["Factory rate is 115200 8N1.", "DI2 ENADIR reverses the direction-bit sense; this profile assumes the normal DI1 enable wiring."]
source = "Eaton MN040018EN, printed pp. 11-17 and 23-24; MN040011EN, printed pp. 164-165"

# §2.3.2 p. 12: DE1 data format is fixed — no parity, 1 start, 1 stop, 8 data.
# §2.4.3 p. 17: P-35 default is 4 = 115.2 kbit/s.
[serial]
baudrate = 115200
parity = "N"
stopbits = 1

# Output process data, §2.6.5 p. 31. IDs converted with address = ID - 1.
# ID 9 (torque) and ID 10 (output power) are marked "DA1, DC1…E1 only" and are
# deliberately absent. IDs 25-28 (serial number) are "Not available on ... DE1
# variable speed starters" (§2.6.5.11 p. 39) and are absent for the same reason.
[monitor]
# ID 6. Bits 0-7 are the status word; bits 8-15 are the FAULT word, i.e. the
# fault code sits in the high byte of this same register (§2.6.5.1 p. 31).
status_word = { address = 5, bits = { 0 = "READY", 1 = "RUN", 2 = "REV", 3 = "FAULT", 4 = "AT_SETPOINT", 5 = "ZERO_SPEED", 6 = "SPEED_CONTROL_ACTIVE", 7 = "HARDWARE_RELEASE" } }
output_frequency = { address = 6, scale = 0.1, unit = "Hz" }   # ID 7 actual speed
motor_current = { address = 7, scale = 0.1, unit = "A" }       # ID 8, 34 = 3.4 A
# ID 11. Lowest bit is DI1 (§2.6.5.6 p. 34). DI1/DI2 carry the mandatory
# hardware enable, so this is the first thing to read when a run is refused.
digital_inputs = { address = 10, bits = { 0 = "DI1", 1 = "DI2", 2 = "DI3", 3 = "DI4" } }
# ID 12, hex-coded part number: nibbles are frame size (1 = FS1, 2 = FS2),
# voltage class (2 = 230 V, 3 = 400 V), input/output phases, output index.
# §2.6.5.7 p. 38, tables 16 and 17.
type_code = { address = 11 }
power_rating = { address = 12, unit = "kW" }   # ID 13; HP on HP-default units
voltage_range = { address = 13, unit = "V" }   # ID 14
sw_version_control = { address = 14 }          # ID 15, two decimal places
sw_version_power = { address = 15 }            # ID 16, two decimal places
device_id = { address = 16 }                   # ID 17: DE1 = 8, DE11 = 9
# From the DE1 parameter table, §3.4 p. 57 (register 23 -> address 22, 24 -> 23).
dc_voltage = { address = 22, unit = "V" }                            # P0-08, 230 = 230 V
heatsink_temperature = { address = 23, signed = true, unit = "C" }   # P0-09, range -10..150

# Input process data, §2.6.4 pp. 29-30. ID 1 -> address 0, ID 2 -> address 1,
# both proven by the worked telegrams at §2.6.6 pp. 40-41.
#
# Command bits (§2.6.4.1 p. 29):
#   0 = 0 Stop / 1 Operational        4 unused
#   1 = 0 FWD  / 1 REV                5 quick stop (ramp 2)
#   2 = 1 Reset fault                 6 fixed frequency FF1
#   3 = 1 Coast to stop               7 overwrite setpoint with 0
[control]
command_register = 0
speed_register = 1
speed_scale = 0.1        # ID 2, 0.1 Hz per count; 500 raw = 50.0 Hz
speed_signed = false     # direction is command bit 1, not the reference sign
speed_unit = "Hz"
max_ref = 300.0          # P-01 tops out at 300 Hz; 300.0 / 0.1 = 3000 raw
step_delay = 0.05
stop = [0x0000]          # bit 0 low = Stop
run_fwd = [0x0001]       # bit 0 high, bit 1 low = clockwise
run_rev = [0x0003]       # bit 0 high, bit 1 high = anticlockwise
# Reset is bit 2 with bit 0 LEFT LOW, so the reset value is a stop word and can
# never itself command a run; the trailing 0x0000 drops the reset bit again.
reset = [0x0004, 0x0000]

# SILENCE DOES NOT STOP THIS MOTOR AT FACTORY DEFAULTS. P-36 "Modbus RTU0 COM
# Timeout" defaults to 0 = "no action" (§2.4.3 p. 17), so a dropped master
# leaves the DE1 running at its last commanded frequency indefinitely. Only
# P-36 = 1-4 trips the device (t 30/100/1000/3000 ms) and P-36 = 5-8 ramps it
# to stop (r 30/100/1000/3000 ms). Set P-36 before arming, and keep refreshing
# the command word.
# interval_ms assumes P-36 = 3 or 4 (1000 ms / 3000 ms). At P-36 = 1 or 2
# (30 ms / 100 ms) no practical RTU poll rate keeps the link alive.
# The fault NAME is a gap, not a guess: MN040018EN Table 11 p. 33 lists the
# Modbus-timeout trip Sc-FO1 (50 dec / 0x32) against "DA1, DC1…E1" and does
# NOT attribute it to the DE1, even though P-36 says the DE1 trips. Confirm the
# code on hardware before adding it to [faults.codes].
[control.watchdog]
interval_ms = 300
fault = "P-36 Modbus RTU0 COM timeout (trip; DE1 code not attributed in MN040018EN Table 11)"

# Status word bit 1 = RUN (§2.6.5.1 p. 31).
[running_check]
register = 5
bit = 1

# §3.4 p. 57, DE1 table: Modbus register 141 = P-13 "Last fault", read-only,
# U16 -> address 140. This row is the DE1's own; the same register number
# carries a different meaning on sibling families, so do not generalise it.
# NO HISTORY REGISTERS. The panel shows the last 8 faults, but §3.4 maps only
# the single register 141 for the DE1 — the other seven have no documented
# Modbus address. Left empty rather than extrapolated.
# The fault code is also readable as the high byte of the status word at
# address 5 (§2.6.5.1 p. 31) if a cross-check is wanted.
[faults]
register = 140

# Table 11 pp. 32-33, DECIMAL "Error no." column. Only rows whose "Device
# series" column names DE1 are included. Codes 19-26, 29-35, 40-44, 49-53,
# 60-74 are all marked "DA1" or "DC1…E1" and are omitted for that reason —
# including the Modbus and CANopen timeout trips (50, 51).
# Two hex typos in the source (16 dec printed as 0x0A, 19 dec as 0x12) do not
# affect these decimal keys.
[faults.codes]
0 = "no-Flt - no fault in the error register"
1 = "OI-b - excessively high braking current"
2 = "OL-br - thermal overload on braking resistor"
3 = "O-I - overcurrent at output"
4 = "I.t-trP - motor overload"
5 = "PS-trp - overcurrent (hardware)"
6 = "O.Volt - overvoltage in DC link"
7 = "VVolt - undervoltage in DC link"
8 = "O-t - overtemperature at heat sink"
9 = "V-t - under-temperature"
10 = "P-dEf - parameter default settings have been loaded"
11 = "E-trip - external fault/warning"
12 = "SC-ObS - communication error with external operating unit or PC"
13 = "FlT-dc - excessively high DC link voltage ripple"
14 = "P-LOss - incoming power phase failure (three-phase supply only)"
15 = "h O-I - overcurrent at output"
16 = "Th-flt - malfunctioning heat sink thermistor"
17 = "dAtA-F - error in internal memory"
18 = "4-20 F - analog input current outside the specified range"

# ID 12 type word, §2.6.5.7 p. 38. Encodes frame size and voltage class, so it
# is the identity to compare before restoring a saved configuration onto a
# replacement unit.
[rating]
register = 11
label = "DE1 type code (frame size / voltage class / phases / rating index)"

# DE1 parameter block, §3.4 pp. 57-58: Modbus registers 129-169 (P-01 to P-41)
# -> addresses 128-168.
# 161-163 (P-34 address, P-35 baud, P-36 comm timeout) are EXCLUDED on purpose.
# Restoring those onto a replacement drive rewrites the node address and baud
# rate mid-transfer and drops the unit off the bus part-way through the clone.
# Registers 178-182 (P-50..P-54) are listed as "Additionally on DE11" and are
# excluded — this profile claims the DE1 only.
[parameters]
ranges = [[128, 160], [164, 168]]