# Property of PMA Electrical Solutions, LLC.
#
# Danfoss VLT Decentral Drive FCD 302 — the motor-mounted / wall-mounted FC 302
# for conveyor and food-and-beverage lines, 0.37-3.0 kW.
#
# PROVENANCE — READ THIS BEFORE TRUSTING THE MAP. The FCD 302's own manuals do
# NOT print a register table, a control word, a status word or an alarm word.
# They deliberately delegate:
#
#   FCD 302 Design Guide, AJ267037025114en-000501 (MG04H3xx, SW 7.5x), §1.1.1
#   "Additional Resources", p. 6:
#     - "VLT AutomationDrive FC 301/302 Programming Guide, for information
#        about how to program the unit, including complete parameter
#        descriptions."
#     - "Modbus RTU Operating Instructions, for the information required for
#        controlling, monitoring, and programming the frequency converter via
#        the built-in Modbus fieldbus."
#   FCD 302 Operating Guide, AQ267036816112en-000301 (© 2025.04, SW 9.X.X),
#   §1.2 p. 7 repeats the pointer to the FC 301/302 Programming Guide, and
#   §5.7.1 p. 38 confirms the built-in protocols are "Danfoss FC" and
#   "Modbus RTU" on the drive's own RS485, with 8-30/8-31/8-32 as the setup
#   parameters (§5.7.2 p. 38 — that page lists 8-30/8-31/8-32 only; 8-33 Parity
#   is sourced from MG33MO02 p. 137, not from here).
#
# WHICH DOCUMENT CARRIES THE FIELDBUS-MAP CLAIM, AND HOW OLD IT IS. Only the
# 2018 Design Guide (SW 7.5x) delegates the Modbus REGISTER MAP — that is the
# "Modbus RTU Operating Instructions" bullet above. The 2025 Operating Guide
# DROPPED that bullet: its §1.2 list names the FC 301/302 Programming Guide,
# the PROFIBUS DP-V1 guide and the STO guide, and no Modbus document. So the
# current documentation delegates parameter descriptions but no longer
# delegates the fieldbus map, and the map below rests on a 2018 statement about
# SW 7.5x while the shipping firmware is SW 9.X.X.
#
# That is the specific risk in this file. Every register below is the FC 302
# map on the vendor's own 2018 statement that it applies — a documented
# delegation, not a cross-family carry — but it is one indirection weaker than
# a first-party table AND the delegating document is seven years stale. Danfoss
# publishes no FCD 302 parameter list, so the per-parameter WIDTHS in
# particular are inherited from MG33MO02's SW 8.10 list and cannot be
# first-party confirmed. Nothing in either FCD manual contradicts the inherited
# map — they contain no register, control-word, status-word or alarm-word table
# at all — but absence of contradiction is not confirmation. Check 15-43
# Software Version on the unit before trusting the widths.
#
# Two things the FCD 302's manuals DO confirm first-hand:
#   - the 16-** readout parameters are the FC 300 set (its design guide uses
#     16-01, 16-02, 16-18 and 16-20 by name, pp. 21, 32, 63)
#   - the alarm/warning NUMBERING is the FC 300 numbering (Operating Guide
#     §6.9.2, pp. 47-62: A4 mains phase loss, W5/W6 DC link, A9 inverter
#     overload, A30-A32 motor phase loss, ...), which is what the 16-90 alarm
#     word bits below decode to.
#
# Underlying sources (see danfoss_fc302.toml for the full page-by-page list):
#   MG33BF02  FC 301/302 Design Guide, pp. 183-190 — Modbus, holding registers,
#             FC-profile control word (Table 12.20) and status word (12.23)
#   MG33MO02  FC 301/302 Programming Guide, pp. 132-137, 185-191, 227, 246-247
#   MG33AG22  FC 300 Instruction Manual, p. 6-4 — alarm word bit layout
#   MG92B102  Modbus RTU Operating Instructions, p. 16 — address worked example
#
# Wiring: terminal 68 (+P RS485), 69 (-N RS485), 61 common (FCD 302 Operating
# Guide §5.7.2 p. 38 and terminal table p. 35).
#
# Drive-side setup: 8-30 Protocol = [2] Modbus RTU (default is [0] FC, and the
# change needs a power cycle), 8-31 Address, 8-32 Baud Rate, 8-33 Parity.
# For bus control also 8-01 Control Site and 8-02 Control Word Source; on a
# unit with a PROFIBUS/PROFINET/EtherNet-IP option fitted, 8-02 self-selects
# [3] Option A at first power-up and the FC RS485 port is ignored until you set
# it back to [1] FC RS485. 8-10 Control Word Profile must stay [0] FC profile.
#
# ADDRESSING: register = parameter_number * 10 - 1 (par 16-13 -> 1613 -> 16129).
# WIDTH IS PER PARAMETER — 16-16 and 16-22 are Int16, one register each.

name = "Danfoss VLT Decentral Drive FCD 302"
vendor = "Danfoss"
device_type = "vfd"
verified = false
probe_register = 16029  # 16-03 status word

[connection]
summary = "Wire the FCD 302's built-in RS-485 FC port at terminals 68/69 inside the installation enclosure."
warnings = ["Lock out all supply and motor energy before opening this decentralized drive.", "Maintain the enclosure's cable-gland, grounding, and ingress-protection requirements when adding the communication cable."]

[[connection.methods]]
id = "built_in_rs485"
title = "Built-in RS-485 (68/69)"
transport = "serial"
hardware = "built_in"
port = "Control terminals 68 (+P RS-485), 69 (-N RS-485), 61 common"
connector = "Internal control-terminal block"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Industrial shielded twisted-pair RS-485 cable through a suitable gland"
parts = ["Correct enclosure cable gland", "Small insulated screwdriver", "End termination when at a bus end"]
wiring = [{ adapter = "D+ / B+", device = "68 (+P)", signal = "RS-485 positive" }, { adapter = "D- / A-", device = "69 (-N)", signal = "RS-485 negative" }, { adapter = "COM/GND", device = "61 common", signal = "RS-485 reference", required = false }]
steps = ["Lock out the installation and open the FCD 302 enclosure according to the operating guide.", "Bring the communication cable through a correctly rated gland and locate terminals 68, 69, and 61.", "Land the positive/negative pair and optional common exactly as marked, preserving shield bonding and enclosure sealing.", "Close the enclosure before power-up, then connect and select the computer adapter."]
setup = ["Set 8-30 to Modbus RTU and configure 8-31 address and 8-32/8-33 framing.", "For control, set 8-02 = 1 FC RS485 if Option A was selected, and keep 8-10 at FC profile."]
warnings = ["Do not use the Ethernet M12 fieldbus plugs for this Modbus RTU profile.", "Improper gland installation defeats the FCD enclosure rating."]
source = "Danfoss AQ267036816112en-000301, pp. 35 and 38; AJ267037025114en-000501, p. 6"

[serial]
baudrate = 9600
parity = "E"
stopbits = 1

[monitor]
# --- 16-bit parameters (words = 1) ---
control_word = { address = 15999 }                          # 16-00, V2
reference_pct = { address = 16019, signed = true, scale = 0.1, unit = "%" }  # 16-02, Int16, conv -1
# 16-03 status word. Bit 2 = 1 means ENABLE (0 = the drive has released the
# motor); bit 10 = 1 means the output frequency is WITHIN the 4-11/4-13 limits.
# Both polarities read backwards from their bit names. Bit 5 is Reserved.
status_word = { address = 16029, bits = { 0 = "CtrlReady", 1 = "DriveReady", 2 = "NotCoasting", 3 = "Trip", 4 = "ErrorNoTrip", 6 = "TripLock", 7 = "Warning", 8 = "SpeedEqRef", 9 = "BusControl", 10 = "WithinFreqLimits", 11 = "InOperation", 12 = "StoppedAutoStart", 13 = "VoltageExceeded", 14 = "TorqueExceeded", 15 = "TimerExceeded" } }
motor_voltage = { address = 16119, scale = 0.1, unit = "V" }   # 16-12, Uint16, conv -1
output_frequency = { address = 16129, scale = 0.1, unit = "Hz" }  # 16-13, Uint16, conv -1
# 16-15 Frequency [%] and 16-05 Main Actual Value [%] are both OMITTED, for the
# reason given at the same point in profiles/danfoss_fc302.toml: MG33MO02 p. 246
# types 16-15 as N2 conversion index -2 (range +/-100.00 %, so +/-10000 raw),
# while p. 186's "scale 0000-4000 hex" sentence describes the cyclic PCD channel
# rather than the FC03 parameter read this profile performs. The manual
# contradicts itself and paper cannot settle it. 16-13 (16129) already gives
# output frequency in Hz unambiguously.
motor_thermal = { address = 16179, unit = "%" }                # 16-18, Uint8
# 16-16 is torque in Nm (0.1 Nm/count), NOT percent. Percent is 16-22.
torque_nm = { address = 16159, signed = true, scale = 0.1, unit = "Nm" }
torque_pct = { address = 16219, signed = true, unit = "%" }    # 16-22, Int16, conv 0
dc_link_voltage = { address = 16299, unit = "V" }              # 16-30, Uint16, conv 0
heatsink_temp = { address = 16339, unit = "C" }                # 16-34, Uint8, conv 100 = factor 1
inverter_thermal = { address = 16349, unit = "%" }             # 16-35, Uint8

# --- 32-bit parameters (words = 2) ---
# 16-10 reads out in 10 W steps on the fieldbus, so raw * 0.01 = kW.
power_kw = { address = 16099, words = 2, scale = 0.01, unit = "kW" }
motor_current = { address = 16139, words = 2, scale = 0.01, unit = "A" }  # 16-14, Int32, conv -2
# 16-17 conversion index 67 is the RPM unit tag, not a wire multiplier.
motor_speed = { address = 16169, words = 2, signed = true, unit = "rpm" }
feedback_unit = { address = 16519, words = 2, signed = true, scale = 0.001 }  # 16-52, Int32, conv -3
feedback_rpm = { address = 16569, words = 2, signed = true, unit = "rpm" }    # 16-57, Int32

[control]
command_register = 49999   # holding register 50000 CTW
speed_register = 50009     # holding register 50010 REF
# Bus reference is % of 3-03 Max Reference: 16384 (0x4000) = 100%. NOT Hz.
speed_scale = 0.006103515625
speed_unit = "%"
max_ref = 100.0
step_delay = 0.05
stop = [1084]             # 0x043C — ramp, no coasting, no quick stop, data valid
run_fwd = [1084, 1148]    # then 0x047C, bit 6 start
reset = [1212, 1084]      # 0x04BC edge on bit 7, then back to stop
# run_rev is deliberately absent. Control word bit 15 reverses ONLY when 8-54
# Reversing Select is set to serial communication (or Logic and/or); the
# default resolves to the digital input, so a "reverse" command on a stock
# drive silently runs the motor FORWARD. Set 8-54, then add
# run_rev = [1084, 33916] if you need it.

# 8-03 Control Word Timeout Time defaults to 20 s and 8-04's [0] Off option
# resumes on the most recent control word, so silence after a run command
# leaves a decentral drive running out on the machine with no master attached.
[control.watchdog]
interval_ms = 500
fault = "A17/W17 Control Word Timeout (8-04; 8-03 time defaults to 20 s)"

[running_check]
register = 16029          # 16-03 status word, 16-bit
bit = 11                  # In operation

# 16-36 Inv. Nom. Current, Uint32, conversion index -2. Frame identity for the
# restore precondition — worth more than usual here, since FCD 302 units are
# scattered across a machine and are easy to mix up.
[rating]
register = 16359
words = 2
scale = 0.01
unit = "A"
label = "Inverter nominal current"

# 16-90 Alarm Word is a 32-bit BITFIELD, not an enum. Bit layout from MG33AG22
# Table 6.3; the alarm numbers in the names match the codes the FCD 302's own
# Operating Guide lists in §6.9.2.
#
# 16-92 Warning Word is NOT included: despite the similar name its bit layout
# DIVERGES from the alarm word at bits 12, 13, 15, 17, 19-21, 25-29 and 31, so
# decoding it with these names would mislabel every one of those.
[faults]
register = 16899          # 16-90 alarm word
words = 2
bitfield = true
bits = { 0 = "BrakeCheck_A28", 1 = "HeatsinkTemp_A29", 2 = "GroundFault_A14", 3 = "CtrlCardTemp_A65", 4 = "CtrlWordTimeout_A17", 5 = "OverCurrent_A13", 6 = "TorqueLimit_A12", 7 = "MotorThermistorOverTemp_A11", 8 = "MotorETR_OverTemp_A10", 9 = "InverterOverloaded_A9", 10 = "DCUnderVoltage_A8", 11 = "DCOverVoltage_A7", 12 = "ShortCircuit_A16", 13 = "SoftChargeFault_A33", 14 = "MainsPhaseLoss_A4", 15 = "AMA_NotOK", 16 = "LiveZeroError_A2", 17 = "InternalFault_A38", 18 = "BrakeOverload_A26", 19 = "U_PhaseLoss_A30", 20 = "V_PhaseLoss_A31", 21 = "W_PhaseLoss_A32", 22 = "FieldbusFault_A34", 23 = "Supply24V_Low_A47", 24 = "MainsFailure_A36", 25 = "Supply1V8_Low_A48", 26 = "BrakeResistor_A25", 27 = "BrakeIGBT_A27", 28 = "OptionChange_A67", 29 = "DriveInitialized_A80", 30 = "SafeStop_A68", 31 = "MechBrakeLow_A63" }