Encoders#

Four extra quadrature encoder inputs, numbered 0 to 3.

Reading counts and velocity#

int counts = exp.getEncoderCount(0);      // signed, accumulates
int rate   = exp.getEncoderVelocity(0);   // signed counts per second

int32_t counts = expander.encoderCount(0);      // signed, accumulates
int32_t rate   = expander.encoderVelocity(0);   // signed counts per second

counts = expander.encoder_count(0)      # signed, accumulates
rate = expander.encoder_velocity(0)     # signed counts per second

Velocity is computed on the board, over a proper time window. This is worth more than it looks: differentiating counts in your own loop gives you a noisy number that depends on how fast that loop happens to be running this iteration. The board’s answer doesn’t.

Counting also happens on the board, which means your loop rate cannot lose you counts. You can spend 50 ms doing something else and the count is still exact when you come back — the failure mode of polling a quadrature signal in software simply does not exist here.

Zeroing#

exp.resetEncoder(0);       // one channel
exp.resetAllEncoders();    // all four

expander.resetEncoder(0);       // one channel
expander.resetAllEncoders();    // all four

expander.reset_encoder(0)        # one channel
expander.reset_all_encoders()    # all four

Resets are idempotent. Every command carries a token, so if the I2C layer retries a transfer, the reset cannot happen twice. You will not get a double-zero from a retry.

Direction#

If a motor is mounted mirrored, fix it on the board rather than negating the number everywhere you use it:

exp.setEncoderDirection(1, BBRDigitalExpander.Direction.REVERSE);

expander.setEncoderDirection(1, BBREncoderDirection::Reverse);

expander.set_encoder_direction(1, EncoderDirection.REVERSE)

FORWARD means the channel counts up when the mechanism moves the way you call forward; REVERSE flips both the count and the velocity. Ask for the current setting with getEncoderDirection(channel).

This one saves itself. Direction is set once when the encoder is bolted on, and a channel that counts backwards again after every reboot is a bug nobody traces back to a missing save call — so it goes to flash for you. Setting the same direction repeatedly costs nothing: the board compares the payload it would write against what is already stored and skips the write.

Like the other setup helpers, run it once rather than in a loop.

Absolute (pulse-width) encoders#

Any channel can be switched from quadrature to reading a PWM absolute encoder — the kind that reports its position as a pulse width, typically 1 to 1024 µs per revolution. An absolute encoder is correct the instant you power on, with no homing move.

exp.setChannelMode(2, BBRDigitalExpander.ChannelMode.PULSE_WIDTH);
int us = exp.getPulseWidthUs(2);    // measured pulse width in microseconds

exp.setPwmChannelParams(2, 1, 1024);   // minUs, maxUs
exp.setPwmWrapEnabled(2, true);
exp.saveConfigToFlash();

expander.setChannelMode(2, BBRChannelMode::PulseWidth);
int32_t us = expander.pulseWidthUs(2);   // measured pulse width in microseconds

expander.setPwmChannelParams(2, 1, 1024);   // minUs, maxUs
expander.setPwmWrapEnabled(2, true);
expander.saveConfigToFlash();

expander.set_channel_mode(2, ChannelMode.PULSE_WIDTH)
us = expander.pulse_width_us(2)   # measured pulse width in microseconds

expander.set_pwm_channel_params(2, 1, 1024)   # min_us, max_us
expander.set_pwm_wrap_enabled(2, True)
expander.save_config_to_flash()

With wrap tracking on, the channel accumulates across revolutions instead of snapping back to zero at the top of each turn.

Triggering on an encoder position#

The board can watch an encoder for you and drive a digital output when it passes a threshold — no I2C, no loop code:

exp.triggerWhenEncoderPast(2, 0, 1000);   // output 2 high once channel 0 reads >= 1000

expander.triggerWhenEncoderPast(2, 0, 1000);   // output 2 high once channel 0 reads >= 1000

expander.trigger_when_encoder_past(2, 0, 1000)   # output 2 high once channel 0 reads >= 1000

That saves to flash for you. The comparison is signed, and on a pulse-width channel the threshold is in microseconds rather than counts. See Digital outputs and triggers.

Diagnosing a channel that reads nothing#

The board exposes the live logic levels on the encoder input pins, which separates “the encoder isn’t turning” from “one wire isn’t connected”:

int pins = exp.readEncoderPinState();   // bit 2n = channel n A, bit 2n+1 = B

uint8_t pins = expander.encoderPinState();   // bit 2n = channel n A, bit 2n+1 = B

pins = expander.encoder_pin_state()   # bit 2n = channel n A, bit 2n+1 = B

Idle inputs read 1, because the inputs are pulled up. Turn the shaft slowly while polling fast: both bits for a healthy channel toggle. A bit that never changes is the dead wire.

Worked example#