lovensepy 1.1.4

Python Lovense API client

LovensePy

LovensePy is a Python client for the Lovense developer APIs: Standard API over LAN (Game Mode) and cloud, Socket API (WebSocket, optional LAN command path), and Toy Events. Optional pieces include a Home Assistant MQTT bridge and direct BLE control.

Who it is for: developers building scripts, bots, dashboards, Home Assistant integrations, or experiments. Lovense’s official docs remain the source of truth for protocol behavior; this library wraps those flows in typed, tested Python.

Install

pip install lovensepy

Optional extras:

pip install 'lovensepy[mqtt]'   # Home Assistant MQTT bridge service + paho-mqtt; run: lovensepy-mqtt
pip install 'lovensepy[ble]'    # Direct BLE (bleak, pick for examples)

Docker Compose: Mosquitto + Home Assistant

The root docker-compose.yml starts Mosquitto and Home Assistant only. The LovensePy MQTT bridge runs on the host (BLE needs Bluetooth; LAN is simpler that way too). See compose/README.md and Home Assistant MQTT.

Minimal example (Game Mode)

from lovensepy import LANClient, Actions

client = LANClient("MyApp", "192.168.1.100", port=20011)
client.function_request({Actions.VIBRATE: 10}, time=3)

Enable Game Mode in Lovense Remote, use the app host’s IP, and pick the right port (e.g. 20011 for Remote, 34567 for Connect). Full setup, tutorials, and API tables are on GitHub Pages (or browse the docs folder in the repository).

For async/await code, AsyncLANClient, AsyncServerClient, BleDirectHub, and BleDirectClient all subclass LovenseAsyncControlClient: same control methods so you can switch transport by changing only construction. See Connection methods and the API reference.

How clients reach the toy

flowchart TB
    subgraph yourCode [Your app]
        LANClient
        AsyncLANClient
        ServerClient
        AsyncServerClient
        SocketAPIClient
        ToyEventsClient
        BleDirect[BleDirectClient / BleDirectHub]
        HAMqttBridge
    end

    subgraph localNet [Local network]
        RemoteApp[Lovense app]
        Toy[Lovense toy]
        MQTTBroker[MQTT broker]
    end

    subgraph cloudLayer [Lovense cloud]
        LovenseServer[Lovense server]
    end

    LANClient -->|"HTTP/HTTPS"| RemoteApp
    AsyncLANClient -->|"HTTP/HTTPS"| RemoteApp
    RemoteApp --> Toy

    ServerClient -->|"HTTPS"| LovenseServer
    AsyncServerClient -->|"HTTPS"| LovenseServer
    LovenseServer --> RemoteApp

    SocketAPIClient -->|"WebSocket"| LovenseServer
    SocketAPIClient -->|"HTTPS when use_local_commands"| RemoteApp

    ToyEventsClient -->|"WebSocket"| RemoteApp

    HAMqttBridge -->|"LAN: HTTP + Toy Events WS"| RemoteApp
    HAMqttBridge -.->|"BLE mode: direct"| Toy
    HAMqttBridge <-->|"MQTT"| MQTTBroker

    BleDirect -.->|"BLE"| Toy

Documentation and official APIs

• Project docs (site): lovensepy.koval-dev.org — source: docs/index.en.md (Russian: index.ru.md)
• Lovense Standard API
• Lovense Socket API
• Toy Events API

Changelog

See CHANGELOG.md.

License

Apache License 2.0 — see LICENSE for full text.