4.6 Connect Spindles

• The section name is the type. Each spindle is a separate block at zero indent in the YAML — there is no spindles: group around them. Sections A–H below give a working block for each.
• G-code has no laser or VFD commands, so FluidNC treats every one of these as a spindle: M3 / M4 run it, M5 stops it, S sets the level.
• M4 is only accepted when the section has a direction, forward or reverse pin. Without one, only M3 and M5 mean anything.

• GPIO.4 → driver PWM / speed input, GND → driver signal ground, both on the Outputs (5v) header.
• 5 kHz PWM. Check with a multimeter first: S10000 ≈ 5 V, S5000 ≈ 2.5 V, M5 = 0 V.
• GPIO.4 is also wired to one MOSFET channel — using it here means it is no longer free for coolant or a relay.

pwm:
  pwm_hz: 5000
  output_pin: gpio.4
  enable_pin: NO_PIN
  disable_with_s0: false
  s0_with_disable: true
  tool_num: 1
  speed_map: 0=0.000% 10000=100.000%
  off_on_alarm: false

Figure B1 — a laser module has three leads. PWM/TTL+ and GND go to the Outputs (5v) header; 12V+/VCC comes from the module's own supply and never touches the controller — but that supply's negative must sit on the same ground as the controller, or the TTL signal has no return path. The test YAML puts the laser on GPIO.12. Click the image to view it full size.

• GPIO.12 → laser module TTL / PWM input, GND → its signal ground, on the same Outputs (5v) header.
• Scale is 0–255, not 0–10000 — full power is S255.
• The laser only fires while moving. Set power with M3 S255, then send a move such as G1 F1000.
• The on-board relay can switch the laser module's power supply if you want a hard cut-off — see E.

• A laser fires only in G1, G2 and G3 moves — never during G0, jogging or homing. If you need output in those modes, use a pwm section instead of Laser.
• Keep off_on_alarm: true so a triggered alarm cannot leave the laser burning.
• The last entry of speed_map is the maximum S your CAM software should emit — 255 here.

Laser:
  pwm_hz: 5000
  output_pin: gpio.12
  enable_pin: NO_PIN
  disable_with_s0: false
  s0_with_disable: true
  tool_num: 2
  speed_map: 0=0.000% 255=100.000%
  off_on_alarm: true

Figure C1 — the V4.96 Pro carries its own relay, so the enable contact costs no extra hardware: COMMON goes to the drive's COM and Normal Open to X3. The optocoupler pair still does forward and reverse, and the analog pair still does speed. If your drive needs no enable contact, leave the relay out and set enable_pin: NO_PIN. Click the image to view it full size.

• OPT-Common is not a ground. OPT-io.15 with OPT-Common, and OPT-io.14 with OPT-Common, are the two ends of an optocoupler — think of each pair as a switch. Its common end belongs on the drive's digital common (COM / DCM). The separate GND pin on the same terminal block is the return for the 0–10 V signal only, and the two are wired to different places on the drive.
• The two channels share one common — they are a pair of switches with a common pole, not two independent floating contacts, so both must return to the same drive terminal.
• The optocoupler output passes no voltage of its own to the drive; it only completes the drive's own input circuit. It does conduct in one direction only — see C2 if your drive uses source-type (PNP) inputs.
• Set the drive to take its run command from the terminals and its speed reference from the analog input, not from the keypad. Parameter numbers differ by brand — look them up in the drive's own manual.
• The 0–10 V output is factory-calibrated to 10 V — only touch the trimmer if your drive needs a different full scale, and watch a multimeter while you do.
• What the G-code does: M3 S12000 closes Fwd and sets the analog voltage; M4 releases Fwd and closes Rev; M5 releases both contacts and, with s0_with_disable: true, drops the analog output to the S0 value at the same time.
• The relay contact is a dry contact too, and an independent one — it has its own NC / COMMON / NO terminals and shares nothing with the optocoupler pair.
• Two settings make the relay follow enable_pin: set the GPIO.26 function-selection jumper to relay output, and give gpio.26 to the 10V section. It cannot also be the relay: spindle at the same time — see E.
• These optocoupler pins are shared with RS485. OPT-io.15 and OPT-io.14 are the same GPIOs the Modbus port uses (D). Use one path or the other, or drive the direction contacts from relays instead (C2).

10V:
  forward_pin: gpio.15         # OPT-io.15 Out1/Fwd - X1   (also RS485 TX - pick one)
  reverse_pin: gpio.14         # OPT-io.14 Out2/Rev - X2   (also RS485 direction - pick one)
  output_pin: gpio.13          # 0-10V - VI, GND - analog common
  enable_pin: gpio.26          # on-board relay COMMON-NO across COM and X3
  direction_pin: NO_PIN
  pwm_hz: 5000
  disable_with_s0: false
  s0_with_disable: true
  spinup_ms: 0
  spindown_ms: 0
  tool_num: 3
  speed_map: 0=0.000% 1000=0.000% 24000=100.000%
  off_on_alarm: false

• The drive is set for three-wire control, where the STOP input must be held closed before it will start at all.
• A multi-function input is assigned to run-enable or external stop and has to be closed.
• The drive's digital inputs are source (PNP) type. An optocoupler output conducts in one direction only; a relay contact has no polarity and works either way.
• You need contacts with independent commons — the two optocoupler channels share one.
• You want the RS485 port free — relay contacts leave GPIO.15 and GPIO.14 to the Modbus path.
• You want the on-board relay for something else, such as switching the spindle's mains supply.

Figure C2 — three relay contacts do forward, reverse and start/stop, driven from I2SO.23 / I2SO.21 / I2SO.20 plus GND. Those I2SO signals only reach the green terminal when the jumper caps are fitted in that driver slot — a driver module must not be plugged in there. The 0–10 V pair is wired exactly as in C1. Click the image to view it full size.

• The three COM terminals are separate. The board does not join them internally — the drawing bridges them with a short external link so all three contacts return to the drive's COM.
• Each channel is a NC / COM / NO changeover contact. These connections use COM–NO, so a de-energised board leaves the drive stopped.
• The IsoSwitch V4 runs from its own 4.5–40 V DC supply (24 V by default), takes 5 V or 3.3 V logic on S1 / S2 / S3, and its INPUT GND must be tied to the controller GND. Trigger jumpers JP4→S1, JP5→S2, JP6→S3 — full detail in 4.3 Connect External Relay and the IsoSwitch V4 reference.
• Fit the jumper caps, not a driver. The I2SO outputs are routed to the green terminal through that driver slot — as the drawing says, insert the jumper caps and leave the slot free of a driver module.
• In the test YAML I2SO.23 and I2SO.21 are the flood and mist coolant outputs — taking them for the VFD means giving up M7 / M8. Any spare output works; the pin names live in your YAML, not in the hardware.
• You can mix the drawings. Keep Fwd and Rev on the optocouplers as in C1 and use the on-board relay for the enable contact — that is exactly what Figure C1 shows.

10V:
  forward_pin: I2SO.20         # K3 - X1 (FWD)
  reverse_pin: I2SO.21         # K2 - X2 (REV)
  enable_pin: I2SO.23          # K1 - X3 (STOP / enable)
  output_pin: gpio.13          # 0-10V - VI, GND - analog common
  direction_pin: NO_PIN
  pwm_hz: 5000
  disable_with_s0: false
  s0_with_disable: true
  spinup_ms: 0
  spindown_ms: 0
  tool_num: 3
  speed_map: 0=0.000% 1000=0.000% 24000=100.000%
  off_on_alarm: false

• FluidNC drives levels, never pulses. A contact closes on M3 / M4 and opens on M5 — which is exactly what two-wire control expects, so start there if your drive offers it.
• Three-wire needs the enable contact. Releasing the start input does not stop a latched drive; only opening its STOP input does, and that is the contact enable_pin holds.

• A → VFD A, B → VFD B. Two wires only. If it does not communicate, swap A and B — a reversed pair does no damage.
• Internally this is UART1 — TX GPIO.15, RX GPIO.16, direction GPIO.14.
• This is the same pin pair as the 0–10 V Fwd/Rev optocouplers (C): OPT-io.15 and OPT-io.14 are those same GPIOs, so a machine uses either the Modbus path or the optocoupler direction contacts — not both.
• The test YAML ships a YL620 profile as a worked example; match baud, format and modbus_id to your own drive.
• FluidNC carries named profiles for a range of drives — Huanyang, YL620, H100, H2A, the P2 series, NowForever, Danfoss VLT 2800, Siemens V20 — plus the generic ModbusVFD. Use the section your drive needs; see the Modbus VFD page.

uart1:
  txd_pin: gpio.15
  rxd_pin: gpio.16
  rts_pin: gpio.14
  baud: 9600
  mode: 8N1

YL620:
  uart_num: 1
  modbus_id: 1
  tool_num: 4
  speed_map: 0=0% 0=25% 6000=25% 24000=100%
  off_on_alarm: false

• The V4.96 Pro has a relay on the board — a single NC / COMMON / NO changeover contact driven by GPIO.26. Nothing external is needed for an on/off spindle, a mains contactor coil, a laser power supply or a VFD enable contact.
• Set the GPIO.26 function-selection jumper to relay output first. The same pin can instead be a general-purpose input, and the jumper decides which — see the pinout and jumper pages.
• One job at a time. In the test YAML the relay is its own on/off spindle (relay:, tool_num: 0, tested with M6 T0 then M3 S255). If you would rather use it as the VFD enable contact of C1, delete that relay: section and put enable_pin: gpio.26 in the 10V section instead — FluidNC refuses a configuration that names the same pin twice.
• Never drive a relay with a PWM signal — the coil chatters and the contacts fail. The relay spindle type switches cleanly: any S above 0 turns it fully on.
• For more channels, add a relay module such as the PiBot IsoSwitch V4 and feed it from spare 5 V, I2SO or GPIO outputs — see 4.3 Connect External Relay.
• Mains switching stays on the contact side, in a rated enclosure, with the contact chosen so that a power loss leaves the spindle off. Give spinup_ms a real value — a router needs seconds to reach speed.

relay:
  output_pin: gpio.26          # on-board relay - set the GPIO.26 jumper to relay output
  direction_pin: NO_PIN
  enable_pin: NO_PIN
  disable_with_s0: false
  s0_with_disable: true
  spinup_ms: 3000              # let the spindle reach speed before cutting
  spindown_ms: 3000
  tool_num: 0
  off_on_alarm: true

• For a brushless motor driven through an ESC (the drone/RC kind, used as a light high-speed spindle), or for a hobby servo such as a pen lift.
• The signal is RC-style: a pulse of roughly 1–2 ms inside a 20 ms period, so pwm_hz: 50. min_pulse_us and max_pulse_us come from your ESC's own documentation, and speed_map is then a plain percentage of that span — no duty-cycle arithmetic.
• It needs a raw PWM pin: GPIO.4 or GPIO.12 on the Outputs (5v) header. Do not use the 0–10 V terminal — that output is a filtered analog voltage, not a pulse train.
• Three wires: signal, ground and power. The signal goes to GPIO.4 or GPIO.12, the ground to that header's GND, and the power to a 5 V source on the board for a small servo, or its own supply for an ESC and motor.
• An ESC that expects an arming sequence at power-up can be walked through it from G-code — M3 S0 for minimum throttle, M3 S1000 for full, M3 S500 for mid.
• The same section drives a pen-lift servo: M3 S1000 down, M5 up. FluidNC also has an RC servo axis feature if you want it on an axis instead.

Figure F1 — the wiring path for a 5 V hobby servo: signal (white) to a PWM pin on the Outputs (5v) header, black to that header's GND, and red to a +5V pin on the board. The servo in the photograph is there to show the three leads, not as a recommended size — see the note below. Click the image to view it full size.

BESC:
  output_pin: gpio.4           # raw PWM pin - not the 0-10V terminal
  pwm_hz: 50                   # 20 ms period
  min_pulse_us: 1000           # ESC "off" pulse - check its datasheet
  max_pulse_us: 2000           # ESC full-power pulse
  tool_num: 5
  speed_map: 0=0% 1000=100%

• Like a PWM spindle, but with one PWM output per direction. While one is toggling the other is held low, and M5 turns both off.
• GPIO.4 and GPIO.12 are the two PWM-capable 5 V outputs — the natural pair for output_cw_pin and output_ccw_pin. They drive the inputs of an H-bridge module, which needs its own supply.
• Neither the MOSFET channels nor the on-board relay can do this. The MOSFETs are low-side switches and the relay is a single changeover contact — they can turn a DC load on and off, but they cannot reverse it.
• There is no direction_pin in this section — the two output pins carry the direction.

HBridge:
  pwm_hz: 5000
  output_cw_pin: gpio.4
  output_ccw_pin: gpio.12
  enable_pin: NO_PIN
  disable_with_s0: false
  spinup_ms: 1000
  spindown_ms: 1000
  tool_num: 6
  speed_map: 0=0.000% 10000=100.000%
  off_on_alarm: false

• This section has no speed output. enable_pin fires the torch, and arc_ok_pin is an input that confirms the arc transferred.
• If arc_ok_pin goes inactive while cutting, motion is aborted with an alarm. arc_wait_ms is how long FluidNC waits for the confirmation before giving up.
• On the V4.96 Pro: fire the torch through the on-board relay or an external contact (E), and take arc OK into one of the optocoupler-isolated inputs you are not using for limits. Add :low if the signal is active-low.
• Plasma is a development feature in FluidNC — read its own plasma page for the hardware notes before wiring a torch.

Plasma:
  enable_pin: gpio.26          # torch start through the on-board relay
  arc_ok_pin: gpio.39:low      # an optocoupler input you are not using for limits
  arc_wait_ms: 1000
  tool_num: 7
  off_on_alarm: true

• Define as many as your hardware supports. Each is its own section and they act independently — a machine can carry a router, a laser and a VFD at once.
• Every spindle needs its own pins. The config parser rejects a pin used twice, and FluidNC has to be able to control each spindle separately during tool changes and alarms.
• Tool numbers decide which spindle is active. tool_num is the first tool of that spindle's range, and the range runs until the next spindle's tool_num. One of them must be 0 so every tool number is valid — and that is the spindle you get at power-on, before any M6.
• Keep T and M6 on the same line, the way the bench pages write M6 T2. A T on its own only sets the next tool; the change happens on M6. Send $G to read back the current tool and modal state.
• Send M5 before switching, so the previous output is left at zero.
• Use shielded cable for the analog and RS485 runs, and keep them away from motor and limit-switch wiring. A VFD is the noisiest device on the machine.

• A spindle is not the only way to drive an RC servo or a solenoid. FluidNC can also make one an axis, so G0 Z5 moves it — useful for a pen lift or a tool cover.

z:
  steps_per_mm: 100.000
  max_rate_mm_per_min: 5000.000
  acceleration_mm_per_sec2: 100.000
  max_travel_mm: 5.000
  soft_limits: true
  homing:
    cycle: 1
    positive_direction: true
    mpos_mm: 5.000

  motor0:
    rc_servo:
      pwm_hz: 50
      output_pin: gpio.27
      min_pulse_us: 1000
      max_pulse_us: 2000

• To reverse the travel, swap the two pulse widths:

rc_servo:
  pwm_hz: 60
  output_pin: gpio.27
  min_pulse_us: 2000
  max_pulse_us: 1000