Repository navigation
feat: optional haptic feedback for surfaces - #90
Conversation
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.
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
|
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? 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. 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 |
|
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. |
|
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. 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. |
|
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 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.
|
I've reworked this to the generic shape. A surface sets |
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.
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.
|
Whenever you have time, this is ready for another look in the |
|
Thanks. Both done.
|
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.
@companion-surface/base): a module lists the events it can show incontrolEventsin its register props, such as['press', 'hold'], and implementscontrolEvent(controlId, event)on itsSurfaceInstance. There are two events for now.pressmeans a press of that control ran an action group, on down or release.holdmeans 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.@companion-surface/host):OpenDeviceResultgainscontrolEvents?: { connectionId }, present only when the list is not empty and the method exists. The host only sends events in that list. Companion callsPluginWrapper.controlEvent(surfaceId, connectionId, controlId, event).Behaviour worth reviewing
connectionIdis new on every open, so a delayed event can't reach a surface reopened under the same id.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.tscovers legacy modules, list and method mismatch, a surface that lists onlypress, 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.