Yiciyuan FJB-02/FJB-03: hardware-verified corrections and runtime control

[xmsama]

Scope

Hardware-verified corrections to the Yiciyuan support introduced in #917, with FJB-03 implementation updates relative to #888. Existing BLE UUIDs and packet-format documentation are unchanged unless noted below. YS-TD models are outside this proposal.

Hardware findings

Testing was performed on physical FJB-02 and FJB-03 devices.

• FJB-02 capabilities: Device-info responses report motor A only, consistent with observed operation. Stroke and rotation are mechanically coupled under one control. Replace the inherited three-output configuration with one Oscillate output and battery input.
• FJB-03 actuator mapping: A controls coupled stroke/rotation; B controls suction (Constrict); C controls independent vibration. These functions were verified on hardware.
• FJB-03 direction encoding: Official-app hardware testing confirms opposite rotation directions on either side of its input midpoint. Combined with the signed-input encoding documented in Device support: Yiciyuan stroker family (FJB-03, YS-TD-01/02/03) #888, 1..20 and 21..40 represent opposite directions at corresponding amplitudes; 0 stops A. An unsigned 0..100 strength must not be linearly mapped across 0..40 as a single forward-speed range.
• FJB-03 vibration: Independent vibration activation was verified using 35 11 04 N checksum, rather than the C field of the live 35 12 frame. The implementation exposes seven fixed modes; activation was hardware-tested, not every mode individually.

Proposed changes

PR A — Output scheduling and stop handling

• Opt-in latest-state scheduling for FJB-02/03, with one hardware write in flight and coalescing of superseded pending state.
• Stop barriers that cannot be overwritten by later nonzero input.
• Bounded write timeouts; discard pending motion after write failure or disconnect.
• Regression tests for slow writes, stop ordering, timeout handling, and disconnection.

PR B — FJB-02/FJB-03 support and runtime rotation modes

• Correct FJB-02 capabilities and add FJB-03 model-specific control frames, checksum handling, actuator mapping, and fixed-mode vibration commands.
• Add model-specific device-info queries and retain the FF42 notification subscription.
• Add per-device forward, reverse, and alternating rotation modes without requiring changes to existing waveform clients.
• Apply mode changes between write batches, cancel the previous timer, and use a zero-command/pause transition before resuming with the latest amplitude. Configuration changes must not restart a stopped output.
• Include protocol and mode-transition tests. This implementation depends on PR A.

Validation and limitations

The local implementation passes 67 server tests and 871 device-protocol regression tests on Windows. These are suite totals, not counts of new tests. The latest runtime mode-switching implementation has passed software tests but has not yet been verified on physical hardware.

FJB-02 connection stability improved after the motherboard's external antenna was connected; that improvement is not attributed solely to software. Windows-specific connection-retry changes are excluded from these PRs.

Review requested

Approval of the two-PR scope and the server-side direction-mode design before PR submission. The companion proposal at intiface/intiface-central#287 covers configuration UI and persistence; the initial implementation remains local pending review.

[qdot]

Please put in both PRs, and we'll take a look. Thanks for following the contribution policy!

[blackspherefollower]

My biggest concerns around this particular brand is that I know they started in the estim space and without having actually had my hands on the hardware to test the devices that are being added I can't verify that we're not letting estim hardware through.

I'd happily buy hardware samples but I haven't found a Chinese forwarding service yet (the drop shippers operate at a different level to what I need). I'm really missing a pipeline for getting hardware not sold outside of China to the UK.

[xmsama]

Thanks, that's a fair concern. Here's what can be checked without the hardware.

Yiciyuan's own BLE docs separate e-stim from motor devices by service UUID. Their official open-source repo, YCY-YOKONEX/YCY-YOKONEX-OpenSource, publishes one BLE document per device family under Bluetooth/. The PDFs are in Chinese; the service UUIDs are in each document's PRIMARY_SERVICE / CHARACTERISTIC lines. Links are pinned to commit 9345b7e:

Document	Primary service	Write / Notify
E-stim gen 1 (电击器一代.pdf)	0000ff30-…	FF31 / FF32
E-stim gen 2 (电击器二代.pdf)	0000ff30-…	FF31 / FF32
Vibrator eggs & strokers (跳蛋飞机杯蓝牙通讯.pdf)	0000ff40-…	FF41 / FF42
Enema device (灌肠机一代.pdf)	0000ffb0-…	not listed

The config only covers the FF40 family. In yiciyuan.yml in #956, it matches just the names YCY-FJB-01, YCY-FJB-02 and YCY-FJB-03, and all of its endpoints are defined under ff40 (TX ff41, notify ff42). An FF30 e-stim unit has no such endpoints, so it can't be initialized by this protocol even if its advertised name collided.

GATT dumps from my FJB-02 and FJB-03 units were captured with a small read-only BLE probe script (Python/bleak). It enumerates the GATT services, subscribes to ff42, and writes only the device-info query 35 10 45; no motor commands are sent. The dumps show vendor services ff40 and ae00 only, with no ff30. The device-info replies report motors only: FJB-02 reports motor A; FJB-03 reports A (stroke/rotation), B (suction) and C (vibration). Dumps are below; repeated heartbeat notifications are trimmed.

YS-TD models from #888 remain out of scope.

FJB-03 GATT dump

{
  "tool": "YCY FJB Safe BLE Probe",
  "tool_version": "1.2.0",
  "created_at": "2026-09-24T04:00:05.436783+08:00",
  "platform": "Windows-11-10.0.26200-SP0",
  "safety": {
    "motor_commands_sent": false,
    "device_info_query_hex": "35 10 45"
  },
  "devices": [
    {
      "name": "YCY-FJB-03",
      "address_hash": "1ca0b6b56967",
      "success": true,
      "error": null,
      "advertised_service_uuids": [],
      "services": [
        {
          "uuid": "00001800-0000-1000-8000-00805f9b34fb",
          "description": "Generic Access Profile",
          "characteristics": [
            {
              "uuid": "00002a00-0000-1000-8000-00805f9b34fb",
              "properties": [
                "read"
              ],
              "descriptors": []
            },
            {
              "uuid": "00002a01-0000-1000-8000-00805f9b34fb",
              "properties": [
                "read"
              ],
              "descriptors": []
            },
            {
              "uuid": "00002a04-0000-1000-8000-00805f9b34fb",
              "properties": [
                "read"
              ],
              "descriptors": []
            }
          ]
        },
        {
          "uuid": "00001801-0000-1000-8000-00805f9b34fb",
          "description": "Generic Attribute Profile",
          "characteristics": [
            {
              "uuid": "00002a05-0000-1000-8000-00805f9b34fb",
              "properties": [
                "indicate"
              ],
              "descriptors": [
                "00002902-0000-1000-8000-00805f9b34fb"
              ]
            }
          ]
        },
        {
          "uuid": "0000ff40-0000-1000-8000-00805f9b34fb",
          "description": "Vendor specific",
          "characteristics": [
            {
              "uuid": "0000ff41-0000-1000-8000-00805f9b34fb",
              "properties": [
                "write-without-response"
              ],
              "descriptors": []
            },
            {
              "uuid": "0000ff42-0000-1000-8000-00805f9b34fb",
              "properties": [
                "notify"
              ],
              "descriptors": [
                "00002902-0000-1000-8000-00805f9b34fb"
              ]
            }
          ]
        },
        {
          "uuid": "0000ae00-0000-1000-8000-00805f9b34fb",
          "description": "Vendor specific",
          "characteristics": [
            {
              "uuid": "0000ae01-0000-1000-8000-00805f9b34fb",
              "properties": [
                "write-without-response"
              ],
              "descriptors": []
            },
            {
              "uuid": "0000ae02-0000-1000-8000-00805f9b34fb",
              "properties": [
                "notify"
              ],
              "descriptors": [
                "00002902-0000-1000-8000-00805f9b34fb"
              ]
            }
          ]
        }
      ],
      "notifications_hex": [
        "35 14 49",
        "35 10 01 00 07 07 07 00 00 5B",
        "35 14 49",
        "35 14 49",
        "... (28 more heartbeat notifications omitted)"
      ],
      "reads_hex": [],
      "device_info": {
        "type": "device_info",
        "product_id": 1,
        "product_version": 0,
        "motor_a_mode_count": 7,
        "motor_b_mode_count": 7,
        "motor_c_mode_count": 7,
        "raw_hex": "35 10 01 00 07 07 07 00 00 5B"
      },
      "battery_percent": null,
      "protocol_match": true,
      "pairing_attempted": false
    }
  ]
}

FJB-02 GATT dump

{
  "tool": "YCY FJB Safe BLE Probe",
  "tool_version": "1.2.0",
  "created_at": "2026-09-24T04:05:14.944528+08:00",
  "platform": "Windows-11-10.0.26200-SP0",
  "safety": {
    "motor_commands_sent": false,
    "device_info_query_hex": "35 10 45"
  },
  "devices": [
    {
      "name": "YCY-FJB-02",
      "address_hash": "2a517dc04244",
      "success": true,
      "error": null,
      "advertised_service_uuids": [
        "0000ff40-0000-1000-8000-00805f9b34fb"
      ],
      "services": [
        {
          "uuid": "00001800-0000-1000-8000-00805f9b34fb",
          "description": "Generic Access Profile",
          "characteristics": [
            {
              "uuid": "00002a00-0000-1000-8000-00805f9b34fb",
              "properties": [
                "read",
                "write"
              ],
              "descriptors": []
            }
          ]
        },
        {
          "uuid": "0000ff40-0000-1000-8000-00805f9b34fb",
          "description": "Vendor specific",
          "characteristics": [
            {
              "uuid": "0000ff41-0000-1000-8000-00805f9b34fb",
              "properties": [
                "write",
                "write-without-response"
              ],
              "descriptors": []
            },
            {
              "uuid": "0000ff42-0000-1000-8000-00805f9b34fb",
              "properties": [
                "notify",
                "read"
              ],
              "descriptors": [
                "00002902-0000-1000-8000-00805f9b34fb"
              ]
            }
          ]
        },
        {
          "uuid": "0000ae00-0000-1000-8000-00805f9b34fb",
          "description": "Vendor specific",
          "characteristics": [
            {
              "uuid": "0000ae01-0000-1000-8000-00805f9b34fb",
              "properties": [
                "write-without-response"
              ],
              "descriptors": []
            },
            {
              "uuid": "0000ae02-0000-1000-8000-00805f9b34fb",
              "properties": [
                "notify"
              ],
              "descriptors": [
                "00002902-0000-1000-8000-00805f9b34fb"
              ]
            }
          ]
        }
      ],
      "notifications_hex": [
        "35 14 00 EF",
        "35 13 01 5A A3",
        "35 10 05 02 08 00 00 00 00 54",
        "35 14 00 F0",
        "35 14 00 F1",
        "... (31 more heartbeat notifications omitted)"
      ],
      "reads_hex": [
        ""
      ],
      "device_info": {
        "type": "device_info",
        "product_id": 5,
        "product_version": 2,
        "motor_a_mode_count": 8,
        "motor_b_mode_count": 0,
        "motor_c_mode_count": 0,
        "raw_hex": "35 10 05 02 08 00 00 00 00 54"
      },
      "battery_percent": 80,
      "protocol_match": true,
      "pairing_attempted": false
    }
  ]
}