Control Digital Outputs

The Behavior board has four general-purpose digital outputs DO0–DO3 on the Output connector. Refer to the connections article to set up a digital output on DO0, which we will use for the rest of these examples.

This article covers how to set, clear, toggle, and pulse any of these outputs in Bonsai.

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

Note

The commands in the examples below can be used to control every output line of the Behavior board. Their location on the Behavior board and values in Bonsai are:

• General-purpose digital outputs DO0–DO3: DO0 - DO3.
• Peripheral ports P0–P2: the 5 V output lines are represented as DOPort0–DOPort2 and 12 V valve lines as SupplyPort0–SupplyPort2. See Control Poke Peripheral.
• LED connectors L0, L1 and RGB: represented as Led0, Led1, Rgb0 and Rgb1 in Bonsai. See Control LEDs.

Note

If you need more digital inputs or outputs, the Breakout extension board makes the peripheral ports' pins available as regular screw-terminal inputs and outputs.

Set and Clear Outputs

Use the OutputSet and OutputClear registers to turn output lines on and off.

• Insert a KeyDown operator and set the Filter property to A.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select OutputSetPayload.
  • OutputSet - Select the line to turn on (e.g. DO0).
• Insert a MulticastSubject operator named Behavior Commands.

In a separate branch:

• Insert a KeyDown operator and set the Filter property to S.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select OutputClearPayload.
  • OutputClear - Select the line to turn off (e.g. DO0).
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow, then press A to set the DO0 line high and S to set it low.

Note

A single command can drive several outputs at once. To select multiple lines, type the names separated by a comma (e.g. DO0, DO1) in the payload field. Any lines not selected are left untouched.

Toggle Outputs

The OutputToggle register inverts the current state of the selected output lines.

• Insert a KeyDown operator and set the Filter property to D.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select OutputTogglePayload.
  • OutputToggle - Select the line to toggle (e.g. DO0).
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow and press D repeatedly. The DO0 line inverts its state on every press.

Write All Outputs

The OutputState register writes every output line in a single command: selected lines are set and all other lines are cleared. Use it to drive the whole output bank to a known state, for example when initializing an experiment.

• Insert a KeyDown operator and set the Filter property to G.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select OutputStatePayload.
  • OutputState - Set the lines to turn on (e.g. DO0, DO1). All other lines are cleared.
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow and press G. The DO0 and DO1 lines go high and every other output goes low. Try setting other outputs first with the commands from the previous sections; the OutputState write overrides them all.

Warning

OutputState acts on every output of the Behavior board, including the peripheral port and LED lines. To change a few lines while leaving the rest untouched, use OutputSet, OutputClear or OutputToggle instead.

Pulse Outputs

The device can generate hardware-timed pulses with a defined duration. Enable pulse mode by selecting output lines in the OutputPulseEnable register, and set the duration in the output line's pulse-duration register (e.g. PulseDO0 for DO0, in milliseconds). Sending an OutputSet command then starts a pulse that turns off after the elapsed time instead of remaining on.

• Insert a KeyDown operator and set the Filter property to F.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select OutputPulseEnablePayload.
  • OutputPulseEnable - Select the line to enable pulse mode (e.g. DO0).
• Insert a MulticastSubject operator named Behavior Commands.
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select PulseDO0Payload.
  • PulseDO0 - Set the pulse duration in ms (e.g. 500).
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow, press F once to configure the pulse, then send a set command with A from Set and Clear Outputs. The DO0 line goes high for 500 ms and returns low on its own.

Warning

OutputPulseEnable is a selection mask over all digital outputs. Any output not selected in the payload has its pulse mode disabled. Make sure to list every output that should keep pulse mode (e.g. DO0, SupplyPort0).

Tip

The poke valve outputs (SupplyPort0–SupplyPort2) boot with pulse mode already enabled and a default duration of 15 ms; see Deliver Rewards on Poke. All other outputs boot with pulse mode disabled and stay on until cleared.

Tip

This method is preferred to timing pulses in software (e.g. pairing a set command with a delay and a clear command). Software timing is subject to non-real-time OS latency and jitter, which are most noticeable on short pulses.

Alternative: Set Outputs with Timer

You can replace KeyDown with other operators to set outputs with other triggers in Bonsai, for instance a Timer to send triggers at a set time.

• Insert a Timer operator and set the DueTime property to the number of seconds to wait before setting the output (e.g. 00:00:02 for two seconds).
• Insert a CreateMessage operator and configure the following properties:
  • Payload - Select OutputSetPayload.
  • OutputSet - Select the line to turn on (e.g. DO0).
• Insert a MulticastSubject operator named Behavior Commands.

Run the workflow. The DO0 line goes high after 2 seconds and turns off automatically if pulse mode is enabled.

---

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