# Property of PMA Electrical Solutions, LLC.
#
# Danfoss VLT SOFT STARTER MCD 600 — not a VFD. No speed reference, no reverse.
#
# COMMUNICATION PATH THIS PROFILE ASSUMES: the plug-in **Modbus RTU Card**,
# order code 175G0127 (or 175G0027 with ground fault protection), driven in
# **LEGACY MODE**. Modbus is not on the bare MCD 600; the card carries the
# RS-485 port (5-way plug, pins 1/2 Data A, 3 Common, 4/5 Data B).
#
# WHY LEGACY MODE. The card offers two register maps (AQ277154312778 §5.2):
#   - Standard Mode puts the command at 40001 but every read-only value in the
#     3xxxx INPUT-register space (30600-30622), which needs FC04.
#   - Legacy Mode mirrors the same soft-starter data into the 4xxxx holding
#     registers, matching the clip-on MCD Modbus Module used on the MCD 500.
# This app speaks FC03 (read holding registers) only, so Standard Mode would
# give a working command register and a status map that answers nothing.
# Legacy Mode is selected by bit 15 = 0 in register 40001, which is the
# power-up state. If the card has previously been driven in Standard Mode,
# EITHER cycle control power OR write 0 to register 40001 (protocol address 0)
# before using this profile (AN353424224484 §7.5.1, AN428736661763 §7.2).
#
# Sources — Danfoss primary only:
#   AQ277154312778en-000201 "Installation Guide, Modbus RTU Card, VLT Soft
#   Starter MCD 600":
#     p.6     card versions 175G0127 / 175G0027
#     p.7     5-way connector pinout
#     p.8     client framing, 300 ms minimum poll, parameters 12-1..12-4,
#             par 1-1 Command Source = Network, the RESET/COM+ link, and the
#             Network Communications trip on inactive comms
#     p.9     Standard vs Legacy Mode; parameter management limits
#     pp.9-12 Standard Mode registers (NOT used here — 3xxxx input registers)
#     pp.13-15 worked examples and Modbus error codes
#   AN353424224484en-000101 "Installation Guide, Modbus TCP Card, VLT Soft
#   Starter MCD 600" — the SAME soft starter and the same two modes, and the
#   only Danfoss document that TABULATES the MCD 600 legacy map, which the RTU
#   card guide names but does not print:
#     pp.20-23 §7.5 Legacy Mode registers 40001-40631
#     pp.23-25 §7.6 trip codes
#   AQ262141844215en-000401 "Operating Guide VLT Soft Starter MCD 600":
#     pp.74-79 §10.4 parameter list — the ORDER that fixes the parameter
#              register map
#     p.111    12-2 Modbus Baud Rate / 12-3 Modbus Parity / 12-4 Modbus Timeout
#     p.94     6-13 Network Communications protection action
#     p.113    20-4 Model Rating (read-only) and the group 20-** warning
#
# ADDRESSING. Danfoss prints Modicon 4xxxx holding-register numbers. 0-based
# protocol address = number - 40001:
#   40002 Command       -> 1
#   40003 Starter state -> 2
#   40009 1st parameter -> 8
#   40619 Trip code     -> 618
# The ground for the -40001 conversion is the card's own Standard Mode, which
# AQ277154312778 §5.2 calls "registers defined in the Modbus Protocol
# Specification" with Command at 40001 — protocol address 0 in that
# specification. VERIFY ON A BENCH BEFORE ARMING. It fails safe in both
# directions: one high puts the command write on read-only status (Modbus error
# 03 / 02), one low puts it on the mode-select register 40001, where writing 1
# or 2 leaves bit 15 clear and so still selects Legacy Mode rather than
# starting anything.
#
# STARTER-SIDE SETUP — without these the starter monitors but will not run:
#   1-1  Command Source   = Network
#   12-1 Modbus Address, 12-2 Baud Rate, 12-3 Parity, 12-4 Timeout
#   A link across terminals RESET and COM+ if no reset switch is wired: with
#   the reset input active the soft starter does not operate at all.
#
# POLLING FLOOR: AQ277154312778 p.8 sets a 300 ms MINIMUM polling interval and
# warns that shorter intervals cause "inconsistent or incorrect behavior,
# particularly when reading multiple registers". That is why step_delay and the
# watchdog interval below are unusually long for this repo.
#
# RESERVED HIGH BITS: currents and voltages in the 40600 block are 14-bit and
# % FLC is 10-bit, with the top bits marked Reserved. This app has no per-point
# mask, so those points are exposed raw and read correctly while the reserved
# bits are 0.
#
# SMALL FRAMES READ 10x HIGH: on MCD6-0063B and smaller (model ID 1-4), every
# current register reports ten times the actual value. Divide by 10 by eye on
# those units; there is no register that says which frame you are on other than
# the model ID at 40601.

name = "Danfoss VLT MCD 600 (soft starter)"
vendor = "Danfoss"
device_type = "soft_starter"
verified = false
probe_register = 2  # 40003 starter state, legacy mode

[connection]
summary = "Install the MCD 600 Modbus RTU Card and use its supplied 5-way plug; this profile requires the card's Legacy Mode register map."
warnings = ["Isolate control and line power before installing the expansion card.", "The vendor names the conductors Data A and Data B but does not state A/B polarity in this guide; match those literal labels at both ends instead of guessing D+/D-."]

[[connection.methods]]
id = "modbus_rtu_card"
title = "MCD 600 Modbus RTU Card"
transport = "serial"
hardware = "option"
port = "Card 5-way plug: pins 1/2 Data A, pin 3 Common, pins 4/5 Data B"
connector = "5-way male card header with supplied unplugging female connector"
adapter = "Isolated USB-to-RS-485 adapter whose A/B labeling can be verified from its datasheet"
cable = "Shielded RS-485 twisted pair with reference conductor"
parts = ["Modbus RTU Card 175G0127 or 175G0027", "Supplied 5-way plug", "RESET-to-COM+ link when no reset switch is fitted"]
wiring = [{ adapter = "Data A (verify adapter label)", device = "Pin 1 or 2, Data A", signal = "RS-485 Data A" }, { adapter = "Data B (verify adapter label)", device = "Pin 4 or 5, Data B", signal = "RS-485 Data B" }, { adapter = "Common", device = "Pin 3, Common", signal = "RS-485 reference" }]
steps = ["Isolate the starter and install the correct MCD 600 Modbus RTU expansion card.", "Fit the supplied 5-way plug and land Data A, Common, and Data B by literal name; duplicate A/B pins permit bus continuation.", "Fit RESET-to-COM+ if no reset switch is wired, then restore all covers before power-up.", "Connect the verified RS-485 adapter and select its computer serial port."]
setup = ["Set 1-1 Command Source = Network and configure 12-1 Address, 12-2 Baud, 12-3 Parity, and 12-4 Timeout.", "Use Legacy Mode (bit 15 clear in register 40001); power-cycle or write 0 to 40001 if the card was left in Standard Mode."]
warnings = ["Poll no faster than 300 ms.", "Standard Mode places read data in FC04 input registers and is incompatible with this profile's FC03 reads."]
source = "Danfoss AQ277154312778en-000201, pp. 6-9; AQ262141844215en-000401, pp. 94 and 111"

# Factory defaults per AQ262141844215 p.111: 12-2 = 9600, 12-3 = None. The stop
# bits follow from AQ277154312778 p.8 — 2 stop bits with no parity, 1 stop bit
# with odd or even.
[serial]
baudrate = 9600
parity = "N"
stopbits = 2

[monitor]
# 40003. Bits 0-3 are a STATE VALUE, not flags: 1 Ready, 2 Starting, 3 Running,
# 4 Stopping, 5 Restart delay, 6 Tripped, 7 Programming mode, 8 Jog forward,
# 9 Jog reverse. Only bits 4-6 are true flags, so only those are named.
starter_status = { address = 2, bits = { 4 = "PositivePhaseSeq (only valid if bit 6)", 5 = "CurrentExceedsFLC", 6 = "Initialised" } }
motor_current_8bit = { address = 4, unit = "A" }   # 40005, saturates at 255 A
motor_temperature = { address = 5, unit = "%" }    # 40006, motor thermal model

# --- 40600 extended block ---
# 40600 bits 0-5 binary protocol version, 6-8 parameter list version,
# 9-15 product type code (15 = MCD 600).
version = { address = 599 }
model_number = { address = 600 }                   # 40601, bits 8-15 model ID
# 40604. Bits 0-4 are a state VALUE; only the flag bits are named.
starter_state = { address = 603, bits = { 5 = "Warning", 6 = "Initialised", 7 = "CommandSourceIsNetwork", 9 = "PositivePhaseSeq" } }
current_avg = { address = 604, unit = "A" }        # 40605, average rms, bits 0-13
current_pct_flc = { address = 605, unit = "%" }    # 40606, bits 0-9
motor_thermal = { address = 606, unit = "%" }      # 40607
power_factor_pct = { address = 608, unit = "%" }   # 40609, 100 = pf 1.00
voltage_avg = { address = 609, unit = "V" }        # 40610, average rms, bits 0-13
phase1_current = { address = 610, unit = "A" }     # 40611
phase2_current = { address = 611, unit = "A" }     # 40612
phase3_current = { address = 612, unit = "A" }     # 40613
phase1_voltage = { address = 613, unit = "V" }     # 40614
phase2_voltage = { address = 614, unit = "V" }     # 40615
phase3_voltage = { address = 615, unit = "V" }     # 40616
param_list_version = { address = 616 }             # 40617
# 40618. Bit 0 is Start/Stop on the MCD 600 — one input, not two. The reset
# input is normally CLOSED by default, so 1 is the healthy state unless
# parameter 7-9 Reset/Enable Logic has been set to normally open, which inverts
# the whole register's reported polarity.
digital_input_state = { address = 617, bits = { 0 = "Start/Stop", 2 = "Reset", 3 = "InputA", 4 = "InputB" } }
trip_code = { address = 618 }                      # 40619, bits 0-7
# 40004 is exposed ALONGSIDE 40619 because two Danfoss documents disagree about
# which one carries the trip code in Legacy Mode on this starter, and the
# disagreement cannot be settled on paper:
#   - AN353424224484 §7.5.2 Table 5 (the Modbus TCP card guide, whose Legacy
#     table this profile follows) marks 40004 Reserved and puts trip code 40619.
#   - AQ277154312778 §5.6 Table 6 — the guide for the RTU card this profile is
#     actually written against — shows a worked "Trip Code: Motor Overload"
#     example reading 40004 with FC03, in a section whose neighbouring examples
#     use 40002 Command and 40003 State, so it is unambiguously Legacy Mode.
# Reading both is free and settles it in one look on the first faulted unit:
# whichever register carries a non-zero code when the starter is tripped is the
# live one. [faults] points at 40619; if the field shows 40003 bit 2 set while
# 40619 reads 0 and 40004 does not, move [faults].register to 3.
trip_code_alt = { address = 3 }                    # 40004, per AQ277154312778 §5.6
#
# 40608 Power is deliberately absent: it packs a 2-bit exponent into bits 12-13
# (0 = x10 W, 1 = x100 W, 2 = kW, 3 = x10 kW) beside a 12-bit mantissa, and a
# fixed `scale` cannot decode that. A raw read would be off by up to 100x.

# 40002 Command in Legacy Mode. The whole register is a VALUE, not a bit mask:
#   1 Start, 2 Stop, 3 Reset, 4 Quick stop (coast), 5 Forced communication trip,
#   6 Start using Parameter Set 1, 7 Start using Parameter Set 2.
# Reset is 3 and start is 1, so the reset value CANNOT be read as a start and
# reset can safely share the command register.
#
# NOTE for anyone tempted to switch this profile to Standard Mode: there the
# command is a BIT MASK at 40001 with bit 15 forced to 1 — start is 0x8001,
# stop 0x8000, reset 0x8002 — and the values below would mean nothing.
#
# A soft starter has no speed reference and no reverse: neither speed_register
# nor run_rev is defined, so `control speed` and `control run_rev` refuse
# rather than writing somewhere harmless-looking.
[control]
command_register = 1
step_delay = 0.3          # the card's documented 300 ms minimum interval
stop = [2]
run_fwd = [1]
reset = [3]

# Parameter 12-4 Modbus Timeout selects Off / 10 s / 60 s / 100 s and its
# FACTORY DEFAULT IS OFF — so out of the box nothing trips when the master goes
# quiet, and a running motor keeps running with no master attached. Set 12-4 to
# 10 s and the starter reacts per 6-13 Network Communications (default "Soft
# Trip and Log"), after which a reset is required. Keep the link fed either
# way. 1 s comfortably clears the 300 ms polling floor and the 10 s timeout.
[control.watchdog]
interval_ms = 1000
fault = "Network Communications, trip code 16 (par 6-13; armed only when par 12-4 Modbus Timeout is set)"

# 40601 bits 8-15 carry the soft starter model ID; bits 0-7 are Reserved. This
# is a MODEL IDENTITY, not an ampere rating, so the number is the raw register
# (model ID x 256 while the reserved byte is 0) and only equality is
# meaningful. It is still the only thing on this map that can stop a 579 A
# MCD6-0579B configuration being restored onto a 20 A MCD6-0021B. If the
# reserved byte is ever non-zero the comparison fails CLOSED — it blocks the
# restore rather than waving it through, which is the right direction.
[rating]
register = 600
words = 1
label = "soft starter model ID (bits 8-15 of legacy register 40601)"

# 40619 trip code, bits 0-7, masked so a stray high byte cannot corrupt the
# lookup. AN353424224484 §7.6 gives 255 = No trip for THIS (Legacy) map.
#
# 0 IS DELIBERATELY NOT NAMED "No trip". It is only the Standard Mode value
# (AQ277154312778 §5.7), and this profile does not use Standard Mode. Naming it
# here would be actively dangerous given the 40004-vs-40619 conflict recorded on
# trip_code above: if 40619 turns out to be Reserved on the RTU card it reads a
# constant 0, and a mapping of 0 -> "No trip" would report a TRIPPED starter as
# healthy — a confident wrong answer on a faulted machine. Left unnamed, a 0
# displays as an unknown code, which is the honest reading and is visibly odd
# enough to send someone to trip_code_alt. Cross-check 40003 bits 5/6 (Tripped)
# before believing any "no trip" conclusion.
[faults]
register = 618
mask = 0x00FF

[faults.codes]
1 = "Excess start time"
2 = "Motor overload"
3 = "Motor thermistor"
4 = "Current imbalance"
5 = "Frequency"
6 = "Phase sequence"
7 = "Overcurrent"
8 = "Power loss"
9 = "Undercurrent"
10 = "Heat sink overtemperature"
11 = "Motor connection"
12 = "Input A trip"
13 = "FLC too high"
14 = "Unsupported option (not available in inside delta)"
15 = "Communications card fault"
# Code 16: the two guides name this differently and it matters for diagnosis.
# AN353424224484 §7.6 calls it "Network communication" (a comms-loss trip);
# AQ277154312778 §5.7 p. 13 — the RTU card's own list — calls it "Forced
# network trip", i.e. the response to command value 5, which is a deliberate
# master-commanded trip rather than a lost link. Both names are carried here so
# neither reading misleads. See [control.watchdog] below.
16 = "Network communication / forced network trip"
17 = "Internal fault"
18 = "Overvoltage"
19 = "Undervoltage"
20 = "Motor overload"
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 = "LCP disconnected"
57 = "Zero speed detect"
58 = "SCR itsm"
59 = "Instantaneous overcurrent"
60 = "Rating capacity"
70 = "Current read err L1"
71 = "Current read err L2"
72 = "Current read err L3"
73 = "Remove mains volts (mains connected during run simulation)"
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"
255 = "No trip"

# Parameters 40009 onwards. The first product parameter is always 40009
# (protocol 8) and they run in AQ262141844215 §10.4 list order — including the
# Reserved entry 1-7, which still occupies an index. Confirmed twice by the
# card's own worked examples: parameter index 9 = 2-2 Start Ramp Time at 40017,
# and 2-9 Stop Mode at 40024. Group sizes are 1:7, 2:18, 3:20, 4:24, 5:18,
# 6:20, 7:11, 8:10, 9:4, 10:13, 11:7, 12:21 — 173 parameters through group 12,
# so protocol address = index + 7 and group 12 ends at protocol 180.
#
# CHECK BEFORE RESTORING: register 30602 high byte (Standard Mode) reports the
# total number of parameters actually in the starter, and 40617 reports the
# parameter list version. If the list differs from the one above, every address
# here is shifted — do not restore.
#
# Deliberate holes and end point:
#   protocol 8    = 1-1 Command Source. Writing it mid-restore can point the
#                   starter away from Network and sever control.
#   protocol 145  = 10-6 Current Calibration, a PER-UNIT calibration that must
#                   never be cloned onto another starter.
#   protocol 160+ = group 12 Communication Card (address, baud, parity, IP).
#                   Writing those severs the link the restore is running over.
#   protocol 181+ = group 20 Advanced. Danfoss states plainly that changing
#                   these "may cause unpredictable behavior in the soft
#                   starter", and 20-4 Model Rating is read-only.
[parameters]
ranges = [[9, 144], [146, 159]]

# No [running_check]. "Running" is the VALUE 3 in bits 0-3 of 40003, not a bit:
# bit 1 alone is also set by Starting (2), Tripped (6) and Programming mode (7),
# so no single bit means running. Commands therefore come back marked
# unverified, which is the honest answer. Read starter_status and compare its
# low nibble to 3.