The USB Handwheel is designed to interface with LinuxCNC using a compiled software module that allows LinuxCNC to communicate with the handwheel. 

Features

• Uses common precision wheel encoder
• Supports 3 or 4 axis
• Powered over USB, uses <50mA
• LCD display shows current position data
• Two knobs allow easy axis and speed selection
• Enclosure is easy to print or machine
• Unplugging or reconnection will not cause machine movement

Installation

Setup consists of three steps.  First, download the module from this link:

usb-handwheel.so

Make sure the file is executable:

sudo chmod +x usb-handwheel.so

Then copy that file to the LinuxCNC modules folder:

sudo cp usb-handwheel.so /usr/lib/linuxcnc/modules

Next, download the hal file from this link:

usb-handwheel.hal

Copy the hal file to the same folder as your machine's main HAL file.  Typically, this is in the home/cnc/linuxcnc/configs/_machineName_ folder.

Last, include the new HAL file into the machine's HAL file.  Open your machines HAL file and add the following line:

source usb-handwheel.hal

Usage

Simply plug the handwheel into the Pi or computer using a USB-C to USB (A Male) cable.  The handwheel will be powered by the USB.  On power-up, the green light on the front should turn on for 1 second.  The LCD splash screen will show LinuxCNC Handwheel.

Once the handwheel is configured in LinuxCNC, it will display the X,Y,Z, and possibly A axis values.  If LinuxCNC is not sending the handwheel any information, the handwheel LCD will display "No Conn".  

First, home each axis of your machine.  Jogging will not be possible until each axis is homed.

The green light will blink as edges are seen by the encoder.  If no edges occur, the green light will remain off, but the LCD will remain on as long as the handwheel is powered.

The handwheel software will send the encoder edge count, current encoder axis, and speed parameters to the module that is connected to LinuxCNC.  

HAL File Contents

The contents of this file can be modified to uncomment the 4th axis or to change the serial port if needed.

loadrt usb-handwheel device="/dev/ttyACM0"   #//load the program
loadrt threads name1=hw_thread period1=1050000 period2=1100000 #//create a thread
addf usb-handwheel hw_thread  #//put our program in the thread
#addf usb-handwheel base-thread  #//alternatively, we can add it to the base thread, but this may cause some delays

setp usb-handwheel.num_axis 3
#setp usb-handwheel.num_axis 4 #// swap these two to enable the fourth axis

#setp usb-handwheel.scale_factor.0 0  #these are default and only needed if you want to change them.
#setp usb-handwheel.scale_factor.1 0.01
#setp usb-handwheel.scale_factor.2 0.1
#setp usb-handwheel.scale_factor.3 1.0

net xjogcounts =>axis.x.jog-counts <= usb-handwheel.counter.0
net yjogcounts =>axis.y.jog-counts <= usb-handwheel.counter.1
net zjogcounts =>axis.z.jog-counts <= usb-handwheel.counter.2
#net ajogcounts =>axis.a.jog-counts <= usb-handwheel.counter.3

net xjogscale =>axis.x.jog-scale <= usb-handwheel.scale.0
net yjogscale =>axis.y.jog-scale <= usb-handwheel.scale.1
net zjogscale =>axis.z.jog-scale <= usb-handwheel.scale.2
#net ajogscale =>axis.a.jog-scale <= usb-handwheel.scale.3

net xdisplay => usb-handwheel.position.0 <= axis.x.pos-cmd  # //this is the value that gets displayed 
net ydisplay => usb-handwheel.position.1 <= axis.y.pos-cmd
net zdisplay => usb-handwheel.position.2 <= axis.z.pos-cmd 
#net adisplay => usb-handwheel.position.3 <= axis.a.pos-cmd 

net xhwenable => axis.x.jog-enable <= usb-handwheel.enable.0
net yhwenable => axis.y.jog-enable <= usb-handwheel.enable.1
net zhwenable => axis.z.jog-enable <= usb-handwheel.enable.2
#net ahwenable => axis.a.jog-enable <= usb-handwheel.enable.3

Debug Screen

The handwheel software has a debug screen that is accessible by placing the speed selector in the off position, then toggling the X and Y positions 3 times on the axis selector.  The screen will display a screen with lots of numbers on it.  Here is what they mean:

To exit the debug screen, turn the speed switch off and toggle the X and Y switch positions 3 times.

Troubleshooting

• If the handwheel doesn't turn on the green LED or the LCD screen when plugged into the USB port, try plugging it into either a seperate computer or a USB charger.  If it doesn't power up, please contact us for repair or replacement.
• If the Pi shuts off when the handwheel is plugged in, check to make sure that the spade lugs are screwed to the encoder wheel.  If they are dangling around they could short together and cause the pi to turn off.
• If the handwheel doesn't move the machine:
  • If the machine is not completely homed, the handwheel will not be able to move any of the axis.  Please make sure you home each axis.
• If the handwheel doesn't communicate with LinuxCNC, try the following:
  • For the initial beta and first round units, unplug the USB-C end of the cable, twist it 180 degrees, then plug it back in.  The USB cable has two separate data wires internally, and the orientation of the cable will use a different pair of wires.  This may be a workaround for a bad solder joint either in the cable or the connector.  Note: All purchased handwheel encoders should not have this issue.  The beta units were not part of the first production run.
• LinuxCNC has a debugging tool called Halshow that can be found in the menu: Machine->Show Hal Configuration.  Look for usb-handwheel in the Pins section of the tree view.  You can double click on the values and they will appear in the watch window.  If you can't find the usb-handwheel at all, then the module is not loaded.  Please see step 1 of the setup above.
• If each of the axis seem to be going backwards, please open up the handwheel encoder by unscrewing the large 7 (2mm Allen head) screws.  Check the A and B wires to the encoder and make sure they are not reversed.  If they are reversed, it will make the encoder pulses go backwards.  This shouldn't happen when using the flex PCB to connect the encoder wheel to the main board.  This may only occur if wires are soldered to the main board and screwed to the encoder wheel.