# Property of PMA Electrical Solutions, LLC.
#
# Danfoss VLT AutomationDrive FC 301 / FC 302 — the general-purpose machine
# drive of the FC 300 platform. FC 301 is V/f + VVC+, FC 302 adds flux vector
# and closed-loop motor control plus extra I/O.
#
# MODEL COVERAGE: both. Danfoss ships ONE programming guide and ONE design
# guide for the pair, and the parameter list marks FC 302-exclusive parameters
# with a dedicated "FC 302 only" column (MG33MO02 §5.2, p. 227). EVERY point
# in this file is flagged as common to both — nothing here carries that mark.
# FC 302-only readouts (16-24 Calibrated Stator Resistance, 16-31 System Temp.,
# 16-49 Current Fault Source, 16-67/16-70 pulse I/O) are deliberately OMITTED
# rather than shipped as a silent cross-model claim.
#
# Sources, all primary Danfoss:
#   MG33BF02  FC 301/302 Design Guide 0.25-75 kW, Rev 2013-12-20
#             pp. 183-190 — Modbus RTU, holding-register map, coil map,
#             FC-profile control word (Table 12.20) and status word
#             (Table 12.23), bus reference scaling (§12.13.3)
#   MG33MO02  FC 301/302 Programming Guide, 01/2018 (SW 7.62 / 48.2X / 8.10)
#             pp. 132-137 — parameter group 8-** and its defaults
#             pp. 185-191 — parameter group 16-** readout descriptions
#             pp. 227, 246-247 — data type, conversion index, FC 302-only flag
#   MG33AG22  FC 300 Instruction Manual, p. 6-4 (PDF p. 110), Table 6.3 —
#             alarm word / warning word / extended status word bit layout
#   MG92B102  Modbus RTU Operating Instructions, Rev 2011-10-31, p. 16 —
#             register-address worked example (secondary confirmation only)
#
# Wiring: terminal 68 (+P RS485), 69 (-N RS485). Terminal 61 is the
# RC-filtered common; connect it only if you have EMC trouble.
#
# Drive-side setup: 8-30 Protocol = [2] Modbus RTU — the FACTORY DEFAULT IS
# [0] FC, and the change does not take effect until the drive is power-cycled
# (MG33MO02 p. 137). Then 8-31 Address, 8-32 Baud Rate, 8-33 Parity/Stop Bits.
# For bus control also set 8-01 Control Site and 8-02 Control Word Source; 8-02
# self-selects [3] Option A at first power-up if a fieldbus option card is
# present, so on a drive that ever had one fitted it will NOT be listening to
# the FC RS485 port until you set it to [1] FC RS485. 8-10 Control Word Profile
# must stay [0] FC profile (the default) — the control-word values below are
# the FC profile, not PROFIdrive.
#
# ADDRESSING: register = parameter_number * 10 - 1, where par 16-13 is the
# integer 1613, so 1613 * 10 - 1 = 16129. MG33BF02 §12.11.8/§12.12.1 gives the
# rule as "(10 x parameter number) DECIMAL" against the 1-based 4xxxx space,
# and MG92B102 p. 16 confirms the minus-one on the wire with a worked example
# (3-41 -> holding register 3410 -> telegram address 0xD51 = 3409).
#
# WIDTH IS PER PARAMETER — see the `words` key on each point below, taken from
# the Type column of MG33MO02 p. 246. Reading a 16-bit parameter as 2 registers
# splices in the neighbouring parameter. NOTE these differ from the AQUA
# FC 202: on the FC 300 platform 16-16 Torque [Nm] and 16-22 Torque [%] are
# BOTH Int16 (1 register), not Int32.

name = "Danfoss VLT AutomationDrive FC 301 / FC 302"
vendor = "Danfoss"
device_type = "vfd"
verified = false
probe_register = 16029  # 16-03 status word

[connection]
summary = "Connect the computer to the built-in FC RS-485 port at terminals 68/69."
warnings = ["Remove power and verify the DC link is discharged before opening the drive.", "Do not route RS-485 beside motor or mains conductors."]

[[connection.methods]]
id = "built_in_rs485"
title = "Built-in FC RS-485"
transport = "serial"
hardware = "built_in"
port = "Control terminals 68 (+P/TX+/RX+), 69 (-N/TX-/RX-), optional 61 common"
connector = "FC-port control terminal plug"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded RS-485 twisted pair"
parts = ["Small insulated screwdriver", "S801 termination only at a bus end"]
wiring = [{ adapter = "D+ / B+", device = "68 (+P, TX+/RX+)", signal = "RS-485 positive" }, { adapter = "D- / A-", device = "69 (-N, TX-/RX-)", signal = "RS-485 negative" }, { adapter = "COM/GND", device = "61", signal = "Optional RC-filtered common", required = false }]
steps = ["Isolate power and locate the 68/69 FC-port terminal plug.", "Land the positive and negative pair exactly as marked; connect 61 only if needed for the documented reference/EMC case.", "Set S801 only when this drive is at a physical end of the bus.", "Close the drive, restore power, and select the USB adapter's serial port."]
setup = ["Set 8-30 = 2 Modbus RTU and power-cycle as required, then set 8-31, 8-32, and 8-33.", "Set 8-02 = 1 FC RS485 when an option card previously caused Option A to be selected; keep 8-10 = 0 FC profile."]
warnings = ["The 8-30 protocol change requires a power cycle.", "An installed or previously installed fieldbus option can divert control away from the FC port."]
source = "Danfoss MG33BF02, pp. 178-180; MG33MO02, pp. 132-137"

# MG33MO02 p. 137: 8-32 default [2] 9600 Baud, 8-33 default [0] Even Parity,
# 1 Stop Bit. Not 8N1.
[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, MG33BF02 Table 12.23. 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 (0 = at/outside them). Both polarities read
# backwards from their bit names and were inverted in an earlier revision of
# this repo. Bit 5 is Reserved on the FC 300 platform and is left unnamed.
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: the
# manual contradicts itself on their scaling and the disagreement cannot be
# settled from paper. MG33MO02 §5.2.16 p. 246 types 16-15 as N2 with conversion
# index -2 and prints its range as [-100.00 - 100.00 %], i.e. 2 decimals and
# +/-10000 raw. The competing sentence on p. 186 ("scale 0000-4000 hex" of 4-19)
# describes the CYCLIC PCD channel, and its own next line says so — it tells you
# to set 9-16 PCD Read Configuration to send it with the status word. This
# profile reads 16149 with FC03, the parameter channel, where the conversion
# index governs. Corroborating: the genuinely-raw N2 parameters 16-82 Fieldbus
# REF 1 and 16-86 FC Port REF 1 carry conversion index 0, while 16-05 and 16-15
# carry -2 precisely because they have a scaled percent display.
#
# An earlier revision shipped 16-15 at 100/16384 per count on the p. 186 reading
# while omitting the identically-typed 16-05 "for the same reason" — the two
# cannot both be right. 16-13 (16129) already gives output frequency in Hz
# unambiguously, so nothing is lost by leaving both out. If percent is wanted,
# read 16149 at a known output frequency on real hardware: scale = 0.01 if it
# reads 10000 at max, 0.006103515625 if it reads 16384.
motor_thermal = { address = 16179, unit = "%" }                # 16-18, Uint8
# 16-16 is torque in Nm (0.1 Nm/count), NOT percent. Percent is 16-22.
# Int16 on the FC 300 platform — one register, unlike the FC 202.
torque_nm = { address = 16159, signed = true, scale = 0.1, unit = "Nm" }
torque_pct_hires = { address = 16209, signed = true, scale = 0.1, unit = "%" }  # 16-21, Int16, conv -1
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
control_card_temp = { address = 16389, unit = "C" }            # 16-39, Uint8, conv 100 = factor 1

# --- 32-bit parameters (words = 2) ---
# 16-10 Int32, conversion index 1 (factor 10) against the SI base unit WATT:
# MG33MO02 p. 185 spells it out — "the resolution of readout value on fieldbus
# is in 10 W steps" — so raw * 10 = W, i.e. * 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 Int32, conversion index 67. That index is the RPM unit tag (1/60 of the
# SI per-second base), not a wire multiplier: the parameter range is
# -30000..30000 RPM and 1-25 Motor Nominal Speed carries the same index in a
# Uint16, which could not hold a 60x-scaled 1500 RPM. The wire value is RPM.
motor_speed = { address = 16169, words = 2, signed = true, unit = "rpm" }
# Process feedback (16-52, Int32, conv -3) in the 3-01 Reference/Feedback Unit,
# and encoder/estimated speed feedback (16-57, Int32, RPM per the note above).
feedback_unit = { address = 16519, words = 2, signed = true, scale = 0.001 }
feedback_rpm = { address = 16569, words = 2, signed = true, unit = "rpm" }

[control]
command_register = 49999   # holding register 50000 CTW, MG33BF02 Table 12.16
speed_register = 50009     # holding register 50010 REF
# MG33BF02 §12.13.3: the bus reference is a relative value in %, 16384 (0x4000)
# = 100% of 3-03 Max Reference, two's complement for negatives. NOT Hz.
speed_scale = 0.006103515625
speed_unit = "%"
max_ref = 100.0
step_delay = 0.05
# FC-profile control word, MG33BF02 Table 12.20. 0x043C sets bit 2 (ramp, not
# DC brake), bit 3 (no coasting), bit 4 (ramp, not quick stop), bit 5 (use
# ramp) and bit 10 (data valid) — everything released except the start.
stop = [1084]             # 0x043C
run_fwd = [1084, 1148]    # 0x043C then 0x047C, bit 6 start
# Bit 7 Reset is edge-triggered ("activated on the signal's leading edge"), so
# it must be raised and lowered again; 0x04BC is the stop word plus bit 7, i.e.
# the reset value is NOT a run command on this register.
reset = [1212, 1084]      # 0x04BC rising edge, then back to stop
# run_rev is deliberately absent. MG33BF02 p. 188, bit 15: "In the default
# setting, reversing is set to digital in 8-54 Reversing Select. Bit 15 causes
# reversing only when Ser. communication, Logic or or Logic and is selected."
# 8-54's default is expression-limited but resolves to the digital input, so a
# "reverse" command on a stock drive silently runs the motor FORWARD.
# Set 8-54 appropriately and add run_rev = [1084, 33916] if you need it.

# 8-03 Control Word Timeout Time defaults to 20 s, but 8-04 Control Word
# Timeout Function is expression-limited and its [0] Off option means the drive
# "resumes control via fieldbus using the most recent control word" — so a run
# command followed by silence leaves the motor running 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, range 0.01-10000.00 A
# (MG33MO02 p. 187). Frame identity for the restore precondition.
[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: several bits can be set
# at once, so there is no code table to look up. Bit layout from MG33AG22
# Table 6.3 — identical to the FC 202's, alarm numbers in the names below.
#
# 16-91 Alarm Word 2 is NOT included: most of it is "reserved" and the live
# bits (17 KTY error, 18 Fans error, 19 ECB error, 29 Feedback Fault, 30 PTC 1
# Safe Stop, 31 Dangerous Failure) share NO layout with word 1.
#
# 16-92 Warning Word is NOT included as history: despite the similar name its
# bit layout DIVERGES from the alarm word at bits 12, 13, 15, 17, 19-21, 25-29
# and 31 (bit 12 is "DC Voltage Low W6" warning vs "Short Circuit A16" alarm),
# 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" }