# Property of PMA Electrical Solutions, LLC.
#
# Schneider Electric Altivar Soft Starter ATS480, EMBEDDED Modbus RTU on the
# control block's RJ45 serial port. No option card is assumed or required.
#
# Sources — Schneider primary documentation only:
#   NNZ85539.04 (04/2025) "ATS480 Embedded Modbus RTU Manual"
#     pp. 26-30   FC03/04/06/10 frames and worked address examples
#     pp. 37-38   serial defaults, [ModbusTimeout], comm-loss response
#     pp. 42-44   profile selection and command-channel ownership
#     pp. 50-55   CMD / CMI / ETA / ETI bit maps and the state machine
#     pp. 65-70   the documented start sequence
#     pp. 71-77   base monitoring addresses, communication scanner defaults
#     pp. 84-88   comm-loss behaviour and SLF1
#   NNZ85540.02 (04/2022) "ATS480 EtherNet/IP - Modbus TCP Manual"
#     pp. 55, 89-91  cross-check: identical logic addresses on the other port
#   NNZ85515.06 (01/2026) "ATS480 User Manual"
#     pp. 250-252  error mnemonics and how each class of error clears
#
# ATS480 ONLY. NNZ85539 covers no sibling model. Its [SE8 Profile] is an
# ATS48 *compatibility* mode that runs on ATS480 addresses — it is not a claim
# about ATS48 hardware, and nothing here came from an ATS48 map.
#
# ADDRESSING. Schneider prints "Logic address: 2135 hex = 8501". That value is
# the Modbus PDU address as-is: NNZ85539 p.26 reads @9860 with "Number of
# first word = 2684 hex", and p.28 states registers are addressed starting at
# zero. So:
#     0-based protocol address = the decimal Logic address, unchanged.
# No 4xxxx offset, no 6-digit form, no group*100+index. FC04 (p.27) reads the
# SAME logic addresses and exists only in [SE8 Profile]; this profile uses the
# holding-register space (FC03/06/10).
#
# DRIVE-SIDE SETUP — without these the ATS480 ACKs writes and ignores them:
#   [Modbus Address] ADD    @6001  factory [OFF]. The unit does not answer at
#                                  all until a node address is set.
#   [Modbus Baud Rate] TBR  @6003  factory [19200 bps]
#   [Modbus Format] TFO     @6004  factory [8-E-1]
#   [Control Mode] CHCF            factory [SE8 Profile], in which the TERMINAL
#     BOARD owns command until the master writes CMD; that write moves command
#     to embedded Modbus (p.42). CMD bits 8 and 15 hand it back to the terminal.
#     In [Standard Profile] instead set [Cmd channel 1] CD1 (or CD2) to
#     [Embedded Modbus] MDB — writing CMD alone will not take command there.
#   Digital input "STOP" must be held high or the start sequence stalls (p.66).
#   Verify ownership by reading [Active Command Channel] CCC @8442 bit 3.
#
# Both [SE8 Profile] and [Standard Profile] use CMD @8501 and ETA @3201 with
# the DRIVECOM/CiA402 state machine, so these sequences are profile-agnostic.

name = "Schneider Altivar ATS480"
vendor = "Schneider Electric"
device_type = "soft_starter"
verified = false
probe_register = 3201  # ETA status word, readable whenever the port is alive

# NNZ85539 p.37: factory settings are [19200 bps] and [8-E-1]. Not 9600 8N1.
[serial]
baudrate = 19200
parity = "E"
stopbits = 1

[monitor]
# ETA, NNZ85539 pp.53-54 and NNZ85540 p.89. Bits 5, 9 and 14 are ACTIVE LOW,
# hence the _N suffix.
#
# BIT 4 POLARITY: the two manuals contradict each other. NNZ85539 p.53 labels
# it "Voltage disabled" (1 = supply absent); NNZ85540 p.89 says "Bit4 = 1 :
# Voltage enabled". NNZ85539's own worked start sequence on p.67 settles it —
# power stage absent reads ETA = 0x21, present reads 0x31, and 0x31-0x21 is
# bit 4. So 1 = supply PRESENT. The p.54 bit-mapping table is also internally
# inconsistent with its own hex column; treat p.67 as authoritative and
# re-check bit 4 on hardware before relying on it.
status_word = { address = 3201, bits = { 0 = "RDY_SWITCH_ON", 1 = "SWITCHED_ON", 2 = "OPERATION_ENABLED", 3 = "FAULT", 4 = "VOLTAGE_ENABLED", 5 = "QUICK_STOP_N", 6 = "SWITCH_ON_DISABLED", 7 = "WARNING", 9 = "FORCED_LOCAL_N", 14 = "STOP_KEY_N" } }
# CMD read back. Bits 13 and 14 are FACTORY-ASSIGNED to braked stop and
# decelerated stop (NNZ85540 p.90) — the sequences below keep the high byte
# clear so neither fires by accident.
control_word = { address = 8501, bits = { 0 = "SWITCH_ON", 1 = "ENABLE_VOLTAGE", 2 = "QUICK_STOP_N", 3 = "ENABLE_OPERATION", 7 = "FAULT_RESET", 8 = "LOCAL_SEL", 12 = "STOP_PER_TYPE", 13 = "BRAKED_STOP", 14 = "DECEL_STOP", 15 = "LOCAL_SEL" } }
# ETI, NNZ85539 p.55. Bit 4 is the real motor-energised flag; bits 13/14
# together report which channel actually holds command.
internal_state = { address = 3206, bits = { 0 = "WRITE_PARAM_AUTH", 1 = "PARAM_CONSISTENCY", 2 = "RESET_AUTH", 3 = "PREHEATING", 4 = "MOTOR_RUNNING", 5 = "BRAKING", 6 = "STEADY_STATE", 7 = "MOTOR_THERM_THRESHOLD", 9 = "ACCELERATING", 10 = "DECELERATING", 11 = "CURRENT_LIMIT_ALARM", 12 = "TORQUE_LIMIT_ALARM", 13 = "CTRL_CHANNEL_LSB", 14 = "CTRL_CHANNEL_MSB" } }
# CCC, NNZ85539 p.44 / NNZ85540 p.90. Read bit 3 to confirm Modbus has command.
active_command_channel = { address = 8442, bits = { 0 = "TERMINAL_BOARD", 2 = "DISPLAY_TERMINAL", 3 = "EMBEDDED_MODBUS", 6 = "CANOPEN", 9 = "FIELDBUS_OPTION", 15 = "SOMOVE" } }
# LCR, p.71. RMS average of the three line currents, 0.1 A per count.
motor_current = { address = 3204, scale = 0.1, unit = "A" }
# THR, p.71. 100% = nominal thermal state at [Motor Nom Current] IN, so this
# is relative to a CONFIGURED value, not an absolute.
motor_thermal_state = { address = 9630, unit = "%" }
# RTH, p.71. 32-bit. Word order follows [Term word order] TWO @6006, factory
# [ON] = high word first, which is what word_order defaults to here.
motor_run_time = { address = 3244, words = 2, unit = "s" }
# OCK, p.71. 32-bit, same word-order caveat.
energy_consumed = { address = 10652, words = 2, unit = "kWh" }
# IL1R, p.72. NNZ85540 p.87 names the same bits DI1..DI4; the serial manual
# names them by their factory function.
logic_inputs = { address = 5202, bits = { 0 = "STOP", 1 = "RUN", 2 = "DI3", 3 = "DI4" } }

# DRIVECOM/CiA402 sequences, NNZ85539 p.51 (bit mapping of the control word)
# and pp.66-68 (the start sequence, step by step).
#
# No speed reference exists on a soft starter, so speed_register, speed_scale
# and max_ref are deliberately absent — and so is run_rev, since a soft
# starter has no direction bit at all.
[control]
command_register = 8501
step_delay = 0.05
# "Shutdown" (transition 8 from 5 - Operation enabled) -> 3 - Ready to switch
# on. The ramp it uses is whatever [Type of stop] STY is set to.
stop = [0x0006]
# Shutdown -> Switch on -> Enable operation, exactly the three transitions of
# pp.66-68. The motor starts on 0x000F.
run_fwd = [0x0006, 0x0007, 0x000F]
# Bit 7 is a RISING EDGE (p.51), so the low->high->low framing is required.
# The manual's own example value is 0x0080; bits 0-3 are "X" for this
# transition and the documented end state is 2 - Switch on disabled, which
# 0x0000 is consistent with. Bit 3 (Enable operation) is clear in every step,
# so nothing in this sequence is a run command.
reset = [0x0000, 0x0080, 0x0000]

# NNZ85539 pp.78, 84-85: monitoring of a channel begins the moment CMD is
# first written to it. [ModbusTimeout] TTO @6005 is factory 5.0 s (range
# 0.1-30.0 s, unit 0.1 s); on expiry [Modbus Error Resp] SLL @7010, factory
# [Freewheel Stop], trips [Mdb Com Interrupt] SLF1 and freewheels the motor.
# A 50 ms keepalive sits below the shortest 0.1 s timeout. SLF1 needs a manual
# reset once the cause is gone (NNZ85515 p.250) — it does not self-clear.
[control.watchdog]
interval_ms = 50
fault = "SLF1 Mdb Com Interrupt"

# ETA bit 2 = Operation enabled = running (NNZ85539 p.53).
[running_check]
register = 3201
bit = 2

# ERRD [CiA402 Error Code], @8606. Confirmed twice by Schneider: NNZ85539
# pp.75-76 and NNZ85540 p.55 both ship it as communication-scanner input 4.
#
# [faults.codes] IS DELIBERATELY EMPTY. Neither ungated manual publishes the
# numeric enumeration; that lives in "ATS480 Communication Parameter
# Addresses" NNZ85544, which se.com serves only behind an account. Filling
# this table from memory or a third-party page is how abb_acs580 got corrupted.
# NNZ85515 pp.251-270 lists the mnemonics (OCF, OHF, OLF, PHF1-PHF4, SLF1,
# USF, ...) but maps none of them to a register value.
[faults]
register = 8606

[connection]
summary = "Connect to the ATS480 embedded Modbus interface; no fieldbus option card is required for the documented serial path."
warnings = ["Lock out the drive/starter before opening covers or moving switches.", "Keep communications cable at least 30 cm from line and motor wiring.", "Prove read-only communication with the motor inhibited before enabling network control."]

[[connection.methods]]
id = "vp12s_rs485"
title = "Modbus VP12S RJ45"
transport = "serial"
hardware = "built_in"
port = "Modbus RTU VP12S communication port"
connector = "RJ45; pin 4 D1, pin 5 D0, pin 8 Common; pin 7 is vendor peripheral power"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "VW3A8306D30 RJ45-to-stripped Modbus lead or equivalently pinned shielded twisted-pair cable"
parts = ["Isolated USB-to-RS-485 adapter", "Shielded twisted pair plus common conductor", "End termination for a multidrop bus"]
steps = ["Lock out the equipment and verify it is de-energized.", "Locate Modbus RTU VP12S communication port.", "Wire D1, D0 and Common exactly as shown below; leave the peripheral-power pin unused.", "Route the communications cable at least 30 cm from power conductors and terminate only the two physical ends.", "Restore control power with the motor inhibited and verify a read before enabling control."]
setup = ["Set ADD @6001 to 1..247 (factory OFF does not answer).", "Match 19200 baud and 8-E-1.", "In Standard Profile set Cd1 or Cd2 to Embedded Modbus", " in SE8 Profile the first CMD write takes ownership.", "Keep the hardwired STOP input high."]
warnings = ["Do not connect adapter power to the vendor peripheral-power pin.", "Connect only the documented data and Common conductors."]
source = "Schneider NNZ85539.04 (04/2025), pp. 17-20, 37-44 and 65-70."

[[connection.methods.wiring]]
adapter = "D1 / B / +"
device = "RJ45 pin 4 — D1"
signal = "RS-485 D1"

[[connection.methods.wiring]]
adapter = "D0 / A / -"
device = "RJ45 pin 5 — D0"
signal = "RS-485 D0"

[[connection.methods.wiring]]
adapter = "COM / signal common"
device = "RJ45 pin 8 — Common"
signal = "Signal reference"

[[connection.methods]]
id = "hmi_rs485"
title = "HMI RJ45 used as external Modbus port"
transport = "serial"
hardware = "built_in"
port = "Modbus RTU HMI port"
connector = "RJ45; pin 4 D1, pin 5 D0, pin 8 Common; pin 7 is vendor peripheral power"
adapter = "Isolated USB-to-RS-485 adapter"
cable = "VW3A8306D30 RJ45-to-stripped Modbus lead or equivalently pinned shielded twisted-pair cable"
parts = ["Isolated USB-to-RS-485 adapter", "Shielded twisted pair plus common conductor", "End termination for a multidrop bus"]
steps = ["Lock out the equipment and verify it is de-energized.", "Locate Modbus RTU HMI port.", "Wire D1, D0 and Common exactly as shown below; leave the peripheral-power pin unused.", "Route the communications cable at least 30 cm from power conductors and terminate only the two physical ends.", "Restore control power with the motor inhibited and verify a read before enabling control."]
setup = ["Set ADD @6001 to 1..247 (factory OFF does not answer).", "Match 19200 baud and 8-E-1.", "In Standard Profile set Cd1 or Cd2 to Embedded Modbus", " in SE8 Profile the first CMD write takes ownership.", "Keep the hardwired STOP input high."]
warnings = ["Do not connect adapter power to the vendor peripheral-power pin.", "Connect only the documented data and Common conductors."]
source = "Schneider NNZ85539.04 (04/2025), pp. 17-20, 37-44 and 65-70."

[[connection.methods.wiring]]
adapter = "D1 / B / +"
device = "RJ45 pin 4 — D1"
signal = "RS-485 D1"

[[connection.methods.wiring]]
adapter = "D0 / A / -"
device = "RJ45 pin 5 — D0"
signal = "RS-485 D0"

[[connection.methods.wiring]]
adapter = "COM / signal common"
device = "RJ45 pin 8 — Common"
signal = "Signal reference"

[[connection.methods]]
id = "vw3a3720_modbus_tcp"
title = "VW3A3720 Modbus TCP option"
transport = "tcp"
hardware = "option"
port = "VW3A3720 Ethernet module, RJ45 port A or B"
connector = "RJ45 Ethernet, dual switched ports"
adapter = "Computer Ethernet interface or Ethernet switch"
cable = "Cat 5e or better straight-through shielded Ethernet cable; no crossover cable"
parts = ["Schneider VW3A3720 Ethernet module V2.1 or later", "Cat 5e or better Ethernet cable"]
steps = ["Lock out the ATS480 and install the VW3A3720 option per its installation instructions.", "Connect the Ethernet cable to module port A or B and the computer/switch.", "Restore control power with the motor inhibited and confirm link LEDs.", "Set or discover the module IP address, then verify a Modbus TCP read on TCP port 502 before enabling control."]
setup = ["Confirm the ATS480 has a compatible VW3A3720 V2.1-or-later module.", "Configure the module IP addressing.", "Select the option module as command channel and configure the communications-loss response.", "Keep the hardwired STOP input high for a run command."]
warnings = ["Do not connect an RS-485 adapter to these Ethernet ports.", "This path requires the option module; it is not the built-in VP12S serial port."]
source = "Schneider NNZ85540.02, pp. 17, 72-75 and Modbus TCP setup chapter."