# Encoder and Position

JCS network off-axis relative encoder is based on an Austria Micro AS5311 magnetic sensing absolute encoder. The AS5311 measures 4096 counts per 2mm pole-pair (1mm magnetic pole length) and works with both linear and ring magnetic targets.

The off-axis relative encoder is capable of sensing both linear position and rotational position.

The linear resolution of the encoder is fixed at \(2mm/4096counts\) (488nm/step). The rotational resolution is dependant on the diameter (and thus the number of pole-pairs) of the magnet ring. JCS offers a 64 pole-pair magnet ring for an encoder count of 262144 counts per revolution. Other magnetic targets may be installed for different resolutions.

At each encoder tick, the position of the sense magnet is sampled and passed through a two state Kalman filter (rotational or linear, depending on the estimator configuration), from which an estimate of the position and velocity of the magnet is obtained.

Encoder/estimator tick rate (\(f\)) | 10kHz |

`op_state` warning bits |
Bit 3 - Encoder zero'd flag Bit 4 - Velocity warning flag Bit 5 - Sensor warning flag Bit 6 - Position maybe invalid flag |

## Encoder Configuration

The following parameters are available for configuring the encoder:

Command | Type | Required | Description |
---|---|---|---|

`encoder_position_zero` |
command | Optional | Records the current encoder position as the zero offset. |

`encoder_direction` |
boolean | Required | Sets the encoder direction. |

`encoder_error_rate_limit` |
float32 | Optional | Encoder error rate limit. Default: 0.05 |

### Encoder position zeroing and offset

An encoder may be zeroed by commanding the system to sample the current encoder position as the zero offset.

To store the encoder current position as the zero offset, issue JCS command `encoder_position_zero`

.

### Encoder direction

Set the encoder direction with a boolean write to `encoder_direction`

.

### Maximum velocity

The off-axis relative encoder has an maximum linear velocity of 20m/s and checks for velocity excursions in both linear and rotary estimator modes.

If the velocity exceeds the maximum speed of the hardware, the position of the encoder cannot be assumed to be valid.
The `op_state`

`velocity warning`

flag will be latched.
The `velocity_warning`

flag is cleared on power cycle or a call to `start`

.

The `op_state`

`position may be invalid`

flag will be asserted to indicate that the encoders position may now be invalid.
The `op_state`

`position may be invalid`

flag may be cleared by zeroing the encoder, a call to `start`

or a by power cycle.

### Encoder errors

In the case that the AS5311 sensor itself returns an error, the `op_state`

`encoder warning`

flag will be asserted for the duration of the error.
The `op_state`

`position may be invalid`

flag will be latched to indicate that the encoders position may now be invalid.
The `op_state`

`position may be invalid`

flag may be cleared by zeroing the encoder, a call to `start`

or a by power cycle.

If a flood of errors occur such that the error rate goes above the limit set in `encoder_error_rate_limit`

, then an E-stop will be generated and the system will attempt to shut down.

To tune the encoder error rate monitor, write a float32 to `encoder_error_rate_limit`

.
Values between 0.0f and 1.0f are valid.
Writing float32 value 1.0f to `encoder_error_rate_limit`

disables the error rate monitor.

The encoder error rate is available as JCS signal `encoder_error_rate`

.

## Estimator Configuration

### Estimator selection

JCS network off-axis encoder supports both linear and rotational position and velocity estimation.

Select an estimator by writing an enum to `estimator_type`

:

Estimator type | Description |
---|---|

`kf_linear` |
Linear Kalman filter estimator |

`kf_rotational` |
Rotational Kalman filter estimator that normalises the position output to \([-\pi, \pi]\). |

`kf_linear`

configuration

Configure the linear Kalman filter estimator with the following parameters:

Command | Type | Required | Description |
---|---|---|---|

`estimator_linear_scale` |
float32 | Optional | Sets the encoder scale from mm to users units. Default: 1.0f (mm) |

`estimator_linear_q_variance` |
float32 | Optional | Sets the internal Kalman filter \(\textbf{Q}\) matrix from variance parameter. Default: \(1e-4\) |

`estimator_linear_r` |
float32 | Optional | Sets the internal Kalman filter \(\textbf{R}\) matrix from variance parameter. Default: \(4.88e-4\) |

`estimator_linear_P_initial` |
float32 array | Optional | Sets the internal Kalman filter initial \(\textbf{P}\) covariance matrix. Default: [100000.0, 0.0, 0.0, 10.0] Write 4x float32 values |

`kf_rotational`

configuration

Configure the rotational Kalman filter estimator with the following parameters:

Command | Type | Required | Description |
---|---|---|---|

`estimator_rotary_cpr` |
uint32 | Required | Sets the encoder counts per revolution. |

`estimator_rotary_q_variance` |
float32 | Optional | Sets the internal Kalman filter \(\textbf{Q}\) matrix from variance parameter. Default: \(1e-4\) |

`estimator_rotary_r` |
float32 | Optional | Sets the internal Kalman filter \(\textbf{R}\) matrix from variance parameter. Default: \(4.88e-4\) |

`estimator_rotary_P_initial` |
float32 array | Optional | Sets the internal Kalman filter initial \(\textbf{P}\) covariance matrix. Default: [100000.0, 0.0, 0.0, 10.0] Write 4x float32 values |

### Estimator variance

The Kalman filter \(\textbf{Q}\) matrix variance is computed according to a piecewise white noise model.

For the estimated state \(\textbf{x} = \big[\begin{smallmatrix} v && x \end{smallmatrix}\big]^\intercal\), the matrix \(\textbf{Q}\) is computed as:

where \(dt = {1 \over{f}}\) from the encoder/estimator tick rate parameters presented above.

Note: Parameter `estimator_q_variance`

is equivalent to \(\sigma^2\). `estimator_q_variance`

is not squared internally.

Note: This applies equally to the rotational Kalman filter with the state \(\textbf{x} = \big[\begin{smallmatrix} \omega && \theta \end{smallmatrix}\big]^\intercal\).

### Estimator initial covariance

If required, set the initial estimator covariance matrix \(\textbf{P}\) by writing a vector of length 4 to `estimator_P_initial`

.

Note: Initial \(\textbf{P}\) matrix values affect the starting performance of the estimator. Since the velocity term is not measured, you may notice large glitches in the velocity estimate at startup if the \(\textbf{P}\) matrix velocity term is too low.

### Estimator pass-through

Setting `estimator_x_passthrough`

to true will cause the system to derive the JCS signal `x`

directly from the encoder, rather than from the estimator.

Command | Type | Required | Description |
---|---|---|---|

`estimator_x_passthrough` |
boolean | Optional | Bypasses the estimator such that the position obtained from the encoder is presented to JCS output signal `x` .Note - The estimator will still produce a velocity estimate output at JCS signal `v` . |

Note that the bypassed position will still retain the following properties:

- May have zero offset applied
- If estimator
`kf_rotational`

is active then the output will be normalised to \([-\pi, \pi]\)

### Absolute position

While the AS5311 magnetic position sensor is able to return an absolute position, it is only able to return the absolute position *within* the 2mm pole-pair.
The sensor is not able to differentiate between pole-pairs and thus the AS5311 encoder system is considered non-absolute.
If the user can guarantee that the magnet target does not move out of a given 2mm pole-pair between power cycles, the encoder position may be considered absolute.