triki-library 0.1__py3-none-any.whl

triki/__init__.py

@@ -0,0 +1,21 @@
+from .controller import TRIKIController
+from .scanner import TRIKIScanner
+from .types import TRIKIDevice
+from .exceptions import (
+    TRIKIError,
+    TRIKIConnectionError,
+    TRIKIDeviceNotFoundError,
+    TRIKINotConnectedError,
+)
+
+__version__ = "0.1"
+
+__all__ = [
+    "TRIKIController",
+    "TRIKIScanner",
+    "TRIKIDevice",
+    "TRIKIError",
+    "TRIKIConnectionError",
+    "TRIKIDeviceNotFoundError",
+    "TRIKINotConnectedError",
+]

triki/controller.py

@@ -0,0 +1,197 @@
+import bleak.exc
+from bleak import BleakClient
+
+from .exceptions import TRIKIDeviceNotFoundError, TRIKINotConnectedError, TRIKIConnectionError
+
+UART_RX_UUID = "6e400002-b5a3-f393-e0a9-e50e24dcca9e"
+UART_TX_UUID = "6e400003-b5a3-f393-e0a9-e50e24dcca9e"
+BATTERY_LEVEL_UUID = "00002a19-0000-1000-8000-00805f9b34fb"
+LED_CHARACTERISTIC_UUID = "6e400004-b5a3-f393-e0a9-e50e24dcca9e"
+START_STREAM_COMMAND = bytes.fromhex("20 10 00 d0 07 34 00 03")
+
+
+class TRIKIController:
+    """
+    Base class for the TRIKI controller
+
+    Args:
+        address:
+            Device Bluetooth address
+    """
+    __device_client: BleakClient = None
+    __bt_address: str = "AA:BB:CC:DD:EE:FF"
+    __battery_level: int = 0
+    __sensor_spin_x: int = 0
+    __sensor_spin_y: int = 0
+    __sensor_turn_z: int = 0
+    __sensor_tilt_x: int = 0
+    __sensor_tilt_y: int = 0
+    __sensor_flip_z: int = 0
+    __button_pressed: bool = False
+
+    def __init__(self, address: str) -> None:
+        self.__bt_address = address
+
+    def __little_endian(self, a: int, b: int) -> int:
+        """Parse data by using a little endian algorithm"""
+        x = a + (b * 256)
+        if x > 32767:
+            x -= 65536
+        return x
+
+    def __parse_received_data(self, sender, data: bytearray) -> None:
+        """Parse data when received"""
+        if len(data) >= 16 and data[0] == 0x22:
+            data_sliced = data.hex(" ").split(" ")
+            data_decimal = []
+            for i in range(len(data_sliced)):
+                data_decimal.append(int(data_sliced[i], 16))
+
+            self.__sensor_spin_x = self.__little_endian(data_decimal[2], data_decimal[3])
+            self.__sensor_spin_y = self.__little_endian(data_decimal[4], data_decimal[5])
+            self.__sensor_turn_z = self.__little_endian(data_decimal[6], data_decimal[7])
+            self.__sensor_tilt_x = self.__little_endian(data_decimal[8], data_decimal[9])
+            self.__sensor_tilt_y = self.__little_endian(data_decimal[10], data_decimal[11])
+            self.__sensor_flip_z = self.__little_endian(data_decimal[12], data_decimal[13])
+
+            self.__button_pressed = data_decimal[15] == 1
+
+    async def connect(self, raise_exception_on_fail: bool = False) -> None:
+        """Connect to the TRIKI controller"""
+        self.__device_client = BleakClient(self.__bt_address, timeout=10)
+        try:
+            await self.__device_client.connect()
+        except bleak.exc.BleakDeviceNotFoundError as error:
+            if raise_exception_on_fail:
+                raise TRIKIDeviceNotFoundError(
+                    f"TRIKI device with address {self.__bt_address} was not found"
+                ) from error
+        except bleak.exc.BleakError as error:
+            if raise_exception_on_fail:
+                raise TRIKIConnectionError(
+                    f"Connection with TRIKI device (at {self.__bt_address}) failed"
+                ) from error
+
+        if self.__device_client.is_connected:
+            try:
+                battery_data = await self.__device_client.read_gatt_char(BATTERY_LEVEL_UUID)
+                self.__battery_level = int(battery_data[0])
+
+                await self.__device_client.start_notify(UART_TX_UUID, self.__parse_received_data)
+
+                await self.__device_client.write_gatt_char(
+                    UART_RX_UUID, START_STREAM_COMMAND, response=True
+                )
+            except bleak.exc.BleakError as error:
+                raise TRIKIConnectionError(
+                    f"Connected to the TRIKI device (at {self.__bt_address}), but initialization failed"
+                ) from error
+        else:
+            raise TRIKIConnectionError(
+                f"Connection with TRIKI device (at {self.__bt_address}) failed"
+            )
+
+    async def disconnect(self) -> None:
+        """Disconnect from the TRIKI device"""
+        if self.__device_client is not None and self.__device_client.is_connected:
+            await self.toggle_led(False)
+            await self.__device_client.disconnect()
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if the TRIKI controller is connected"""
+        return self.__device_client is not None and self.__device_client.is_connected
+
+    @property
+    def battery_level(self) -> int:
+        """Get the TRIKI controller battery level"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read battery_level, because the TRIKI controller is not connected"
+            )
+        return self.__battery_level
+
+    @property
+    def spin_x(self) -> int:
+        """Get the TRIKI controller X Spin value"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read spin_x, because the TRIKI controller is not connected"
+            )
+        return self.__sensor_spin_x
+
+    @property
+    def spin_y(self) -> int:
+        """Get the TRIKI controller Y Spin value"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read spin_y, because the TRIKI controller is not connected"
+            )
+        return self.__sensor_spin_y
+
+    @property
+    def turn_z(self) -> int:
+        """Get the TRIKI controller Z Turn value"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read turn_z, because the TRIKI controller is not connected"
+            )
+        return self.__sensor_turn_z
+
+    @property
+    def tilt_x(self) -> int:
+        """Get the TRIKI controller X Tilt value"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read tilt_x, because the TRIKI controller is not connected"
+            )
+        return self.__sensor_tilt_x
+
+    @property
+    def tilt_y(self) -> int:
+        """Get the TRIKI controller Y Tilt value"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read tilt_y, because the TRIKI controller is not connected"
+            )
+        return self.__sensor_tilt_y
+
+    @property
+    def flip_z(self) -> int:
+        """Get the TRIKI controller Z Flip value"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read flip_z, because the TRIKI controller is not connected"
+            )
+        return self.__sensor_flip_z
+
+    @property
+    def button_pressed(self) -> bool:
+        """Check if the TRIKI controller button is pressed"""
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot read button_pressed, because the TRIKI controller is not connected"
+            )
+        return self.__button_pressed
+
+    async def toggle_led(self, is_on: bool) -> None:
+        """
+        Toggle the TRIKI controller built-in LED light
+
+        Args:
+            is_on:
+                Set the LED status
+        """
+        if not self.is_connected:
+            raise TRIKINotConnectedError(
+                "Cannot toggle LED, because the TRIKI controller is not connected"
+            )
+
+        if is_on:
+            bytes_to_send = bytes([0x01])
+        else:
+            bytes_to_send = bytes([0x00])
+
+        await self.__device_client.write_gatt_char(
+            LED_CHARACTERISTIC_UUID, bytes_to_send, response=True
+        )

triki/exceptions.py

@@ -0,0 +1,14 @@
+class TRIKIError(Exception):
+    """Base exception for triki errors."""
+
+
+class TRIKIConnectionError(TRIKIError):
+    """Raised when connection to a TRIKI device fails."""
+
+
+class TRIKIDeviceNotFoundError(TRIKIError):
+    """Raised when a TRIKI device cannot be found."""
+
+
+class TRIKINotConnectedError(TRIKIError):
+    """Raised when called operation requires a connected TRIKI device."""

triki/scanner.py

@@ -0,0 +1,27 @@
+from bleak import BleakScanner, BLEDevice
+from .types import TRIKIDevice
+
+
+class TRIKIScanner:
+    """Base class for the TRIKI controller scanner"""
+    __scanner = None
+    __bleak_devices: list[BLEDevice] = []
+    __scanned_devices: list[TRIKIDevice] = []
+
+    def __init__(self) -> None:
+        self.__scanner = BleakScanner()
+
+    async def scan(self) -> None:
+        """Scan for TRIKI controllers"""
+        self.__bleak_devices = await self.__scanner.discover()
+        self.__scanned_devices.clear()
+
+        for device in self.__bleak_devices:
+            if device.name is not None and "Triki" in device.name:
+                triki_device = TRIKIDevice("Triki " + device.address[-6:], device.address)
+                self.__scanned_devices.append(triki_device)
+
+    @property
+    def scanned_devices(self) -> list[TRIKIDevice]:
+        """Scanned TRIKI controllers"""
+        return self.__scanned_devices

triki/types.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class TRIKIDevice:
+    name: str
+    address: str

triki_library-0.1.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: triki-library
+Version: 0.1
+Summary: A Python library for integrating the TRIKI motion controller (made by Caps Apps) into your projects.
+Project-URL: Homepage, https://github.com/woofter-wolf/triki-library-python
+Project-URL: Repository, https://github.com/woofter-wolf/triki-library-python
+Project-URL: Issues, https://github.com/woofter-wolf/triki-library-python
+Author: Woofter_Wolf
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,bluetooth,controller,triki
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Requires-Dist: bleak>=3.0.2
+Description-Content-Type: text/markdown
+
+# TRIKI Library
+A Python library for the integrating TRIKI motion controller (made by Caps Apps) into your projects.
+
+> This library is still in development. Some things may change sligthly.
+
+---
+
+## What is TRIKI?
+TRIKI is a Bluetooth Low Energy (BLE) motion controller that has the shape and size of a bottle cap. It is produced by Caps Apps (also known as HOPX) and sold by 'Żabka', a convenience store franchise.
+
+It was designed to be used in mini-games which are on the store's loyalty app.
+
+## Why I made this library
+I wanted to make this library to give everyone a way to integrate this niche controller into their own games, experiments and other Python projects.
+
+## Features
+- Scan for TRIKI controllers
+- Connect to TRIKI controller
+- Get battery level
+- Get IMU data from the controller
+- Get state of the built-in button
+- Control built-in LED
+
+## Platforms
+| Platform      | Does it work?       |
+|---------------|---------------------|
+| Windows 10/11 | ✅ Tested            |
+| macOS         | ❔ Untested          |
+| Linux         | ⚠️ Partially tested |
+> Linux support needs further testing. Some Arch-based distributions may have issues with receiving data.
+---
+## Installation
+```bash
+pip install triki-library
+```
+
+## Usage
+```python
+# Import the library
+import asyncio
+from triki import TRIKIScanner, TRIKIController
+```
+
+```python
+# Scan for TRIKI controllers
+scanner = TRIKIScanner()
+await scanner.scan()
+devices = scanner.scanned_devices # Returned as list[TRIKIDevice]
+
+devices[0].name # Get device name
+devices[0].address # Get device BT address
+```
+```python
+# Connect to the controller
+controller = TRIKIController("AA:BB:CC:DD:EE:FF")
+await controller.connect()
+```
+```python
+controller.is_connected # Check if device is connected
+controller.battery_level # Get battery level
+```
+```python
+controller.spin_x # Get X Spin
+controller.spin_y # Get Y Spin
+controller.turn_z # Get Z Turn
+controller.tilt_x # Get X Tilt
+controller.tilt_y # Get Y Tilt
+controller.flip_z # Get Z Flip
+```
+```python
+controller.button_pressed # Check if built-in button is pressed
+```
+```python
+#turn on LED
+await controller.toggle_led(True)
+
+#turn off LED
+await controller.toggle_led(False)
+```
+```python
+# Loop
+try:
+    while controller.is_connected:
+        # Do stuff
+finally:
+    await controller.disconnect()
+```
+```python
+# IMPORTANT: disconnect from the controller when you're done with it!
+await controller.disconnect()
+```
+>Examples can be found on the 'examples' directory.
+---
+
+## Credits
+Library made by [Woofter_Wolf](https://woofterwolf.space)
+
+Special thanks to [Wojciech "Koksny" Górny](https://koksny.com) for doing the hard work of documenting this device (look here for communication documentation): [Link](https://github.com/koksny/TRIKI-Control)
+
+## Copyright
+"TRIKI" and "Żabka" are trademarks of Żabka Polska sp. z o.o. "HOPX" is a trademark of Caps Apps sp. z o.o.
+
+This library is an independent, open-source project. It is **NOT** affiliated, endorsed or sponsored by these companies. This library ships with no software, images or any assets belonging to these companies.

triki_library-0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+triki/__init__.py,sha256=AHjiD0BA2QFSnSfpgUbRpiB2bBc0I6Th0adQHKLAk4Q,460
+triki/controller.py,sha256=7XH_JM6WffCzyuQuwLoCffbQwIIU2iNFpRwCAutEo1k,7515
+triki/exceptions.py,sha256=wwUwVGIXCudFYMTk1ItNpIiXgGg9WTjlaeCvr7w0ShQ,404
+triki/scanner.py,sha256=UZovNbsSws_bdu6-0Dxfsih_NtbJe2GrufwqYhxtwLw,944
+triki/types.py,sha256=3dcQ_ULegVH5B173x8iqKIg7AlB5n_fxKefoAR83hzU,117
+triki_library-0.1.dist-info/METADATA,sha256=E_h4T_if4z7WKrVGWk3DoJp7iIBpDo3G6xhFpwoTU1c,4106
+triki_library-0.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+triki_library-0.1.dist-info/licenses/LICENSE,sha256=p3f-kD18WHRPEDAoq1ZetdFSIO4XszzcuJ9A6cQRQCo,1083
+triki_library-0.1.dist-info/RECORD,,

triki_library-0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

triki_library-0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright © 2026 Woofter_Wolf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.