Skip to content

feat: optional haptic feedback for surfaces - #90

Merged
Julusian merged 4 commits into
bitfocus:mainfrom
cbusillo:feat/surface-haptic-feedback
Nov 21, 2026
Merged

Julusian merged 4 commits into
bitfocus:mainfrom
cbusillo:feat/surface-haptic-feedback

Conversation

@cbusillo

@cbusillo cbusillo commented Sep 18, 2026 •

Copy link
Copy Markdown
Contributor

Goal

A press on a surface should be able to show that it did something, and show when a hold has fired. On a Loupedeck that is a haptic click. On an X-keys it could be a flash of the key. Only Companion knows when a press ran actions or a hold group fired, so this adds a way for Companion to tell the surface, per control.

What

Everything is optional, so existing modules keep working unchanged.

  • Surface side (@companion-surface/base): a module lists the events it can show in controlEvents in its register props, such as ['press', 'hold'], and implements controlEvent(controlId, event) on its SurfaceInstance. There are two events for now. press means a press of that control ran an action group, on down or release. hold means a run-while-held group fired while the control is held. Surfaces should ignore events they don't recognise. How to show an event is up to the surface. One that can only signal for the whole device can ignore the control id.
  • Host side (@companion-surface/host): OpenDeviceResult gains controlEvents?: { connectionId }, present only when the list is not empty and the method exists. The host only sends events in that list. Companion calls PluginWrapper.controlEvent(surfaceId, connectionId, controlId, event).

Behaviour worth reviewing

  • When to send events, and the per-group opt-out, stay in Companion. Nothing here fires from raw input.
  • Events are dropped before the surface is ready, while it is locked, after it closes, and for controls it does not have.
  • The connectionId is new on every open, so a delayed event can't reach a surface reopened under the same id.
  • Errors from the module are caught and logged.

Satellite

I have matching changes ready for the satellite API and companion-satellite. A device opts in when it registers and receives a CONTROL-EVENT message. I'll open those once the shape here is agreed.

Testing

plugin.controlEvent.spec.ts covers legacy modules, list and method mismatch, a surface that lists only press, events before ready, unknown controls, locked surfaces, a module that rejects, close, and a stale connection id after reopen. Build, lint and the host tests pass. Three schema generation tests fail the same way without this change. I tested it end to end on a Loupedeck Live S with Companion main and bitfocus/companion#4538: press and hold cues, the per-group and surface opt-outs, reconnect and rapid input. I haven't touched versions or changelogs. Names are still open.

This change was written with AI assistance and reviewed and tested by me.

Let a surface declare that it can give haptic feedback and implement
triggerHapticFeedback(). The host reports the capability only when the
registration flag is true and the method exists, so existing modules are
unaffected and need no changes.

Requests are accepted only once the surface is ready, and failures in the
surface's implementation are caught and logged. Each successful open gets
a connection ID that a request must match, so a delayed request cannot
reach a surface that was closed and reopened under the same surface ID.
@coderabbitai

coderabbitai Bot commented Sep 18, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 93cb9a4b-c025-4447-9165-c15f73031b1c
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@Julusian

Copy link
Copy Markdown
Member

How do you intend this to be exposed within Companion? Is this something there would be an action for, or is it behaviour within the 'SurfacePanel' class?
Trying to think about whether this is the best design is hard without having an idea of the full picture

As the loupedeck product line is dead, and according to our stats there are only something around 100 loupedecks in use across 80_000 companion installs that are reporting, I am a little hesistant to add something which could be too specific for them to the api.
If this is generic enough and there are likely to be other desirable products that would make use of it then that changes things.

Also, this would probably need to be added to the satellite api, so that it behaves the same when run there.

So I am not entirely against this, but want to understand more first

@cbusillo

Copy link
Copy Markdown
Contributor Author

Thanks for merging #4473.

What I'm after is feeling when a hold has taken. I use 1 s run-while-held buttons on a Live S and can't tell when they've fired without looking. So in Companion it's behaviour rather than an action: a cue when a physical press runs an action group, and another when a run-while-held group activates, with an opt-out per action group. Branch is here: https://github.com/cbusillo/companion/tree/feat/haptic-feedback

That's also why it's in the API and not just a setting in the loupedeck module. The module could buzz on every press, but it doesn't know whether the press did anything or when a hold activates. Only Companion knows that.

You're right about the numbers. The API is only a flag and "play a short cue", but the Loupedeck family is the only hardware I know of that would use it today.

The core side touches more of Controls than I'd like, so if you see a simpler place for it to live I'm happy to rework it. If you're ok with it in principle I'll do satellite too.

@Julusian

Julusian commented Oct 3, 2026

Copy link
Copy Markdown
Member

ok yeah the firing on hold is the challenging bit, and isnt something that the surface modules should be aware of directly. so I dont have any ideas on a different approach.

I think there is a question of whether this could/should be made a bit more of a generic 'event' instead of haptics? which might depend on how exactly this ties in inside companion.
perhaps an xkeys would want to do the same to flash a colour when reaching the hold threshold or something.
and whether it should be the one haptics/hold event, or more possible events?

And while haptics may not make sense to be per control, if this is made any more generic it would be good to have it wired up to be per control, so that if it does want to be a button flash instead of buzz, then a surface can do that. Inside the loupedeck it would ignore that control info of course.

@cbusillo

cbusillo commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

Yeah, that makes sense. Buzzing is just how a Loupedeck shows it, and an X-keys flashing the key at the hold threshold is a good example of why it shouldn't be haptics-specific.

I'd change it to something like controlEvent(controlId, event) that a surface can optionally implement. To start with there would be two events: press when a press runs actions (on down or release), and hold when a run-while-held group fires. Those are the two places I actually want feedback, and I'd rather add more when someone needs them than guess now. Loupedeck would ignore the controlId and just click. The per-group opt-out stays in Companion, so it works the same whatever the surface does with it.

If that sounds right to you I'll rework this and do satellite as well. Not attached to the names.

Surfaces can now register controlEvents and implement
controlEvent(controlId, event) instead of a haptics-only call. The two
events are press (a press ran an action group, on down or release) and
hold (a run-while-held group fired). A surface decides how to show them,
for example a haptic click or a flash of the key, and may ignore the
control id.

The host keeps the per-open connection id, drops events before ready,
while locked, after close and for unknown controls, and contains errors
from the surface.
@cbusillo

Copy link
Copy Markdown
Contributor Author

I've reworked this to the generic shape. A surface sets controlEvents: true and implements controlEvent(controlId, event). There are two events for now. press means a press ran an action group, on down or release. hold means a run-while-held group fired. Surfaces should ignore events they don't know. The host still drops stale, locked, not-ready and unknown-control events. Satellite support is ready in Companion core and companion-satellite. I'll open those once you're happy with the shape. Names are still open.

shiny-code-app Bot pushed a commit to cbusillo/companion that referenced this pull request Oct 18, 2026
When a physical press runs an action group, Companion sends a press
event to the control that was pressed. When a run-while-held group
fires, it sends hold. The surface decides how to show it, for example a
haptic click or a flash of the key. This uses the optional
controlEvent(controlId, event) surface API proposed in
bitfocus/companion-surface-api#90.

- Plugin surfaces receive controlEvent IPC with the per-open connection
  id, so a delayed event cannot reach a reconnected surface.
- Satellite API 1.15.0: a client that sets CONTROL_EVENTS on ADD-DEVICE
  receives CONTROL-EVENT with KEY or CONTROLID and EVENT. Advertised by
  CONTROL_EVENTS in CAPS and listed in the satellite-protocol feature
  table.
- Each action group has a "Surface cue" checkbox, on by default, stored
  as controlEventsDisabledSets on the step. A release does not send a
  second event after a press or hold already did.
- Synthetic presses (HTTP, OSC, web buttons, triggers) send nothing.
  Button references pass the original surface through. Cancel, lock and
  unload stop pending events.
- New internal action "Surface: Show cue on this button" sends a press
  event to the control showing the running button.

Timed groups that run on release send nothing yet; when that cue should
fire is still an open question.
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
Contributor Author

Whenever you have time, this is ready for another look in the controlEvent shape. I think the fork's CI run is waiting on an approval click too.

Comment thread packages/host/src/surfaceProxy.ts Resolved
Comment thread packages/base/src/surface-api/types.ts Resolved
@cbusillo

Copy link
Copy Markdown
Contributor Author

Thanks. Both done.

  • The connection id is now string | undefined instead of optional.
  • controlEvents is now a list of the events the surface can show, like ['press', 'hold']. The host only sends events in that list. A surface can take presses without holds, and new event types can be added later without a second flag.

@Julusian
Julusian merged commit 1e3906f into bitfocus:main Nov 21, 2026
2 of 4 checks passed
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.

2 participants