Device support: Yiciyuan YCY-FJB-01 (cup, JieLi SoC)

[SanJerry007]

Per CONTRIBUTING in CLAUDE.md, filing this issue before submitting a PR.

Device

Yiciyuan FJB-01 (役次元): white gen-2 BLE-controlled stroker built on a JieLi SoC.

• Adv name: YCY-FJB-01
• MAC pattern: 0C:A5:E2:* (JieLi OUI)
• Adv service UUID: 0xFF40
• Mfr data magic: JLAISDK (JieLi AI SDK)
• Product listing: sold on the official 役次元 site / Taobao under "FJB-01"

This is the cup, not the DG-LAB powerbox clone — addressing the question left open in #688. Stroke is an oscillating linear actuator (back-and-forth motion driven by 0..=0x14 level on a single byte), plus two separate vibration motors.

Why now

PR #688 attempted to add support for this vendor in 2024 and was closed in April 2026 for inactivity — CLA was signed but the reviewer's questions (oscillate vs vibrate? product link? full test coverage?) were never answered. I've reverse-engineered the protocol independently and have a working implementation ready that addresses each of those points.

Protocol (verified against firmware reporting 02 07 07)

GATT layout:

Service	Char	UUID	Properties
0xFF40	cmd in	0000ff41-0000-1000-8000-00805f9b34fb	write, write-without-response
0xFF40	status out	0000ff42-0000-1000-8000-00805f9b34fb	read, notify

Control packet (always 16 bytes):

[0] 0x35       vendor magic
[1] 0x12       "set motor levels" sub-command
[2] stroke     0..=0x14 — linear oscillation
[3] vibe       0..=0x14 — vibration motor
[4] axis_c     0..=0x14 — third haptic motor (driven by app patterns)
[5..15] 0x00   reserved

Battery push arrives unprompted on the notify char as 35 13 01 <pct>, mixed with 10 Hz uptime ticks (35 14 ..) we filter out by prefix.

Buttplug v4 mapping

Index	Description	OutputType	Range
0	stroke	Oscillate	0..=100
1	vibe	Vibrate	0..=100
2	axis_c	Vibrate	0..=100
3	battery	Input::Battery (Read + Subscribe)	0..=100

Same shape as Galaku G317 / TFF1 (oscillate + 2×vibrate + battery), so the data model is already proven in tree.

Implementation status

Done and locally verified — branch SanJerry007/buttplug:add-yiciyuan-fjb-01:

• device-config-v4/protocols/yiciyuan.yml
• protocol_impl/yiciyuan.rs (atomic per-axis state, single 16-byte frame per call, prefix-filtered battery read)
• device_test_case/test_yiciyuan_protocol.yaml (Scalar/Stop gated on v3+ since v0–v2 single-axis Vibrate semantics don't map cleanly to a multi-actuator device)
• Test case registered in all 10 test_device_protocols slots (v0–v4 × embedded/json)
• cargo test -p buttplug_tests --test test_device_protocols → 818/818 pass
• cargo build → clean (no new warnings)
• CLA already signed on prior account

Happy to open the PR if this is welcome. ~470 lines, 7 files (+2 build artifacts: regenerated config JSON + minor version bump). No regressions, no changes to unrelated files.

Future incremental work (separately, if desired)

• Reverse-direction stroke (firmware accepts signed -20..+20 on byte 2; out of scope for this PR — Buttplug's Oscillate is unsigned)
• Additional model identifiers as they appear (currently only FJB-01 is verified; the YAML structure makes adding more straightforward)

[SanJerry007]

Update — broadened the scope to FJB-02; documenting the rest of the family

Walked through the official app's app-service.js source to map out Yiciyuan's other BLE devices. Below is the full device matrix for anyone evaluating the PR. The branch SanJerry007:add-yiciyuan-fjb-01 now covers FJB-01 + FJB-02 (828/828 tests pass).

Device matrix

Adv name	Vuex namespace	Packet format	Status in this PR	Notes
YCY-FJB-01	bt_os_fjb	35 12 stroke vibe axis_c (5-byte short write; firmware accepts 16-byte zero-padded)	Added, hardware-verified	Reverse-engineered against firmware 02 07 07
YCY-FJB-02	bt_os_fjb	Identical	Added based on shared source path; needs an FJB-02 owner for hardware confirmation	App code: identical control flow, same UUIDs, same hex frame
YCY-FJB-03	bt_os_fjb	35 12 s v a + 1-byte checksum; stroke range 0..=40 (double the others)	Deferred	Different packet format + range. Would need a separate config entry, range mapping, and checksum routine — better as a follow-up
YS-TD-01 / -02 / -03	bt_os_td	Goes through _ble_write_os_td; appears to use the same 35 12 ... 5-byte format but a separate vuex slot	Deferred	"TD" sub-family — possibly a timer-equipped variant. No hardware available to confirm
YCY-PJ-01	bt_os (shared)	10 hex chars (5 bytes) with model-specific handling	Deferred	Same code branch as FJB-03 ((i+Array(10).join("0")).slice(0,10)) but no checksum
YS0x lock (YS01/02/03)	separate code	AES-128-ECB with per-device key derived from _tp_uni_jm(my, vuex_token)	Out of scope	No Unlock / Solenoid OutputType in Buttplug v4 — discussed at #688
YISK-003V3 pump	bt_pump	35 12 cut air water (4 bytes, plaintext)	Out of scope	Could be a separate PR as Constrict (cf. galaku-pump.yml) if there's appetite
YISKJ-003V2 pump	bt_pump	BF 0F A0 XX ... AES-128 with hard-coded key F638BC9CFA477480AB3242F6B04557A1	Out of scope	Same — separate PR if welcome
Yiciyuan electro device (model unknown)	vuex_ele_* via mixins/ele.js	35 11 ... waveform format, plaintext	Out of scope	E-stim — noted from prior #688 thread that Buttplug doesn't ship support for these

Why FJB-02 is safe to include

App-level evidence (from the decompiled app-service.js):

• Same vuex_bt_os_fjb vuex namespace
• Same _ble_write_os_fjb function (no model-specific branches for FJB-02)
• Same BLE service 0xFF40 + write 0xFF41 + notify 0xFF42
• Identical hex-stringed motor frame construction
• FJB-03 is the ONLY model in that family with an explicit if(localName == "YCY-FJB-03") special case

So the new config block lists both identifiers under the same defaults; both share yiciyuan.rs. If a maintainer prefers to keep FJB-02 out until hardware-verified, removing the two lines is trivial.

Open questions for the reviewer

1. OK to land FJB-01 + FJB-02 together, or would you prefer FJB-02 deferred until hardware-verified?
2. If the pump variants are welcome as a Constrict actuator, I can prepare a follow-up PR (same reverse-engineering pedigree).
3. Anything else needed before I open the PR — squashed/merged history preference, additional test coverage, etc?