Rotary Encoder

name string | false | null "rotaryEncoder"

Controls automatic event callback registration. Any function on the sketch named name + EventName (event name capitalised) is called whenever that event fires. With the default name:

function rotaryEncoderChanged(event) { /* knob turned or button changed */ }
function rotaryEncoderPressed(event) { /* button pressed */ }
function rotaryEncoderReleased(event) { /* button released */ }

Pass false or null to disable automatic registration and use addEventListener instead.

addressOrIndex number 0x36

The I2C address of the device, or an index (0–7) into the address list. Eight addresses are available, set by the A0, A1, and A2 solder jumpers on the back of the board:

getValue() number

Returns the current encoder position as a signed integer. The value starts at 0 and increments or decrements by one for each detent as the knob is turned. There is no minimum or maximum — the value accumulates indefinitely in either direction.

isPressed() boolean

Returns true if the encoder button is currently held down.

getBrightness() number

Returns the current brightness level as an integer from 0 (off) to 255 (full brightness). The default is 128.

getLength() number

Returns the number of NeoPixels on the device.

getPixelColor(index?) ColorObject

Returns the last known color of the pixel at index (defaults to 0) as a { red, green, blue } object with values from 0 to 255.

getPixelColors(offset?, length?) ColorObject[]

Returns an array of { red, green, blue } objects for the pixels starting at offset (default 0). If length is omitted, all pixels from the offset to the end are returned.

setBrightness(value) Promise<void>

Sets the global brightness for all pixels. value is clamped to 0–255 and rounded to the nearest integer.

setPixelColor(color) Promise<void>

setPixelColor(index, color) Promise<void>

Sets the color of a single pixel. When called with one argument the first pixel (index 0) is used. color accepts a { red, green, blue } object, a CSS hex string (e.g. "#ff0000"), or a packed 24-bit integer.

setPixelColors(colors) Promise<void>

setPixelColors(offset, colors) Promise<void>

Sets the colors of multiple pixels in one call. When called with one argument the update starts at pixel 0; provide an offset to start further along. Each entry in colors accepts the same formats as setPixelColor. Large updates are automatically split into chunks of 64 pixels.

connect() Promise<Response>

Opens the USB connection and sends the start command to the firmware. Calling it multiple times is safe — subsequent calls return the same promise. In p5.js you do not need to call this manually; startXxx() calls it for you inside preload().

id { type, address }

Identifies the device. type is the DeviceType enum value, address is the I2C address the device was started with.

isConnected boolean

true once the USB connection has been established and the firmware has acknowledged the device. In p5.js this is always true by the time setup() runs, because startXxx() waits for the connection inside preload().

changed(event) changed

Fires whenever the knob is turned. Also fires if the button state changes at the same time as a rotation (both updates arrive in one firmware poll).

pressed(event) pressed

Fires when the encoder button is pressed down.

released(event) released

Fires when the encoder button is released.

event.detail.isPressed boolean — Whether the button is held down at the time of the event.

event.detail.value number — The current encoder position at the time of the event.