Skip to content

feat: Velvet Rituals protocol (VR-* toys) - #984

Open
velvetrituals wants to merge 8 commits into
buttplugio:devfrom
velvetrituals:feat/velvet-protocol
Open

velvetrituals wants to merge 8 commits into
buttplugio:devfrom
velvetrituals:feat/velvet-protocol

Conversation

@velvetrituals

@velvetrituals velvetrituals commented Nov 3, 2026 •

Copy link
Copy Markdown

Closes #974.

Adds a velvet protocol for Velvet Rituals toys (Velvet Technologies GmbH): 13 BLE models advertised as VR-<Model>. The firmware is in the same family as cupido, but it uses its own GATT service and has three quirks that a plain cupido mapping can't handle (details in #974).

What's in it

  • protocol_impl/velvet.rs
    • Motors: B0 03 00 00 <m2> <m1> AA. Single-motor models get motor 1 only, like cupido (Aurora ignores strength changes when both bytes are set).
    • Eclipse (2 motors): when the running motor changes, it sends the zero frame and then the new frame. The firmware ignores the change otherwise. The zero frame has its own command id so batching keeps it.
    • Ember heat: B0 04, off / low / high.
    • Battery: B0 00, with the percentage at byte 5.
  • Write spacing via message_gap_ms (no pacing in the protocol). The toys take write-without-response only and drop a frame sent right after another one.
    • device_task.rs: with a message gap set, writes are kept at least the gap apart, within a batch and from the previous flush (including the acknowledged stop path). Devices without a gap are unaffected.
    • Device config schema: message_gap_ms is allowed per configuration, which ConfigBaseDeviceDefinition already supported.
    • velvet.yml: 60 ms for the range, 250 ms for Ember (needed after a heat frame), 300 ms for Eclipse (needed between the zero frame and a new motor).
  • device-config/protocols/velvet.yml: all 13 models by exact name, plus the regenerated buttplug-device-config-v5.json and a version.yaml bump.
  • Tests: test_velvet_protocol.yaml, test_velvet_eclipse.yaml and test_velvet_ember.yaml, wired into test_device_protocols.rs; two device task unit tests for the spacing.

Testing

  • cargo test -p buttplug_tests --test test_device_protocols: 879 passed, including velvet on all embedded and JSON spec versions (Eclipse and Ember cases on v3 and v4).
  • cargo test -p buttplug_server: passes, including the new spacing tests.
  • cargo +nightly fmt --all -- --check: clean for the files in this PR. ossm.rs already shows a diff on current master, and this PR doesn't touch it.
  • Hardware, 18 Oct 2026, through Intiface Central with a local build: Pixie, Aurora, Ember and Eclipse. The other single-motor models use the same firmware and frames as Pixie.
  • Hardware, 9 Nov 2026, after the review changes, through a local intiface-engine build: Ember (motor, heat, stop, combined commands, fast burst then stop) and Eclipse (motor switching both ways, ramp, stop).

🤖 Generated with Claude Code

velvetrituals and others added 4 commits October 18, 2026 18:15
Cupido firmware family with Velvet's own BLE service: both motor bytes
(A = B on single-motor toys), Eclipse's two motors with the stop + 300 ms
pause the firmware needs when the running motor changes, Ember heat
(B0 04, low/high), battery (B0 00 → byte 5), and all 13 model names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Velvet toys only take write-without-response, and back-to-back frames are
dropped. Writes now go through a pacer: 60 ms between frames, 250 ms after
a heat frame (Ember lost a motor stop sent 60 ms after heat-off; 200 ms
worked), latest-only per channel, motor first. The first frame of a burst
still goes out directly so a stop before disconnect lands. Replaces the
heat re-send workaround. Hardware-tested 18 Oct on Pixie, Eclipse, Ember.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Aurora ignored strength changes with the level in both motor bytes; with
motor 1 only (as Cupido sends) it steps 30/70/100 and 100/70/50/30 on
hardware (18 Oct).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@CLAassistant

CLAassistant commented Nov 3, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@blackspherefollower blackspherefollower left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, this isn't far off, but the message staggering shouldn't be in the protocol.

busy: AtomicBool,
}

impl Pacer {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a far more general issue we have with a number of brand's devices, and I'd rather see a general fix. @qdot what's your take?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved out of the protocol. The spacing now lives in the device task (b8224be), driven by message_gap_ms. Details in the comment below.

- VR-Aurora
name: Velvet Aurora
features:
- description: suction

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suction vibrate, or constrict?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Air pulse: the motor drives pulsed suction rather than holding pressure, so we kept it as vibrate and changed the description to "suction (air pulse)".

communication:
- btle:
names:
- VR-*

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this wildcard is far too wide: I can imagine this picking up misc VR hardware.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed, replaced with the 13 model names.

velvetrituals and others added 4 commits November 9, 2026 16:00
VR-* is wide enough to catch unrelated hardware (cheap BLE VR remotes
advertise as VR-BOX). List each model instead. Aurora's feature is
described as suction (air pulse): its motor drives pulsed suction, so it
stays a vibrate output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With message_gap_ms set, the device task batches commands per window but
then writes the whole batch back to back, and an acknowledged (stop)
flush can follow the previous write immediately. Some firmware drops a
frame that arrives right after another one, so a batch with writes for
two features loses one. Keep writes at least the message gap apart,
within a flush and across flushes. Devices without a gap are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ConfigBaseDeviceDefinition already reads message_gap_ms per configuration
and falls back to the protocol defaults, but the schema only allowed it
under defaults, so a per-model gap failed validation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Drop the write pacer from the protocol. Spacing now comes from
message_gap_ms in velvet.yml: 60 ms for the range, 250 ms for Ember
(it needs that after a heat frame) and 300 ms for Eclipse (the pause it
needs between the zero frame and a new motor). Eclipse's motor switch
returns the zero frame and the new frame together; the zero frame has its
own command id so batching keeps it. Heat writes use the feature id, so
a stop keeps both motor-off and heat-off. Adds Eclipse and Ember device
tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@velvetrituals

Copy link
Copy Markdown
Author

Thanks for the review, @blackspherefollower. All three points are addressed in the latest commits.

Message staggering: the pacer is gone from the protocol. Spacing now comes from message_gap_ms, which the device task already supports:

  • b8224be makes the device task keep writes at least the message gap apart, both within a batch and from the previous flush (including the acknowledged stop path). Before this, a batch with writes for two features went out back to back, which is exactly what our firmware drops. Devices without a gap are unaffected. Two unit tests cover it.
  • c6b1940 lets message_gap_ms be set per configuration. ConfigBaseDeviceDefinition already read it there and fell back to the defaults; only the schema rejected it.
  • velvet.yml now uses 60 ms for the range, 250 ms for Ember and 300 ms for Eclipse. Eclipse's motor switch is now just a zero frame followed by the new frame.

@qdot the device task change is in its own commit, so it's easy to pull out or rework if you'd rather solve this another way.

Wildcard: replaced VR-* with the 13 model names. We'll send config updates ahead of new launches.

Aurora: its motor drives pulsed suction rather than holding pressure, so it stays a vibrate output. The description now says "suction (air pulse)".

Testing: test_device_protocols passes (879, including new Eclipse and Ember cases). We also re-ran the hardware checks today through a local intiface-engine build: Ember heat + stop and combined commands, and Eclipse motor switching.

Hardware: we'd be glad to send test units, for you and for IoSTIndex. We can send one of each type (Pixie for the single-motor models, Eclipse, Ember and Aurora), or the full range of 13 if that's more useful. We've joined the Buttplug Discord server as velvetrituals. DM us a shipping address there and we'll get them out.

blackspherefollower added a commit to blackspherefollower/buttplug-rs that referenced this pull request Nov 10, 2026
Some devices drop or mishandle writes that arrive back to back, which forced individual protocols (e.g. the velvet toys in buttplugio#984) to implement their own write pacing. Add a configurable per-device minimum interval between writes, enforced below the protocol layer so protocols don't need to care.

Config:
- New optional min_command_interval_ms on base definitions, protocol defaults, user customizations, ServerDeviceDefinition and its builder. It follows the same default-merging and user-config rebuild paths as message_gap_ms.
- v5 device config schema accepts the field in defaults, configurations and user config. Config version bumped to 5.72.

Enforcement (device_task.rs, wired up from device_handle.rs):
- Each device task tracks its own last-send time, so the limit is per device. Devices do not throttle each other.
- The first command after idle is sent immediately. Later commands are held and released one per interval. A newer pending command for the same channel replaces the older one.
- Stop/shutdown commands (acknowledged messages) do NOT bypass the limit. A device that cannot take back to back writes may drop a stop on one feature, which is dangerous. A stop is merged into the pending queue with the usual per-channel dedupe, skips the batching window, and is scheduled at the earliest slot the limiter allows (max(now, last_send + interval)).
- The stop ack fires only once the whole pending queue has been written, one write per interval, so callers never see an ack before every stop write has reached hardware. Without a limit configured, the ack path is unchanged (immediate flush, then ack).
- If the command channel closes while writes are still pending (e.g. during shutdown teardown), a rate limited device drains them at the paced interval instead of dumping them all at once. Unflushed stop acks are released afterwards.
- device_handle.rs still waits at most WRITE_ACK_TIMEOUT for the stop ack. A stop with many writes at a long interval can outlast that wait. The task keeps writing the queue after the caller stops waiting.
- message_gap_ms is unchanged. It is a batching window that The Handy and TCode rely on, and the two settings can be combined.

Devices:
- Set min_command_interval_ms: 50 on the IntoYou (activejoy) protocol defaults. The dual feature device drops its second command if it arrives back to back with the first.

Tests:
- device_task.rs tests cover the idle first send, spacing with latest-wins, and one-per-interval release of distinct channels.
- Stop handling tests check that a stop respects the interval and is not acked early, that a multi-channel stop is spaced and acked only after all writes, and that the teardown flush stays paced.
- Config test checks the value propagates from protocol defaults to the device definition.

Known issue: the activejoy_protocol tests fail on an existing device-name mismatch (IntoYou Remote Egg Vibrator vs IntoYou Vibrator), unrelated to this change.

Manually tested with ActiveJoy IntoYou Prostate massager and Joyhub Lach

Co-authored-by: Junie <junie@jetbrains.com>
blackspherefollower added a commit to blackspherefollower/buttplug-rs that referenced this pull request Nov 11, 2026
Some devices drop or mishandle writes that arrive back to back, which forced individual protocols (e.g. the velvet toys in buttplugio#984) to implement their own write pacing. Add a configurable per-device minimum interval between writes, enforced below the protocol layer so protocols don't need to care.

Config:
- New optional min_command_interval_ms on base definitions, protocol defaults, user customizations, ServerDeviceDefinition and its builder. It follows the same default-merging and user-config rebuild paths as message_gap_ms.
- v5 device config schema accepts the field in defaults, configurations and user config. Config version bumped to 5.72.

Enforcement (device_task.rs, wired up from device_handle.rs):
- Each device task tracks its own last-send time, so the limit is per device. Devices do not throttle each other.
- The first command after idle is sent immediately. Later commands are held and released one per interval. A newer pending command for the same channel replaces the older one.
- Stop/shutdown commands (acknowledged messages) do NOT bypass the limit. A device that cannot take back to back writes may drop a stop on one feature, which is dangerous. A stop is merged into the pending queue with the usual per-channel dedupe, skips the batching window, and is scheduled at the earliest slot the limiter allows (max(now, last_send + interval)).
- The stop ack fires only once the whole pending queue has been written, one write per interval, so callers never see an ack before every stop write has reached hardware. Without a limit configured, the ack path is unchanged (immediate flush, then ack).
- If the command channel closes while writes are still pending (e.g. during shutdown teardown), a rate limited device drains them at the paced interval instead of dumping them all at once. Unflushed stop acks are released afterwards.
- device_handle.rs still waits at most WRITE_ACK_TIMEOUT for the stop ack. A stop with many writes at a long interval can outlast that wait. The task keeps writing the queue after the caller stops waiting.
- message_gap_ms is unchanged. It is a batching window that The Handy and TCode rely on, and the two settings can be combined.

Devices:
- Set min_command_interval_ms: 50 on the IntoYou (activejoy) protocol defaults. The dual feature device drops its second command if it arrives back to back with the first.

Tests:
- device_task.rs tests cover the idle first send, spacing with latest-wins, and one-per-interval release of distinct channels.
- Stop handling tests check that a stop respects the interval and is not acked early, that a multi-channel stop is spaced and acked only after all writes, and that the teardown flush stays paced.
- Config test checks the value propagates from protocol defaults to the device definition.

Known issue: the activejoy_protocol tests fail on an existing device-name mismatch (IntoYou Remote Egg Vibrator vs IntoYou Vibrator), unrelated to this change.

Manually tested with ActiveJoy IntoYou Prostate massager and Joyhub Lach

Co-authored-by: Junie <junie@jetbrains.com>
blackspherefollower added a commit to blackspherefollower/buttplug-rs that referenced this pull request Nov 16, 2026
Some devices drop or mishandle writes that arrive back to back, which forced individual protocols (e.g. the velvet toys in buttplugio#984) to implement their own write pacing. Add a configurable per-device minimum interval between writes, enforced below the protocol layer so protocols don't need to care.

Config:
- New optional min_command_interval_ms on base definitions, protocol defaults, user customizations, ServerDeviceDefinition and its builder. It follows the same default-merging and user-config rebuild paths as message_gap_ms.
- v5 device config schema accepts the field in defaults, configurations and user config. Config version bumped to 5.72.

Enforcement (device_task.rs, wired up from device_handle.rs):
- Each device task tracks its own last-send time, so the limit is per device. Devices do not throttle each other.
- The first command after idle is sent immediately. Later commands are held and released one per interval. A newer pending command for the same channel replaces the older one.
- Stop/shutdown commands (acknowledged messages) do NOT bypass the limit. A device that cannot take back to back writes may drop a stop on one feature, which is dangerous. A stop is merged into the pending queue with the usual per-channel dedupe, skips the batching window, and is scheduled at the earliest slot the limiter allows (max(now, last_send + interval)).
- The stop ack fires only once the whole pending queue has been written, one write per interval, so callers never see an ack before every stop write has reached hardware. Without a limit configured, the ack path is unchanged (immediate flush, then ack).
- If the command channel closes while writes are still pending (e.g. during shutdown teardown), a rate limited device drains them at the paced interval instead of dumping them all at once. Unflushed stop acks are released afterwards.
- device_handle.rs still waits at most WRITE_ACK_TIMEOUT for the stop ack. A stop with many writes at a long interval can outlast that wait. The task keeps writing the queue after the caller stops waiting.
- message_gap_ms is unchanged. It is a batching window that The Handy and TCode rely on, and the two settings can be combined.

Devices:
- Set min_command_interval_ms: 50 on the IntoYou (activejoy) protocol defaults. The dual feature device drops its second command if it arrives back to back with the first.

Tests:
- device_task.rs tests cover the idle first send, spacing with latest-wins, and one-per-interval release of distinct channels.
- Stop handling tests check that a stop respects the interval and is not acked early, that a multi-channel stop is spaced and acked only after all writes, and that the teardown flush stays paced.
- Config test checks the value propagates from protocol defaults to the device definition.

Known issue: the activejoy_protocol tests fail on an existing device-name mismatch (IntoYou Remote Egg Vibrator vs IntoYou Vibrator), unrelated to this change.

Manually tested with ActiveJoy IntoYou Prostate massager and Joyhub Lach

Co-authored-by: Junie <junie@jetbrains.com>
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.

Device support: Velvet Rituals toys (VR-*), Cupido-family firmware

3 participants