# Encoder and Position

JCS network on-axis absolute encoder is based on an Austria Micro AS5047p magnetic sensing absolute encoder.

At each encoder tick, the rotational position of the sense magnet is sampled and passed through a two state Kalman filter, from which an estimate of the rotational 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 - Position maybe invalid flag |

## Parameters

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_position_offset` |
float32 | Optional | Sets or returns the rotor position offset. |

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

`encoder_linearisation_coeffs` |
float32 array | Optional | An array of 64 coefficients for encoder linearisation. If any elements are non-zero, encoder linearisation is activated. |

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

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

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

### Encoder position zeroing and offset

An encoder may be zeroed by either writing a zero offset or 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`

. The encoder position will be sampled and stored in `encoder_position_offset`

. The sampled zero position may be read as a float32 from `encoder_position_offset`

.

To write an encoder offset, write a float32 to `encoder_position_offset`

. Any existing entry will be overwritten.

### Encoder direction

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

.

### Encoder linearisation

The encoder system supports linearisation of the encoder position by means of a lookup table for correction. The linearisation process takes the scaled encoder value and adds a small corrective bias term that is derived from the linear interpolation of the correction table.

Encoders may be linearised by writing an array of 64 linearisation coefficients to `encoder_linearisation_coeffs`

.

### Maximum velocity

If the rotational velocity exceeds the maximum rotational speed of the hardware device (28000RPM), `op_state`

`velocity warning`

flag will be latched.
The `op_state`

`velocity warning`

flag is cleared on zeroing the encoder, a call to `start`

or a power cycle.

### Error error handling

The encoder system is monitored for errors and registers errors as they occur.
If an encoder error occurs, the previous timestep encoder value is used and the encoder manager will attempt to continue.
`op_state`

`encoder warning`

flag will be asserted for the duration of the error.

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 theta pass-through

Setting `estimator_theta_bypass`

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

directly from the encoder, rather than from the estimator.
Note that the bypassed theta position will still retain the following properties:

- May have zero offset applied
- May have linearisation compensation applied
- Normalised to \([-\pi, \pi]\)

### 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} \omega && \theta \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.