Skip to content

feat: best-effort vibration, for haptic feedback on button presses - #58

Open
cbusillo wants to merge 1 commit into
Julusian:mainfrom
cbusillo:feat/best-effort-vibrate
Open

cbusillo wants to merge 1 commit into
Julusian:mainfrom
cbusillo:feat/best-effort-vibrate

Conversation

@cbusillo

@cbusillo cbusillo commented Sep 18, 2026 •

Copy link
Copy Markdown

Goal

I'm adding haptic feedback to Companion's Loupedeck support: a short click when you press a touch button with an action, and another when a hold action fires. This PR is the library piece. The rest will follow as separate PRs to companion-surface-api, companion and companion-surface-loupedeck, and they depend on a release that includes this.

Why the library needs a change

vibrate() already exists, but it waits for the device's acknowledgement inside the command queue. Fired on every press, a slow or missing acknowledgement delays the button redraw that follows. And the built-in patterns played in full are either long buzzes or loud clicks, which don't feel like a button press.

What

  • vibrate(pattern, { bestEffort: true }) resolves after the transport write, without waiting for the acknowledgement. Its transaction ID stays reserved until the acknowledgement arrives or the connection is torn down, so a late acknowledgement can never resolve another command. While one is outstanding, further best-effort requests are dropped, not queued. Default vibrate() behaviour is unchanged.
  • Optional interrupt: { afterMs, pattern } sends a second pattern a few milliseconds later, from the same queue slot so queued draws cannot change the spacing. On a Live S a new vibration command replaces the one playing, so interrupting with a pattern too weak to feel turns a click into a much shorter, quieter one. Two enum members name the effects I used (0x05, 0x06).
  • Two fixes found along the way: acknowledgement waiters are now registered before the write, so an acknowledgement delivered during submission isn't lost. Node serial send now waits for both write callbacks and reports their errors, while keeping each header and payload adjacent.

Testing

  • 21 fake-transport tests using node --test (no new dependencies), passing on Node 20 and Node 26. They cover missing, immediate and late acknowledgements, ID wrap and exhaustion, close and disconnect at each stage, write failures, and the interrupt paths. I added a unit:node script and a CI job for them. The existing unit script points at Jest, which isn't installed, so I left it alone. I'm happy to fold these together however you prefer.
  • Hardware: exercised on one Loupedeck Live S (firmware 0.1.4) through a local Companion build, including rapid presses, reconnects and normal drawing. Sharp Click 60% interrupted after 5 ms by Sharp Click 30% was the feel I settled on. I have not tested other models.

Notes

The pattern byte appears to be a TI DRV2605 ROM effect ID (the existing enum values line up with that table), which is where the two new names come from. If you'd rather not add enum members on that basis, I can pass raw numbers from the caller instead.

I can split the two fixes into their own PR if that's easier to review.

Disclosure

This change was written with AI assistance. I directed the design, reviewed the code, and tested it on my own hardware.

Add vibrate(pattern, { bestEffort: true }), which resolves after the
transport write instead of waiting for the acknowledgement. Its
transaction ID stays reserved until the acknowledgement arrives or the
connection is torn down, and overlapping best-effort requests are
dropped, so a missing acknowledgement cannot hold up draws or brightness.

An optional interrupt submits a second pattern a few milliseconds later
from the same queue slot. A new vibration command replaces the playing
one, so a pattern too weak to feel shortens the first into a brief click.

Register acknowledgement waiters before submitting, so an acknowledgement
delivered during the write is not lost, and surface serial write errors
while keeping each header and payload adjacent.

Add fake-transport tests run with node --test, and a CI job for them.
shiny-code-app Bot pushed a commit to cbusillo/companion-surface-loupedeck that referenced this pull request Oct 18, 2026
On models with a vibration motor, register for Companion control events
and play a short click when Companion reports that a press ran actions
(press) or a run-while-held group fired (hold). The adapter never
vibrates from raw input, draws or startup. The motor is shared by the
whole device, so the control id is ignored, and unknown events are
ignored.

The click is a Sharp Click interrupted a few milliseconds later by a
pattern too weak to feel, which keeps it short and quiet. A hold cuts it
3 ms later than a press, because a finger resting on the key damps it.
Per-surface settings enable it (on by default) and choose Light, Medium
or Strong. Requests are dropped while one is in flight, before the
surface is ready and after close. Stream Controller X has no motor and
gets no settings.

Adds a node:test suite and runs it in CI.

Depends on unreleased @companion-surface/base (controlEvent, see
bitfocus/companion-surface-api#90) and @loupedeck/node (best-effort
vibrate with interrupt, see Julusian/node-loupedeck#58). Dependency
versions will be bumped once those are released.
@cbusillo

Copy link
Copy Markdown
Author

Friendly ping on this one. It is the library half of the haptics work, and it is opt-in: existing vibrate calls behave exactly as before.

On the small Loupedeck user count you raised on the surface API PR: the Companion side is now the generic controlEvent shape you suggested (bitfocus/companion-surface-api#90), so only this change and the Loupedeck module are Loupedeck-specific. The Razer Stream Controller also has a motor and uses the same code. I'm also not the only one who wants this: ninoleto shipped haptics in their own fork (bitfocus/companion-surface-loupedeck#24).

I tested the full stack on a Live S today. I'm happy to keep this working and to change anything you'd like.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant