Encoders

The module encoder is used used to measure position by counting the pulses generated by a quadrature encoder. It is meant as a drop-in replacement for the LinuxCNC encoder component , with some extra functions. Differences are:

LitexCNC uses a different algorithm to calculate the velocity of the encoder. Therefore the HAL-pin min-speed-estimate is no longer used.
To be able to simulate a (digital) potentiometer, the HAL-parameter position-scale is supplemented with position-offset.
The encoder can be configured to:
- Have a custom reset-value (default=0)
- Have a minimum and/or maximum value (default=None, meaning no minimum and/or maximum value). This functionality is required to create a (digital) potentiometer.

Configuration

The code-block belows gives an example for the configuration of stepgen for different both a simple encoder and encoders with an index pulse.

simple
with index
digital potentiometer

...
"modules": [
    ...,
    {
    "module_type": "encoder",
    "instances": [
        {"pin_A":"j3:0", "pin_B":"j3:1"},
        ...,
        {"pin_A":"j3:2", "pin_B":"j3:4"}
    ]
    },
    ...
]

...
"modules": [
    ...,
    {
    "module_type": "encoder",
    "instances": [
        {"pin_A":"j3:0", "pin_B":"j3:1", "pin_Z":"j3:2"},
        ...,
        {"pin_A":"j3:4", "pin_B":"j3:5", "pin_Z":"j3:6"}
    ]
    },
    ...
]

...
"modules": [
    ...,
    {
    "module_type": "encoder",
    "instances": [
        {
            "name": "feed_override",
            "pin_A":"j3:0",
            "pin_B":"j3:1",
            "pin_Z":"j3:2",
            "min_value": 250,
            "max_value": 1500,
            "reset_value": 1000
        },
        ...,
        {
            "name": "spindle_override",
            "pin_A":"j3:4",
            "pin_B":"j3:5",
            "pin_Z":"j3:6",
            "min_value": 500,
            "max_value": 1300,
            "reset_value": 1000
        }
    ]
    },
    ...
]

Defining the pin is required in the configuration. Optionally one can give the pin a name which will be used as an alias in HAL. When no name is given, no entry in the file containnig the aliases will be generated.

Tip

When inserting new pins in the list and the firmware is re-compiled, this will lead to a renumbering of the HAL-pins. When using numbers, it is therefore strongly recommended only to append instances to prevent a complete overhaul of the HAL.

HAL

Note

The input and output pins are seen from the module. I.e. the GPIO In module will take an value from the machine and will put this on its respective _output_ pins. While the GPIO Out module will read the value from it input pins and put the value on the physical pins. This might feel counter intuitive at first glance.

Input pins

<board-name>.encoder.<n>.index_enable (HAL_BIT): When true, counts and position are reset to zero on the next rising edge of Phase-Z. At the same time, index-enable is reset to zero to indicate that a rising edge has occurred.

Output pins

<board-name>.encoder.<n>.counts (HAL_INT): Position in encoder counts.
<board-name>.encoder.<n>.index_pulse (HAL_BIT): When true, a rising edge has been detected on the FPGA. This flag will be active until the next read action from the FPGA, when it is automatically reset.
<board-name>.encoder.<n>.position (HAL_FLOAT): Position in scaled units (see parameter position-scale).
<board-name>.encoder.<n>.velocity (HAL_FLOAT): Velocity in scaled units per second. Encoder uses an algorithm that greatly reduces quantization noise as compared to simply differentiating the position output. When the magnitude of the true velocity is below min-speed-estimate, the velocity output is 0.
<board-name>.encoder.<n>.velocity_rpm (HAL_FLOAT): Velocity in scaled units per minute. Simply encoder.N.velocity scaled by a factor of 60 for convenience.
<board-name>.encoder.<n>.overflow_occurred (HAL_BIT): Indication that overflow has occurred. This indicates that the position and velocity might be less accurate due to rounding errors with floating point.

Parameters

<board-name>.encoder.<n>.position_scale (HAL_FLOAT): Scale factor, in counts per (length) unit. For example, if position-scale is 500, then 1000 counts of the encoder will be reported as a position of 2.0 units.
<board-name>.encoder.<n>.position_offset (HAL_FLOAT): Position offset in scaled units. When the encoder count is 0, this will be the reported position. Can be used to create a digital potentiometer.

Example

The examples below uses the 5a-75b_v#.#_i12o14p6s6e6.json firmware (except for the digital potentiometer, which requires additional settings as shown in the example configuration above). Please change #.# for the correct version of your board.

spindle feedback
digital potentiometer

TODO

loadrt litexcnc
loadrt litexcnc_eth connection_string="<ip_address>"
loadrt threads name1=test-thread period1=10000000

# SETUP WATCHDOG
# ==============
setp test_PWM_GPIO.watchdog.timeout_ns 15000000

# ADD FUNCTIONS TO THREAD
# =======================
addf <board-name>.read test-thread
addf <board-name>.write test-thread

# DIGITAL POTENTIOMETER FOR FEED/SPEED
======================================
# NOTE: this example uses GMOCCAPY
# For all encoders for overrides the index_enable is set by default to 1, which
# means that the encoder can be reset at any time.
# The ``direct-value`` pin does accept values from 0.0 to 1.0, being the percentage
# value you want to set the slider value. It is recommended to have configure the
# FPGA setting the ``minimum_value`` and ``maximum_value`` equal to the boundaries
# of GMOCCAPY (while taking into account the scale or desired resolution). The ``reset_value``
# should be set to 100 / position_scale.
# - feed override
setp <board-name>.encoder.0.index_enable        1
setp <board-name>.encoder.0.position_scale      0.0008  # 1 / (max_value - min_value)
setp <board-name>.encoder.0.position_offset    -0.2     # -1 * min_value * position_scale
setp gmoccapy.feed.feed-override.analog-enable  1
net <board-name>.encoder.0.position => gmoccapy.feed.feed-override.direct-value
# - spindle override
setp <board-name>.encoder.1.index_enable        1
setp <board-name>.encoder.1.position_scale      0.00125 # 1 / (max_value - min_value)
setp <board-name>.encoder.1.position_offset    -0.625   # -1 * min_value * position_scale
setp gmoccapy.spindle.spindle-override.analog-enable  1
net <board-name>.encoder.1.position => gmoccapy.spindle.spindle-override.direct-value

Break-out boards

For simple encoders, such as inputs for speed and feed overrides, the 12 channel sinking input can be used. This gives the possibility to combine GPIO input and encoders on a single break-out board. The speed of this break-out board is limited by the maximum speed of the used opto-couplers.

For faster encoders a dedicated fast encoder is created. This board support up to 3 A/B encoders or 2 A/B/Z encoders. This board is developed to be used with differential output from the encoders.