# Property of PMA Electrical Solutions, LLC.
#
# Danfoss VLT HVAC Drive FC 102 — built-in RS-485 (FC port, terminals 68/69),
# no option card. Covers the FC 102 only; the FC 202 (AQUA) and FC 103
# (Refrigeration) are separate files sourced from their own books.
#
# SOURCES — every section below was taken from an FC 102 document, not from the
# shipped FC 202 profile:
#   * MG11BC02, Design Guide VLT HVAC Drive FC 102 1.1-90 kW, Rev 06/2014
#       p. 131      8-30..8-37 RS-485 parameters, 8-33 default even parity 1 stop
#       pp. 139-140 holding-register map (50000/50010/50200/50210) and the
#                   PNU -> "10 x parameter number" translation
#       p. 144      Table 8.33 control word bits (FC profile)
#       pp. 145-146 Table 8.36 status word bits + per-bit polarity text
#       p. 146      bus speed reference scaling, 16384 (0x4000) = 100%
#   * MG11CE02, Programming Guide VLT HVAC Drive FC 102, 03/2015 (SW 4.x)
#       p. 92       8-32 baud / 8-33 parity option lists
#       p. 212      Table 4.3 alarm word / warning word / ext. status word
#       p. 223      Table 5.1 conversion index -> conversion factor
#       p. 230      8-** parameter list (8-04 default [0] Off)
#       pp. 235-236 16-** parameter list: data type and conversion index per
#                   parameter — this is where the per-point `words` come from
#   * AU430028034214en-001901, Programming Guide VLT HVAC Drive FC 102
#     Software Version 7.61, 2024.10
#       pp. 409-410 16-1* parameter descriptions (16-10 "base unit is in W")
#       pp. 719-720 Table 82 alarm word, with the alarm numbers (A2..A80)
#   * MG92B102, Modbus RTU Operating Instructions (Danfoss FC series)
#       p. 15       control/status word coil tables
#       pp. 16-17   register addressing, 32-bit register pairing
#       p. 30       8-32 default [2] 9600 Baud, 8-33 default even parity 1 stop
#
# Wiring: terminal 68 (+P / TX+ RX+), 69 (-N / TX- RX-). Terminal 61 is the
# RC-filtered screen point; connect only if you have EMC trouble.
#
# Drive-side setup: 8-30 Protocol = [2] Modbus RTU, 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 Source to the FC port, and leave 8-10 Control Profile at
# [0] FC profile — the control/status word bits below are the FC profile, not
# PROFIdrive. The drive ACKs writes to the control word and ignores them if
# 8-01/8-02 still point at the terminals.
#
# ADDRESSING: MG11BC02 p. 140 gives holding register = 10 x parameter number,
# and p. 139 states "register addresses start at zero, that is, register 1 is
# addressed as 0". So the 0-BASED WIRE ADDRESS = parameter_number * 10 - 1.
# Par 16-13 -> 1613 -> 16130 -> wire 16129. Cross-checked against MG92B102
# p. 16, whose worked example maps 3-41 to holding register 3410 = 0x0D51.
#
# WIDTH IS PER PARAMETER — see `words` on each point. MG11CE02 pp. 235-236
# lists Uint16/Int16/V2 (1 register) and Int32/Uint32 (2 registers) side by
# side. Reading a 16-bit parameter as 2 registers splices in the neighbouring
# parameter and breaks the running-state interlock.
#
# SCALE: the conversion index in the parameter list converts the raw value to
# the SI BASE unit, not to the displayed unit. 16-10 Power [kW] has index 1
# (x10) because "the base unit is in W" (sw 7.61 guide p. 409) — hence 0.01
# kW/count. 16-17 Speed [RPM] has index 67 (1/60) because the base unit is
# rev/s, so the raw value is already RPM and the scale is 1.

name = "Danfoss VLT HVAC Drive FC 102"
vendor = "Danfoss"
device_type = "vfd"
verified = false
probe_register = 16029  # 16-03 status word

[connection]
summary = "Connect directly to the built-in FC-port RS-485 terminal block; no option card is needed."
warnings = ["Isolate mains and DC-link power and prove the drive dead before touching control wiring.", "Run communication cable separately from motor and mains wiring and terminate only at the two bus ends."]

[[connection.methods]]
id = "built_in_rs485"
title = "Built-in RS-485 (68/69)"
transport = "serial"
hardware = "built_in"
port = "Control terminals 68 (+P/TX+/RX+), 69 (-N/TX-/RX-), optional 61 screen/reference"
connector = "3-pole RS-485 control plug"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "Shielded twisted-pair RS-485 cable"
parts = ["Small insulated screwdriver", "120 ohm end termination or drive switch S801 when 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 screen/reference", required = false }]
steps = ["Isolate power, open the control cover, and identify terminals 68, 69, and 61 by marking.", "Land the twisted pair on 68/69 without swapping polarity; use 61 only for the documented EMC/reference case.", "Enable S801 only if this drive is at a physical end of the RS-485 trunk.", "Close the cover, restore power, and connect/select the computer's RS-485 adapter."]
setup = ["Set 8-30 = 2 Modbus RTU, 8-31 node address, 8-32 baud, and 8-33 parity/stop bits.", "For control, route 8-01/8-02 to the FC port and leave 8-10 at FC profile."]
warnings = ["Do not enable S801 on a mid-bus drive.", "The drive may acknowledge writes but ignore them if 8-01/8-02 still select terminals."]
source = "Danfoss MG11BC02, pp. 111-112 and 131-132; MG92B102, pp. 8-10 and 30"

# MG92B102 p. 30: 8-32 default [2] 9600 Baud, 8-33 default [0] Even parity,
# 1 stop bit. MG11BC02 p. 131 repeats the parity default for the FC port.
[serial]
baudrate = 9600
parity = "E"
stopbits = 1

[monitor]
# --- 16-bit parameters (words = 1) — MG11CE02 pp. 235-236 ---
control_word = { address = 15999 }                                            # 16-00, V2
reference_pct = { address = 16019, signed = true, scale = 0.1, unit = "%" }    # 16-02, Int16, idx -1
# 16-03 status word, V2 (16-bit). Polarity is from MG11BC02 pp. 145-146, not
# inferred from the bit names: bit 2 = 1 means ENABLED (0 = coasting) and
# bit 10 = 1 means the output frequency is WITHIN the limits (0 = outside).
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 = "Running", 12 = "StoppedAutoStart", 13 = "VoltageExceeded", 14 = "TorqueExceeded", 15 = "TimerExceeded" } }
motor_voltage = { address = 16119, scale = 0.1, unit = "V" }    # 16-12, Uint16, idx -1
output_frequency = { address = 16129, scale = 0.1, unit = "Hz" } # 16-13, Uint16, idx -1
motor_thermal = { address = 16179, unit = "%" }                 # 16-18, Uint8, idx 0
torque_pct = { address = 16219, signed = true, unit = "%" }     # 16-22, Int16, idx 0
dc_link_voltage = { address = 16299, unit = "V" }               # 16-30, Uint16, idx 0
heatsink_temp = { address = 16339, unit = "C" }                 # 16-34, Uint8, idx 100
inverter_thermal = { address = 16349, unit = "%" }              # 16-35, Uint8, idx 0
control_card_temp = { address = 16389, unit = "C" }             # 16-39, Uint8, idx 100

# --- 32-bit parameters (words = 2) — MG11CE02 pp. 235-236 ---
power_kw = { address = 16099, words = 2, scale = 0.01, unit = "kW" }             # 16-10, Int32, idx 1 (base W)
motor_current = { address = 16139, words = 2, scale = 0.01, unit = "A" }         # 16-14, Int32, idx -2
# 16-16 is torque in Nm. Percent of rated torque is the separate 16-bit 16-22.
torque_nm = { address = 16159, words = 2, signed = true, scale = 0.1, unit = "Nm" }  # 16-16, Int32, idx -1
motor_speed = { address = 16169, words = 2, signed = true, unit = "rpm" }        # 16-17, Int32, idx 67 (base rev/s)

# 16-05 Main Actual Value [%] and 16-15 Frequency [%] are deliberately absent.
# Both are type N2 (normalised 2 bytes, 0x4000 = 100%), which contradicts the
# conversion index printed alongside them; decode them with the bus-reference
# scale, not the index, if you ever need them.
#
# 16-26/16-27 Power Filtered [kW]/[hp] exist on the FC 102 (they do not on the
# FC 103) but MG11CE02 gives 16-26 conversion index 0 without naming the base
# unit, so the kW/count is not sourceable. Omitted rather than guessed.

[control]
command_register = 49999   # holding register 50000 CTW, MG11BC02 p. 139
speed_register = 50009     # holding register 50010 REF
# MG11BC02 p. 146: the reference is a relative value in %, 16384 (0x4000) =
# 100% of par 3-03 Maximum Reference. It is NOT Hz.
speed_scale = 0.006103515625
speed_unit = "%"
max_ref = 100.0
step_delay = 0.05
# Built from Table 8.33 (MG11BC02 p. 144): bit 2 Ramp, 3 No coasting,
# 4 Ramp (no quick stop), 5 Use ramp, 10 Data valid = 0x043C. Bit 6 = Start.
stop = [1084]             # 0x043C
run_fwd = [1084, 1148]    # 0x043C then 0x047C
# Bit 7 Reset is edge-triggered ("activated on the signal's leading edge",
# MG11BC02 p. 145), so the sequence is a rising edge back to the stop word.
# 0x04BC is not a run command: bit 6 stays 0.
reset = [1212, 1084]      # 0x04BC then 0x043C

# run_rev is deliberately absent. MG11BC02 p. 145: "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." MG11CE02
# p. 231 lists the 8-54 default as size/configuration related, i.e. not
# documented as bus. So a bus "reverse" silently runs the motor FORWARD until
# 8-54 is set. Set 8-54 = [1] Bus and add run_rev = [1084, 33916] if needed.

# 8-04 Control Timeout Function defaults to [0] Off (MG11CE02 p. 230), so a run
# command followed by silence leaves the motor running with no master attached.
# Set 8-03 Control Timeout Time and 8-04 to get Alarm 17 Ctrl. Word TO.
[control.watchdog]
interval_ms = 500
fault = "Alarm 17 Ctrl. Word TO (requires 8-04 to be configured; default Off)"

[running_check]
register = 16029          # 16-03 status word, V2 = 16-bit
words = 1
bit = 11                  # 11 = 1 -> In operation (MG11BC02 p. 146)

# 16-36 Inv. Nom. Current, Uint32, conversion index -2 (MG11CE02 p. 236).
# Read as 2 registers: a 32-bit rating read as one word returns the high half,
# which is 0 on any small frame and would compare equal to every saved source.
[rating]
register = 16359
words = 2
scale = 0.01
unit = "A"
label = "Inverter nominal current (16-36)"

# 16-90 Alarm Word is Uint32 (MG11CE02 p. 236) and a BITFIELD, not an enum:
# several bits can be set at once, so there is no code table to look up.
#
# Bit names below are Table 82 of AU430028034214en-001901 pp. 719-720, which
# agrees with Table 4.3 of MG11CE02 p. 212. NOTE: Table 4.4 on MG11CE02 p. 213,
# which claims to describe 16-90 specifically, disagrees with both at bit 23
# ("Control voltage fault") and bit 28 ("Earth fault DESAT") and leaves bits
# 0/3/6/13/18 blank. Two tables in one book cannot both be right; the
# 3-document majority — and the fact that its names line up with the alarm
# numbers A47 24 V supply low and A67 Option configuration has changed — is why
# the summary table won. Confirm on hardware before trusting bits 23 and 28.
#
# 16-92 Warning Word is NOT included as history: despite the similar name its
# bit layout DIVERGES from the alarm word (Table 83, pp. 721-722) 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", 1 = "PowerCardTemp", 2 = "GroundFault", 3 = "CtrlCardTemp", 4 = "CtrlWordTimeout", 5 = "OverCurrent", 6 = "TorqueLimit", 7 = "MotorThermistorOverTemp", 8 = "MotorETR_OverTemp", 9 = "InverterOverloaded", 10 = "DCUnderVoltage", 11 = "DCOverVoltage", 12 = "ShortCircuit", 13 = "InrushFault", 14 = "MainsPhaseLoss", 15 = "AMA_NotOK", 16 = "LiveZeroError", 17 = "InternalFault", 18 = "BrakeOverload", 19 = "U_PhaseLoss", 20 = "V_PhaseLoss", 21 = "W_PhaseLoss", 22 = "FieldbusFault", 23 = "Supply24V_Low", 24 = "MainsFailure", 25 = "Supply1V8_Low", 26 = "BrakeResistor", 27 = "BrakeIGBT", 28 = "OptionChange", 29 = "DriveInitialized", 30 = "SafeStop", 31 = "MechBrakeLow" }