HY_GT_VFD(1)

📦
version 2.9.4 · 4 versions
, in ubuntu resolute, ubuntu stonking

💖 hy_gt_vfd — the LinuxCNC manual page, bestie edition 💖

okay so this is hy_gt_vfd(1), a page from the LinuxCNC Documentation manual, and it's about making your spindle go brrr on purpose. sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

hy_gt_vfd — it's a HAL non-realtime component for Huanyang GT-series VFDs. that's it. that's the whole name section. iconic brevity. 👑

✨ SYNOPSIS ✨

hy_gt_vfd [OPTIONS]

✨ DESCRIPTION ✨

so basically hy_gt_vfd is the little matchmaker between a Huanyang GT-series VFD and LinuxCNC's HAL. the VFD shows up connected over RS-485 serial to your LinuxCNC computer, and this component handles the talking. 💬🦋

🔧 HARDWARE SETUP 🔧

ngl this is the part where you might have to get the soldering iron out. 😭 at least some Huanyang GT VFDs have to be physically modified to enable Modbus communication. like, hardware surgery. on purpose. fr fr.

the circuit board location marked "SW1" is identified in the manual as "Switch of terminal resistor for RS485 communication". okay but on the only VFD I have experience with, the circuit board contained no switch at that location — instead it held a pair of crossed jumper wires (top-left pad connected to bottom-right pad, top-right to bottom-left). in this configuration, no Modbus communication is possible. 💀

we had to desolder the two crossed jumper wires and re-solder them parallel to each other (top-left to bottom-left, top-right to bottom-right). and then it worked. slay. 💅

⚙️ FIRMWARE SETUP ⚙️

the Huanyang GT VFD must be configured via the faceplate to talk Modbus with LinuxCNC. go consult the Operation section of the Huanyang GT-series Inverter Manual for the deets. 📖 then set these parameters:

  • P0.01 = 2 — sets Run Command Source to Modbus serial port.
  • P0.03 — sets Maximum Frequency to the maximum frequency you want the VFD to output, in Hz.
  • P0.04 — sets Upper Frequency Limit to the maximum frequency you want the VFD to output, in Hz. this should be the same as the value in P0.03.
  • P0.05 — sets Lower Frequency Limit to the minimum frequency you want the VFD to output, in Hz.
  • P0.07 = 7 — sets Frequency A Command Source to Modbus serial port.
  • P2.01 = ??? — sets Motor Rated Power to the motor's power rating in kW.
  • P2.02 = ??? — sets Motor Rated Frequency to the motor's max frequency in Hz.
  • P2.03 = ??? — sets Motor Rated Speed to the motor's speed in RPM at its rated maximum frequency.
  • P2.04 = ??? — sets Motor Rated Voltage to the motor's maximum voltage, in Volts.
  • P2.05 = ??? — sets Motor Rated Current to the motor's maximum current, in Amps.
  • PC.00 = 1 — sets Local Address to 1. this matches the default in the hy_gt_vfd driver, so change it if your setup has special needs.
  • PC.01 = 5 — sets baud rate selection to 5 (38400 bps). this matches the default in the hy_gt_vfd driver, so change it if your setup has special needs.

the full baud menu, for the record:

  • 0 = 1200
  • 1 = 2400
  • 2 = 4800
  • 3 = 9600
  • 4 = 19200
  • 5 = 38400
  • PC.02 = 0 — sets Data Format (8n1 RTU). this matches the default in the hy_gt_vfd driver, so change it if your setup has special needs.
  • PC.03 = 1 — sets Communication Delay Time to 1 ms. the hy_gt_vfd driver expects this. 👀

🌸 OPTIONS 🌸

  • -b, --bits N — (default 8) for Modbus communication. sets number of data bits to N. N must be between 5 and 8 inclusive.
  • -p, --parity [Even,Odd,None] — (default None) for Modbus communication. sets serial parity to Even, Odd, or None.
  • -r, --rate N — (default 38400) for Modbus communication. sets baud rate to N. it is an error if the rate is not one of the following: 1200, 2400, 4800, 9600, 19200, 38400.
  • -s, --stopbits [1,2] — (default 1) for Modbus communication. sets serial stop bits to 1 or 2.
  • -t, --target N — (default 1) for Modbus communication. sets Modbus target (slave) number. this must match the device number you set on the Huanyang GT VFD. 👯
  • -d, --device PATH — (default /dev/ttyS0) for Modbus communication. sets the name of the serial device node to use.
  • -v, --verbose — turn on verbose mode. for when you want ✨lore✨.
  • -S, --motor-max-speed RPM — the motor's max speed in RPM. this must match the motor speed value configured in VFD register P2.03.
  • -F, --max-frequency HZ — this is the maximum output frequency of the VFD in Hz. it should correspond to the motor's rated max frequency, and to the maximum and upper limit output frequency configured in VFD register P0.03 and P0.04.
  • -f, --min-frequency HZ — this is the minimum output frequency of the VFD in Hz. it should correspond to the minimum output frequency configured in VFD register P0.05.

📌 PINS 📌

  • hy_gt_vfd.period (float, in) — the period for the driver's update cycle, in seconds. this is how frequently the driver will wake up, check its HAL pins, and communicate with the VFD. must be between 0.001 and 2.000 seconds. default: 0.1 seconds.
  • hy_gt_vfd.speed-cmd (float, in) — the requested motor speed, in RPM.
  • hy_gt_vfd.speed-fb (float, out) — the motor's current speed, in RPM, reported by the VFD.
  • hy_gt_vfd.at-speed (bit, out) — True when the drive is on and at the commanded speed (within 2%), False otherwise.
  • hy_gt_vfd.freq-cmd (float, out) — the requested output frequency, in Hz. this is set from the .speed-cmd value, and is just shown for debugging purposes.
  • hy_gt_vfd.freq-fb (float, out) — the current output frequency of the VFD, in Hz. this is reported from the VFD to the driver.
  • hy_gt_vfd.spindle-on (bit, in) — set this pin True to command the spindle on, at the speed requested on the .speed-cmd pin. set this pin False to command the spindle off.
  • hy_gt_vfd.output-voltage (float, out) — the voltage that the VFD is current providing to the motor, in Volts.
  • hy_gt_vfd.output-current (float, out) — the current that the motor is currently drawing from the VFD, in Ampères.
  • hy_gt_vfd.output-power (float, out) — the power that the motor is currently drawing from the VFD, in Watts.
  • hy_gt_vfd.dc-bus-volts (float, out) — the current voltage of the VFD's internal DC power supply, in Volts.
  • hy_gt_vfd.modbus-errors (u32, out) — a count of the number of modbus communication errors between the driver and the VFD. the driver is resilient against communication errors, but a large or growing number here indicates a problem that should be investigated. 🚨
  • hy_gt_vfd.input-terminal (float, out) — the VFD's input terminal register.
  • hy_gt_vfd.output-terminal (float, out) — the VFD's output terminal register.
  • hy_gt_vfd.AI1 (float, out) — the VFD's AI1 register.
  • hy_gt_vfd.AI2 (float, out) — the VFD's AI2 register.
  • hy_gt_vfd.HDI-frequency (float, out) — the VFD's HDI-frequency register.
  • hy_gt_vfd.external-counter (float, out) — the VFD's external counter register.
  • hy_gt_vfd.fault-info (float, out) — the VFD's fault info register.

😭 ISSUES 😭

heads up bestie, this is the "why is my spindle lying to me" section.

the VFD produces the output frequency that it sends to the motor by adding a manually specified offset to the frequency command it gets over modbus. sneaky. 🙈

the manual offset is controlled by pressing the Up/Down arrows on the faceplate while the VFD is turning the motor.

so if you command a speed on the .speed-cmd pin and get a different speed reported on the .speed-fb pin, here's the vibe check, in order:

  1. first verify that the VFD registers listed in the FIRMWARE SETUP section above and the driver's command-line arguments all agree with the info on the motor's name plate. like, actually check. 🔍
  2. if you still aren't getting the speed you expect, zero the VFD's frequency offset by starting the motor running, then pressing the Up/Down buttons to zero the offset.

👑 AUTHOR 👑

Sebastian Kuzminsky

📜 LICENSE 📜

GPL-2.0+

okay that's the whole page, you ate it, you're a LinuxCNC main character now. 🌈✨ this was page HY_GT_VFD(1) from the LinuxCNC docs, dated 03/17/2026 — love that for us, periodt. 💜🦋🎀

📦 where this page comes from