Track Rotary Encoder

The P2 peripheral port of the Behavior board has an encoder mode that allows it to read a quadrature encoder (e.g. to track the rotation of a treadmill). Refer to the connections article to set up either the Rotary Encoder peripheral or attach an external quadrature encoder to the Breakout board.

This article covers enabling the encoder mode, visualizing the reading, and resetting the count.

The complete workflow is shown below. Copy and paste it into Bonsai or build each section by following the step-by-step instructions below.

Enable the Encoder

The encoder mode is disabled by default and needs to be enabled with the EnableEncoders register. The reading can either reflect position or displacement, which is set with EncoderMode.

• Insert a KeyDown operator and set the Filter property to A.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select EncoderModePayload.
  • EncoderMode - Select Position to stream the accumulated count, or Displacement to stream the change since the previous sample.
• Insert a MulticastSubject operator named Behavior Commands.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select EnableEncodersPayload.
  • EnableEncoders - Select EncoderPort2 to enable the encoder. To disable the encoder in the future, select None.
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow and press A to enable the encoder.

Warning

While the encoder is enabled, P2 repurposes its infrared and DIO lines as the quadrature inputs: poke events from P2 are suspended until the encoder is disabled.

Visualize Encoder Reading

The counter is then streamed in the Encoder field of the 1 kHz AnalogData events.

• Insert a SubscribeSubject operator named Behavior Events.
• Insert a Parse operator and configure the Register property to AnalogData.
• Right-click on the Parse operator, select the "Output (Harp.Behavior.AnalogDataPayload)" > "Encoder" option from the context menu. This will create an Encoder node.
• Insert a VisualizerWindow operator. This will automatically open a window displaying the encoder count when the workflow starts.

Run the workflow, press A to enable the encoder if it is disabled, and turn the encoder shaft. The visualizer plots the count going up in one direction and down in the other.

Warning

In Position mode the count is a signed 16-bit value that ranges from -32768 to 32767 and wraps around silently when it passes either end. If the count is likely to hit those limits, reset the count every session or switch to Displacement mode and accumulate the per-sample changes in Bonsai with an Accumulate operator.

Reset the Encoder

The EncoderReset register sets the counter of the selected encoders back to zero:

• Insert a KeyDown operator and set the Filter property to S.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select EncoderResetPayload.
  • EncoderReset - Select EncoderPort2.
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow and press S. The Encoder value in the analog stream returns to zero.

---

Last updated with:
Hardware v2.1
Firmware v3.3
Bonsai Package v0.2