Metadata-Version: 2.4
Name: honeyplaybox-opensdk
Version: 1.0.3
Summary: Python SDK for discovering, connecting, and controlling HoneyPlayBox toys.
Author: HoneyPlayBox
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: bleak>=0.22
Requires-Dist: hidapi>=0.14
Provides-Extra: ble
Requires-Dist: bleak>=0.22; extra == "ble"
Provides-Extra: hid
Requires-Dist: hidapi>=0.14; extra == "hid"

# HoneyPlayBox Python SDK

An asynchronous Python SDK for discovering, connecting, and controlling
HoneyPlayBox toys over BLE or USB HID. Send commands, manage per-device queues,
play Funscript files, and receive battery and sensor feedback. Python-style
methods and JavaScript-style aliases are available.

The SDK provides exactly two connection types: BLE and USB HID.

## Requirements

- Python 3.11 or later.
- A supported toy and a Bluetooth adapter or compatible USB HID gateway.
- Operating-system permissions to access Bluetooth or USB devices.

## Installation

```bash
python -m pip install "honeyplaybox-opensdk==1.0.3"
```

BLE and HID dependencies are included. The import name is `honeyplaybox_sdk`.
If migrating from `honeyplaybox-sdk`, uninstall the old distribution before
installing this one because both use the same import directory.

## BLE Quick Start

This example sends a one-second vibration command to the first discovered toy.
Only send movement commands when the device is ready for testing.

```python
import asyncio
from honeyplaybox_sdk import ToyConnector


async def main():
    connector = ToyConnector()
    connector.on_feedback(
        lambda report: print(report.kind, report.value, report.unit)
    )
    toy = None
    try:
        devices = await connector.discover_devices()
        if not devices:
            print("No supported toys found.")
            return
        toy = await connector.connect_device(devices[0].toy_id)
        print("Battery:", await toy.read_battery_level())
        await toy.send_command({
            "function": "Vibrate", "value": 30, "duration": 1000,
        })
        # Keep the event loop alive while the device executes the command.
        await asyncio.sleep(1)
    finally:
        if toy is not None:
            try:
                await toy.stop_command()
            finally:
                await toy.disconnect()


asyncio.run(main())
```

## USB HID Quick Start

Opening the USB gateway does not connect a toy or send movement commands.
Scan and connect the selected toy before using its methods.

```python
import asyncio
from honeyplaybox_sdk import HIDToyConnector


async def main():
    connector = HIDToyConnector()
    connector.on_feedback(
        lambda report: print(report.kind, report.value, report.unit)
    )
    try:
        await connector.connect_hid()
        devices = await connector.scan()
        if not devices:
            print("No supported toys found.")
            return
        toy = await connector.connect_device(devices[0].toy_id)
        print("Battery:", await toy.read_battery_level())
        # Keep receiving feedback until the application finishes.
        await asyncio.sleep(10)
    finally:
        await connector.close()


asyncio.run(main())
```

For multiple gateways, use `await connector.enumerate_adapters()` and select
one with `HIDToyConnector(path=adapter["path"])`.

## Commands and Queues

The following snippets assume a connected `toy` and run inside an async
function. Supported functions depend on the device.

```python
# Immediate execution.
toy.set_command_mode("normal")
await toy.send_command({
    "function": "Vibrate", "value": 30, "duration": 1000,
})

# Enqueueing returns without waiting for execution to complete.
toy.on_queue_change(lambda event: print(event["action"], event["queue"]))
toy.set_command_mode("queue")
receipt = await toy.send_command({
    "function": "Vibrate", "value": 50, "duration": 1000,
})
print(receipt.status, receipt.command_id)
```

Use `get_command_queue()`, `remove_command(command_id)`, and
`clear_command_queue()` to manage pending entries. Use
`await toy.stop_command()` to explicitly stop device output. Disconnecting
clears the device queue.

## Funscript Playback

Load a dictionary, JSON text, a local file, or an HTTP/HTTPS URL. Replace
`<FUNSCRIPT_FILE>` with the file path in your application environment.

```python
toy.on_funscript_state(lambda state: print(state["state"], state["progress"]))
await toy.load_funscript("<FUNSCRIPT_FILE>")
await toy.start_funscript()
```

Keep the application's event loop alive during playback. Controls include
pause, resume, stop, restart, seek, jump, playback rate, and time synchronization.
Compatible multi-track Funscript files are supported.

## Feedback

Subscribe through `connector.on_feedback(callback)` to receive battery and
supported sensor reports, including pressure, depth, temperature, steps, and
acceleration. Available reports depend on the toy and firmware.

Callbacks deliver feedback to your application; the SDK does not upload these
reports to a server. Explicit battery reads refresh the device reading.

## SDK Documentation

Visit [HoneyPlayBox Developer](https://developer.honeyplaybox.com/docs?nav=python-sdk-nav.json#python-sdk-overview) for SDK
documentation and integration resources.

