# LinuxCNC HAL Configuration for Vevor D100 VFD via mb2hal

This guide explains how to connect the HAL pins of LinuxCNC to the `mb2hal` component configured in [vfd_d100.ini](file:///home/bartool/local_projects/linuxcnc-modbus/vfd_d100.ini).

## 1. Required Components

To achieve correct speed scaling, rotation control, feedback conversion, and "at-speed" detection, we will load the following standard HAL components:
*   **`scale`**: Used twice.
    1. `spindle_speed_scale`: Converts commanded RPM (e.g., 24000 RPM) to Modbus frequency units (tenths of Hz, 400.0 Hz = 4000).
    2. `spindle_feedback_scale`: Converts actual speed from RPM (from VFD metrics) to RPS (Revolutions Per Second) required by LinuxCNC.
*   **`mux2`**: Used twice.
    1. `spindle_dir_mux`: Selects between `2.0` (Forward) and `4.0` (Reverse).
    2. `spindle_run_mux`: Selects between `8.0` (Stop) and the output of `spindle_dir_mux`.
*   **`near`**: Compares commanded speed and actual speed to assert `spindle.0.at-speed`.

---

## 2. Speed Scaling Calculations

The VFD expects the given frequency in tenths of Hz (e.g., $400.0 \text{ Hz} = 4000$ in register `0201H`).
The motor has a maximum speed of $24000 \text{ RPM}$ at $400 \text{ Hz}$.

*   **Commanded Speed Gain:**
    $$Gain = \frac{4000 \text{ (Modbus Units)}}{24000 \text{ (RPM)}} = \frac{1}{6} \approx 0.16666667$$
    
*   **Feedback Speed Gain (RPM to RPS):**
    $$Gain = \frac{1}{60} \approx 0.01666667$$

---

## 3. HAL Configuration Snippet

Add the following lines to your main `.hal` file (e.g. `custom.hal` or `postgui.hal` depending on your setup):

```hal
# =====================================================================
# Vevor D100 VFD Modbus (mb2hal) Integration
# =====================================================================

# Load the mb2hal component
loadusr -Wn vfd mb2hal config=vfd_d100.ini

# Load helper components
loadrt scale names=spindle_speed_scale,spindle_feedback_scale
loadrt mux2 names=spindle_dir_mux,spindle_run_mux
loadrt near names=spindle_at_speed_near

# Add helper components to the servo thread
addf spindle_speed_scale servo-thread
addf spindle_feedback_scale servo-thread
addf spindle_dir_mux servo-thread
addf spindle_run_mux servo-thread
addf spindle_at_speed_near servo-thread

# =====================================================================
# 1. Spindle Run & Direction Logic
# =====================================================================

# Direction Mux Input Values: 2.0 = Forward Run, 4.0 = Reverse Run
setp spindle_dir_mux.in0 2.0
setp spindle_dir_mux.in1 4.0

# Run Mux Input Values: 8.0 = Stop, in1 = value from direction mux
setp spindle_run_mux.in0 8.0

# Connect selection signals
net spindle-rev-sig      spindle.0.reverse        => spindle_dir_mux.sel
net spindle-dir-cmd      spindle_dir_mux.out      => spindle_run_mux.in1

net spindle-on-sig       spindle.0.on             => spindle_run_mux.sel
net spindle-run-cmd      spindle_run_mux.out      => vfd.control.00.float

# =====================================================================
# 2. Spindle Commanded Speed Scaling
# =====================================================================

# Gain = 4000 / 24000 = 0.16666667
setp spindle_speed_scale.gain 0.16666667
setp spindle_speed_scale.offset 0.0

# Connect signals
net spindle-speed-cmd    spindle.0.speed-out-abs  => spindle_speed_scale.in
net spindle-speed-scaled spindle_speed_scale.out  => vfd.speed.00.float

# =====================================================================
# 3. Spindle Speed Feedback (RPM to RPS)
# =====================================================================

# Gain = 1 / 60 = 0.01666667 (converts RPM to RPS)
setp spindle_feedback_scale.gain 0.01666667
setp spindle_feedback_scale.offset 0.0

# Connect signals
net spindle-rpm-feedback vfd.metrics.rpm.float    => spindle_feedback_scale.in
net spindle-rps-feedback spindle_feedback_scale.out => spindle.0.speed-in

# =====================================================================
# 4. Spindle "At Speed" Detection
# =====================================================================

# Configure allowable difference (e.g., within 5% or 300 RPM)
setp spindle_at_speed_near.difference 300.0
# We want the speed to be compared on the absolute commanded speed (RPM)
net spindle-speed-cmd     => spindle_at_speed_near.in1
net spindle-rpm-feedback  => spindle_at_speed_near.in2
net spindle-at-speed      spindle_at_speed_near.out => spindle.0.at-speed
```

---

## 4. Troubleshooting & Tuning Tips

> [!TIP]
> **Modbus Communication Stability**
> If you experience CRC errors or timeouts when the spindle motor starts spinning, it is likely due to Electro-Magnetic Interference (EMI).
> * Ensure your RS485 twisted-pair cable is shielded, and the shield is grounded **only at one end** (usually at the VFD or controller side, not both).
> * Add a $120\ \Omega$ termination resistor across the RX+/TX+ and RX-/TX- terminals at the VFD if it's at the end of the bus.
> * If the VFD takes too long to process requests, you can increase `SERIAL_DELAY_MS` in [vfd_d100.ini](file:///home/bartool/local_projects/linuxcnc-modbus/vfd_d100.ini) to `70` or `100`.