tap-python-sdk 0.7.0__py3-none-any.whl

tap_python_sdk-0.7.0.dist-info/METADATA

@@ -0,0 +1,403 @@
+Metadata-Version: 2.4
+Name: tap-python-sdk
+Version: 0.7.0
+Summary: Tap strap python sdk
+Home-page: https://github.com/TapWithUs/tap-python-sdk
+Author: Tap systems Inc.
+Author-email: support@tapwithus.com
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bleak==0.6.4; platform_system == "Linux"
+Requires-Dist: bleak==0.12.1; platform_system == "Darwin"
+Requires-Dist: bleak==0.22.3; platform_system == "Windows"
+Requires-Dist: bleak-winrt==1.2.0; platform_system == "Windows"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: flake8; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+
+## TapStrap Python SDK (beta)
+
+### What Is This ?
+
+TAP python SDK allows you to build python app that can establish BLE connection with Tap Strap and TapXR, send commands and receive events and data - Thus allowing TAP to act as a controller for your app!  
+The library is developed with Python >= 3.9 and is **currently in beta**.
+
+
+### Supported Platforms
+This package supports the following platforms:
+* MacOS (tested on 10.15.2) - using Apple's CoreBluetooth library. The library depends on PyObjC which Apple includes with their Python version on OSX. Note that if you're using a different Python, be sure to install PyObjC for that version of Python.  
+* Windows 10 - using [Bleak](https://github.com/hbldh/bleak) with WinRT for BLE connectivity (no external DLL required).
+* Linux (tested on Ubuntu 18.04) - need to install libbluetooth-dev and bluez-tools
+    ```
+    sudo apt-get install bluez-tools libbluetooth-dev
+    ```
+    also the user needs to be in the bluetooth group:
+    ```
+    sudo usermod -G bluetooth -a <username>
+    #and can reload groups in this shell by running the following command or by logging out and back in:
+    su - $USER
+    ```
+
+
+### Installation
+
+Install the package from PyPI:
+```console
+pip install tap-python-sdk
+```
+
+Or clone this repo and install the package locally:
+```console
+git clone https://github.com/TapWithUs/tap-python-sdk
+cd tap-python-sdk
+pip install .
+```
+
+
+The SDK is asyncio-based. Pair your Tap device with the OS first, then connect and register callbacks inside an async entry point:
+
+```python
+import asyncio
+from tapsdk import TapSDK
+
+async def main():
+    tap_device = TapSDK()
+    tap_device.register_tap_events(lambda identifier, tapcode: print(identifier, tapcode))
+    await tap_device.run()  # connects to a paired Tap, or scans until one is found
+
+asyncio.run(main())
+```
+
+If no Tap is already connected at the OS level, `run()` will scan and wait for a device. On Windows and MacOS it also polls for already-paired devices that reconnect without advertising.
+
+Also make sure that you have updated your Tap device to the latest version.
+
+### Features
+
+This SDK implements two basic interfaces with a Tap device.
+
+First is setting the operation mode:
+
+1. *Text mode* - the Tap device will operate normally, with no events being sent to the SDK
+2. *Controller mode* - the Tap device will send events to the SDK
+3. *Controller and Text mode* - the Tap device will operate normally, in parallel with sending events to the SDK
+4. *Raw data mode* - the Tap device will stream raw sensors data to the SDK.
+
+Second, subscribing to the following events:
+
+1. *Tap event* - whenever a tap event has occurred
+2. *Mouse event* - whenever a mouse movement has occurred
+3. *AirGesture event* - whenever one of the gestures is detected
+4. *Raw data* - whenever new raw data sample is being made.
+
+Additional to these functional events, there are also some state events, such as connection and disconnection of Tap devices to the SDK backend.
+
+#### Spatial Control - NEW
+Authorized developers can gain access to the experimental Spatial Control features:
+1. Extended AirGesture state - enabling aggregation for pinch, drag and swipe gestures.
+2. Select input type - enabling the selection of input type to be activated - i.e. AirMouse/Tapping. 
+
+These features are only available on TapXR and only for qualified developers. Request access [here](https://www.tapwithus.com/contact-us/)
+
+
+### Migration from 0.6.x
+
+If you are upgrading from an earlier release, note these breaking changes:
+
+* `TapInputMode("controller")` → `InputModeController()` (and similarly for other modes). Import from `tapsdk`.
+* `TapInputMode("raw", sensitivity=[2, 1, 4])` → `InputModeRaw(finger_accl_sens=..., imu_gyro_sens=..., imu_accl_sens=...)`. Use the typed enums in `tapsdk.enumerations`.
+* `from tapsdk.models import AirGestures` → `from tapsdk import AirGestures`
+* The `loop=` constructor argument has been removed.
+* Event registration (`register_*`) is synchronous; call it before `await tap_device.run()`.
+* Commands (`set_input_mode`, `set_input_type`, `send_vibration_sequence`) are async and must be awaited.
+* OS-specific examples (`example_unix.py`, `example_win.py`) have been replaced by a single cross-platform `examples/basic.py`.
+
+
+### High level API
+The SDK uses callbacks to implement user functions on the various events. To register a callback, you just have to instance a TapSDK object and:
+
+```python
+def on_tap_event(identifier, tapcode):
+    print(identifier + " tapped " + str(tapcode))
+
+tap_device.register_tap_events(on_tap_event)
+```
+#### Commands list
+1. ```set_input_mode(self, input_mode:InputMode, identifier=None):```
+This function sends a mode selection command. It accepts an object of type ```InputMode``` such as ```InputModeText```, ```InputModeController```, ```InputModeControllerText```, or ```InputModeRaw```.  
+For example:
+    ```python
+    from tapsdk import InputModeController
+    await tap_device.set_input_mode(InputModeController())
+    ```  
+    For raw sensors mode, you can specify sensitivity and scaling:
+    ```python
+    from tapsdk import InputModeRaw
+    from tapsdk.enumerations import FingerAcclSensitivity, ImuGyroSensitivity, ImuAcclSensitivity
+    await tap_device.set_input_mode(InputModeRaw(
+        scaled=True,
+        finger_accl_sens=FingerAcclSensitivity.G4,
+        imu_gyro_sens=ImuGyroSensitivity.DPS250,
+        imu_accl_sens=ImuAcclSensitivity.G4
+    ))
+    ```
+2. ```set_input_type(self, input_type:InputType, identifier=None):```   
+    > **Only for TapXR and with Spatial Control experimental firmware**
+
+    This function sends a command to force input type. It accepts an enum of type ```InputType``` initialized with any of the types ```InputType.MOUSE```, ```InputType.KEYBOARD```, or ```InputType.AUTO```.  
+    For example:
+    ```python
+    from tapsdk import InputType
+    await tap_device.set_input_type(InputType.AUTO)
+    ```  
+    This will set the input to be automatically selected by the Tap device, based on hand posture.
+
+3. ```send_vibration_sequence(self, sequence:list, identifier=None):```
+This function sends a series of haptic activations. ```sequence``` is a list of integers indicating the activation and delay periods one after another. The periods are in millisecond units, in the range of [10,2550] and in resolution of 10ms. Each haptic command supports up to 18 period definitions (i.e. 9 haptics + delay pairs).  
+For example: 
+    ```python 
+    await tap_device.send_vibration_sequence(sequence=[1000,300,200])
+    ```  
+    will trigger a 1s haptic, followed by 300ms delay, followed by 200ms haptic.
+
+
+#### Events list
+1. ```register_connection_events(self, listener:Callable):```  
+Register callback to a Tap strap connection event.
+    ```python
+    def on_connect(tap_sdk_instance):
+        print("Connected to Tap device")
+
+    tap_device.register_connection_events(on_connect)
+    ``` 
+
+2. ```register_disconnection_events(self, listener:Callable):```  
+Register callback to a Tap strap disconnection event.
+    ```python
+    def on_disconnect(client):
+        print("Tap device disconnected")
+
+    tap_device.register_disconnection_events(on_disconnect)
+    ``` 
+
+3. ```register_tap_events(self, listener:Callable):```  
+Register callback to a tap event.
+    ```python
+    def on_tap_event(identifier, tapcode):
+        print(identifier + " - tapped " + str(tapcode))
+
+    tap_device.register_tap_events(on_tap_event)
+    ```    
+    ```tapcode``` is an 8-bit unsigned number, between 1 and 31 which is formed by a binary representation of the fingers that are tapped.
+The LSb is thumb finger, the MSb is the pinky finger. 
+For example: if combination equals 5 - its binary form is 10100 - means that the thumb and the middle fingers were tapped.
+
+
+4. ```register_mouse_events(self, listener:Callable):```  
+Register callback to a mouse or air mouse movement event.
+    ```python
+    def on_mouse_event(identifier, vx, vy, proximity):
+        print(identifier + " - moused: %d, %d" %(vx, vy))
+
+    tap_device.register_mouse_events(on_mouse_event)
+    ``` 
+    ```vx``` and ```vy``` are the horizontal and vertical velocities of the mouse movement respectively.
+```proximity``` is a boolean that indicates proximity with a surface.
+5. ```register_raw_data_events(self, listener:Callable):```  
+Register callback to raw sensors data packet received event.
+    ```python
+    def on_raw_sensor_data(identifier, packets):
+        for packet in packets:
+            print(identifier, packet["type"], packet["ts"], packet["payload"])
+
+    tap_device.register_raw_data_events(on_raw_sensor_data)
+    ``` 
+    The callback receives a list of dicts, each with keys `type` (`"imu"` or `"accl"`), `ts` (millisecond timestamp), and `payload` (list of sample values). When `InputModeRaw(scaled=True)` is active, values are in mg and mdps.
+    You'll find more information on that mode in the dedicated section below or [here](https://tapwithus.atlassian.net/wiki/spaces/TD/pages/792002574/Tap+Strap+Raw+Sensors+Mode).
+
+6. ```register_air_gesture_events(self, listener:Callable):```  
+Register callback to air gesture events.
+    ```python
+    from tapsdk import AirGestures
+
+    def on_airgesture(identifier, gesture):
+        print(identifier + " - gesture: " + str(AirGestures(gesture)))
+
+    tap_device.register_air_gesture_events(on_airgesture)
+    ``` 
+    ```gesture``` is an integer code of the air gesture detected. The air gesture values are enumerated in the ```AirGestures``` class, including directional gestures (`UP_ONE_FINGER`, `PINCH`, etc.), thumb gestures (`THUMB_FINGER`, `THUMB_MIDDLE`), and spatial state gestures (`STATE_OPEN`, `STATE_FIST`, etc.).
+
+7. ```register_air_gesture_state_events(self, listener:Callable):```  
+Register callback to mouse-mode state changes (e.g. air mouse, optical mouse).
+    ```python
+    from tapsdk.enumerations import MouseModes
+
+    def on_mouse_mode_change(identifier, mouse_mode):
+        print(identifier + " - mode: " + str(mouse_mode))
+
+    tap_device.register_air_gesture_state_events(on_mouse_mode_change)
+    ``` 
+    ```mouse_mode``` is a ```MouseModes``` enum value: `STDBY`, `AIR_MOUSE`, `OPTICAL1`, or `OPTICAL2`.
+
+### Raw sensors mode
+
+**Make sure that "Developer mode" is enabled on TapManager app for this mode to work properly**
+
+In raw sensors mode, the Tap device continuously sends raw data from the following sensors:
+1. Five 3-axis accelerometers - one per each finger (**available only on TAP Strap and Tap Strap 2**).
+    * sampled at 200Hz
+    * allows dynamic range configuration (±2G, ±4G, ±8G, ±16G)
+2. IMU (3-axis accelerometer + gyro) located on the thumb (**available on TAP Strap 2 and TapXR**).
+    * sampled at 208Hz. 
+    * allows dynamic range configuration for the accelerometer (±2G, ±4G, ±8G, ±16G) and for the gyro (±125dps, ±250dps, ±500dps, ±1000dps, ±2000dps).
+
+The sensors measurements are given with respect to the reference system below.
+
+![alt text](TAP-axis-alpha.png "Tap Strap reference frame")
+![alt text](TAPXR-axis.png "TapXR reference frame")
+
+Each sample (of accelerometer or imu) is preambled with a millisecond timestamp, referenced to an internal Tap clock.
+
+
+The dynamic range of the sensors is determined with the ```set_input_mode``` method by passing an ```InputModeRaw``` instance with the desired sensitivity enums, and a boolean flag indicating if the data should be scaled to mg and mdps for the accelerometer and gyro respectively:
+```python
+from tapsdk import InputModeRaw
+from tapsdk.enumerations import FingerAcclSensitivity, ImuGyroSensitivity, ImuAcclSensitivity
+
+await tap_device.set_input_mode(InputModeRaw(
+    scaled=True,
+    finger_accl_sens=FingerAcclSensitivity.G4,
+    imu_gyro_sens=ImuGyroSensitivity.DPS250,
+    imu_accl_sens=ImuAcclSensitivity.G4
+))
+```
+Refer to `FingerAcclSensitivity`, `ImuGyroSensitivity`, and `ImuAcclSensitivity` in [`tapsdk.enumerations`](tapsdk/enumerations.py) for the available sensitivity values.
+
+### Examples
+
+You can find some examples in the [examples folder](examples).
+
+### Testing
+
+To run the tests, first install the development dependencies:
+
+```bash
+pip install .[dev]
+```
+
+Then run the tests using pytest:
+
+```bash
+pytest
+```
+
+
+### Known Issues
+See [History.md](History.md) for release notes. No known issues at 0.7.0.
+
+### Support
+
+Please refer to the issues tab! :)
+
+
+# History
+
+## Releasing
+
+PyPI releases are published automatically when a version tag is pushed to GitHub.
+
+1. Bump `__version__` in `tapsdk/__version__.py` and update this file.
+2. Merge the release changes into `develop`, then into `master` as needed.
+3. Create and push an annotated tag whose name matches the package version (for example `v0.7.0`):
+
+   ```bash
+   git tag -a v0.7.0 -m "Release 0.7.0"
+   git push origin v0.7.0
+   ```
+
+The `Publish to PyPI` workflow runs the same lint and test matrix as CI, verifies that the tag (without the `v` prefix) matches `tapsdk.__version__`, builds the package with `python -m build`, and uploads it to PyPI using Trusted Publishing.
+
+Maintainers must configure PyPI Trusted Publishing for the `tap-python-sdk` project name, the `TapWithUs/tap-python-sdk` repository, and a GitHub `pypi` environment before the first automated release.
+
+## 0.7.0 (2026-06-09)
+______________________
+### Main features
+
+* Unified cross-platform implementation in `tapsdk/tap.py` (removed separate posix/dotnet backends).
+* Windows rewritten to use Bleak/WinRT instead of TAPWin.dll.
+* `InputMode` API: `TapInputMode("…")` replaced by `InputModeText`, `InputModeController`, `InputModeControllerText`, `InputModeRaw`.
+* Raw mode: typed sensitivity enums and optional scaling to mg/mdps (`scaled=True`).
+* Connection and disconnection events implemented on all platforms.
+* Windows: BLE scan and reconnect polling for paired devices.
+* Python requirement raised to 3.9+.
+* CI: cross-platform pytest and flake8.
+* New `AirGestures` values (thumb and state gestures).
+
+### Breaking changes
+
+* Removed `TapInputMode`, `loop` constructor argument, `tapsdk.models`, and OS-specific examples.
+* Windows no longer uses bundled TAPWin.dll.
+
+## 0.6.0 (2024-07-04)
+______________________
+### Main features
+
+* Added Spatial features for TapXR.
+* Mac and Linux backends unified to posix backend.
+
+### Known Issues
+* Windows backend -
+    * Raw sensor data rate might be lower than expected.
+    * Sometimes a Tap strap wouldn't be detected upon connection. In this case try restarting your Tap and/or the Python application. In worst case scenario re-pair your Tap.
+    * Spatial features are still not available for Windows backend.
+* MacOS & Linux backends -
+    * Doesn't support multiple Tap strap connections.
+    * OnConnect and OnDisconnect events are not implemented
+    * Raw sensor data is given unscaled (i.e. unitless), therefore in order to scale to physical units need to multiply by the relevant scale factor
+
+## 0.5.1 (2024-01-01)
+______________________
+### Main features
+
+* Support TapXR Air Gesture pinch
+
+## 0.5.0 (2021-08-03)
+______________________
+### Main features
+
+* Support Bleak 0.12.1 for mac
+
+## 0.3.0 (2020-09-07)
+______________________
+### Main features
+
+* Linux support
+* Some bug fixes
+
+## 0.2.0 (2020-02-22)
+______________________
+### Main features
+
+* Added dll to enable windows backend.
+* fix parsers output types on gesture and tap messages
+
+## 0.1.0 (2020-02-20)
+______________________
+### Main features
+
+* SDK created.
+

tap_python_sdk-0.7.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+tap_python_sdk-0.7.0.dist-info/licenses/LICENSE,sha256=eti4ME038zjryrDblce9H1mdbHYvJWcAWzO_YijslMQ,1076
+tapsdk/__init__.py,sha256=KKp2hx7wbS004eFz9NSncfRedc-EA-xXBMF7esZUuzc,373
+tapsdk/__version__.py,sha256=RaANGbRu5e-vehwXI1-Qe2ggPPfs1TQaZj072JdbLk4,22
+tapsdk/enumerations.py,sha256=GbDjCjnJfVNQ_Tm-xhHntoMVAb3psFKw9pC6_q79NxM,919
+tapsdk/inputmodes.py,sha256=X-wE2xGFY6RWfxOMcFpoaoS3rBAzvu9oCto8YLdsXPE,2443
+tapsdk/parsers.py,sha256=xgm4kof0xfn8RBUv4pZ0T5LKefY6rt8bwBcvMyF7oPc,2529
+tapsdk/tap.py,sha256=w4RfrGtNkeYlS5B6guJTWKyngPH9wHkAU26gOsM9fic,21592
+tap_python_sdk-0.7.0.dist-info/METADATA,sha256=GwYzxzTsesQG6F9025I68TzWwBhT1cGXeb0yJYmPG7k,16360
+tap_python_sdk-0.7.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+tap_python_sdk-0.7.0.dist-info/top_level.txt,sha256=iS4pGTpFcbvz23yP9N21AGqQfCQ2w7uustHmwcI-qTs,7
+tap_python_sdk-0.7.0.dist-info/RECORD,,

tap_python_sdk-0.7.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tap_python_sdk-0.7.0.dist-info/licenses/LICENSE

@@ -0,0 +1,11 @@
+
+MIT License
+
+Copyright (c) 2020, Tap Systems Inc.
+
+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.
+

tap_python_sdk-0.7.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tapsdk

tapsdk/__init__.py

@@ -0,0 +1,10 @@
+from tapsdk.enumerations import InputType, AirGestures  # noqa: F401
+from tapsdk.inputmodes import InputModeRaw, InputModeController, InputModeText, InputModeControllerText  # noqa: F401
+
+
+def __getattr__(name):
+    if name == "TapSDK":
+        from tapsdk.tap import TapSDK
+
+        return TapSDK
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tapsdk/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.7.0"

tapsdk/enumerations.py

@@ -0,0 +1,58 @@
+from enum import Enum
+
+
+class MouseModes(Enum):
+    STDBY = 0
+    AIR_MOUSE = 1
+    OPTICAL1 = 2
+    OPTICAL2 = 3
+
+
+class InputType(Enum):
+    MOUSE = 1
+    KEYBOARD = 2
+    AUTO = 3
+
+
+class AirGestures(Enum):
+    NONE = 0
+    GENERAL = 1
+    UP_ONE_FINGER = 2
+    UP_TWO_FINGERS = 3
+    DOWN_ONE_FINGER = 4
+    DOWN_TWO_FINGERS = 5
+    LEFT_ONE_FINGER = 6
+    LEFT_TWO_FINGERS = 7
+    RIGHT_ONE_FINGER = 8
+    RIGHT_TWO_FINGERS = 9
+    PINCH = 10
+    THUMB_FINGER = 12
+    THUMB_MIDDLE = 14
+    STATE_OPEN = 100
+    STATE_THUMB_FINGER = 101
+    STATE_THUMB_MIDDLE = 102
+    STATE_THUMB_RING = 103
+    STATE_THUMB_PINKY = 104
+    STATE_FIST = 105
+
+
+class FingerAcclSensitivity(Enum):
+    G2 = 1
+    G4 = 2
+    G8 = 3
+    G16 = 4
+
+
+class ImuGyroSensitivity(Enum):
+    DPS125 = 1
+    DPS250 = 2
+    DPS500 = 3
+    DPS1000 = 4
+    DPS2000 = 5
+
+
+class ImuAcclSensitivity(Enum):
+    G2 = 1
+    G4 = 2
+    G8 = 3
+    G16 = 4

tapsdk/inputmodes.py

@@ -0,0 +1,71 @@
+from enum import Enum
+import logging
+from .enumerations import InputType, FingerAcclSensitivity, ImuGyroSensitivity, ImuAcclSensitivity
+
+logger = logging.getLogger(__name__)
+
+
+class RawSensorsSensitivity():
+    finger_acc_scales = [None, 3.91, 7.81, 15.62, 31.25]  # mg/lsb
+    imu_gyro_scales = [None, 4.375, 8.75, 17.5, 35, 70]  # mdps/lsb
+    imu_acc_scales = [None, 0.061, 0.122, 0.244, 0.488]  # mg/lsb
+
+    def __init__(self, finger_accl_sens, imu_gyro_sens, imu_accl_sens):
+        assert all(isinstance(s, Enum) for s in [finger_accl_sens, imu_gyro_sens, imu_accl_sens]), \
+            "sensitivity values must be of type Enum"
+        self.sens_values = [finger_accl_sens.value, imu_gyro_sens.value, imu_accl_sens.value]
+        self.scale_factors = [      # in mg, mdps, mg
+            self.finger_acc_scales[self.sens_values[0]],
+            self.imu_gyro_scales[self.sens_values[1]],
+            self.imu_acc_scales[self.sens_values[2]]
+        ]
+
+    def tolist(self):
+        return self.sens_values
+
+    def get_scale_factors(self):
+        return self.scale_factors
+
+
+class InputMode:
+    COMMAND_PREFIX = bytearray([0x3, 0xc, 0x0])
+
+    def get_command(self):
+        return self.COMMAND_PREFIX + self.code
+
+    def __repr__(self):
+        return self.name
+
+
+class InputModeController(InputMode):
+    def __init__(self):
+        self.name = "Controller Mode"
+        self.code = bytearray([0x1])
+
+
+class InputModeText(InputMode):
+    def __init__(self):
+        self.name = "Text Mode"
+        self.code = bytearray([0x0])
+
+
+class InputModeControllerText(InputMode):
+    def __init__(self):
+        self.name = "Controller and Text Mode"
+        self.code = bytearray([0x5])
+
+
+class InputModeRaw(InputMode):
+    def __init__(self, scaled=False, finger_accl_sens=None,
+                 imu_gyro_sens=None, imu_accl_sens=None):
+        self.name = "Raw sensors Mode"
+        self.scaled = scaled
+        self.sensitivity = RawSensorsSensitivity(finger_accl_sens or FingerAcclSensitivity.G2,
+                                                 imu_gyro_sens or ImuGyroSensitivity.DPS125,
+                                                 imu_accl_sens or ImuAcclSensitivity.G2)
+        self.code = bytearray([0xa]) + bytearray(self.sensitivity.tolist())
+
+
+def input_type_command(input_type):
+    assert isinstance(input_type, InputType), "input_type must be of type InputType"
+    return bytearray([0x3, 0xd, 0x0, input_type.value])

tapsdk/parsers.py

@@ -0,0 +1,74 @@
+def tapcode_to_fingers(tapcode: int):
+    return '{0:05b}'.format(1)[::-1]
+
+
+def mouse_data_msg(data: bytearray):
+    vx = int.from_bytes(data[1:3], "little", signed=True)
+    vy = int.from_bytes(data[3:5], "little", signed=True)
+    prox = data[9] == 1
+    return vx, vy, prox
+
+
+def air_gesture_data_msg(data: bytearray):
+    return [data[0]]
+
+
+def tap_data_msg(data: bytearray):
+    return [data[0]]
+
+
+def raw_data_msg(data: bytearray, scale_factors=None):
+    '''
+    Parses raw data messages into structured data with optional scaling.
+    Raw data is packed into messages with the following structure:
+         [msg_type (1 bit)][timestamp (31 bit)][payload (12 - 30 bytes)]
+             * msg type     - '0' for imu message
+                        - '1' for accelerometers message
+            * timestamp - unsigned int, given in milliseconds
+            * payload     - for imu message is 12 bytes
+                          composed by a series of 6 uint16 numbers
+                          representing [g_x, g_y, g_z, xl_x, xl_y, xl_z]
+                        - for accelerometers message is 30 bytes
+                          composed by a series of 15 uint16 numbers
+                          representing [xl_x_thumb , xl_y_thumb,  xl_z_thumb,
+                                          xl_x_finger, xl_y_finger, xl_z_finger,
+                                        ...]
+
+    '''
+    L = len(data)
+    ptr = 0
+    messages = []
+    while ptr <= L:
+        # decode timestamp and message type
+        ts = int.from_bytes(data[ptr:ptr+4], "little", signed=False)
+        if ts == 0:
+            break
+        ptr += 4
+
+        # resolve message type
+        if ts > raw_data_msg.msg_type_value:
+            msg = "accl"
+            ts -= raw_data_msg.msg_type_value
+            num_of_samples = 15
+        else:
+            msg = "imu"
+            num_of_samples = 6
+
+        # parse payload
+        payload = []
+        for i in range(num_of_samples):
+            val = int.from_bytes(data[ptr:ptr+2], "little", signed=True)
+            ptr += 2
+            payload.append(val)
+
+        if scale_factors:
+            if msg == "accl":
+                payload = [v * scale_factors[0] for v in payload]
+            elif msg == "imu":
+                payload = [payload[j] * scale_factors[1] if j < 3 else payload[j] * scale_factors[2]
+                           for j in range(num_of_samples)]
+        messages.append({"type": msg, "ts": ts, "payload": payload})
+    return messages
+
+
+raw_data_msg.msg_type_value = 2**31

tapsdk/tap.py

@@ -0,0 +1,469 @@
+import asyncio
+import logging
+import platform
+from typing import Callable
+
+from bleak import BleakClient, BleakScanner
+
+from . import parsers
+from .enumerations import InputType, MouseModes
+from .inputmodes import InputModeText, InputMode, InputModeRaw, input_type_command
+
+logger = logging.getLogger(__name__)
+
+tap_service = 'c3ff0001-1d8b-40fd-a56f-c7bd5d0f3370'
+nus_service = '6e400001-b5a3-f393-e0a9-e50e24dcca9e'
+tap_data_characteristic = 'c3ff0005-1d8b-40fd-a56f-c7bd5d0f3370'
+mouse_data_characteristic = 'c3ff0006-1d8b-40fd-a56f-c7bd5d0f3370'
+ui_cmd_characteristic = 'c3ff0009-1d8b-40fd-a56f-c7bd5d0f3370'
+air_gesture_data_characteristic = 'c3ff000a-1d8b-40fd-a56f-c7bd5d0f3370'
+tap_mode_characteristic = '6e400002-b5a3-f393-e0a9-e50e24dcca9e'        # nus rx
+raw_sensors_characteristic = '6e400003-b5a3-f393-e0a9-e50e24dcca9e'     # nus tx
+
+
+if platform.system() == "Darwin":
+    try:
+        from bleak.backends.corebluetooth.CentralManagerDelegate import (
+            CBUUID, CentralManagerDelegate)
+    except ImportError as e:
+        raise ImportError(
+            "tapsdk requires bleak==0.12.1 on macOS; the installed bleak version "
+            "no longer exposes bleak.backends.corebluetooth.CentralManagerDelegate "
+            "at this import path. Reinstall with the pinned dependency from setup.py."
+        ) from e
+
+    def string2uuid(uuid_str: str) -> CBUUID:
+        """Convert a string to a uuid"""
+        return CBUUID.UUIDWithString_(uuid_str)
+
+    class TapClient(BleakClient):
+        def __init__(self, address="", **kwargs):
+            super().__init__(address, **kwargs)
+
+        async def connect_retrieved(self, **kwargs) -> bool:
+            self._central_manager_delegate = CentralManagerDelegate.alloc().init()
+            paired_taps = self.get_paired_taps()
+            if len(paired_taps) == 0:
+                return False
+            self._peripheral = paired_taps[0]
+            logger.debug("Connecting to Tap device @ {}".format(self._peripheral))
+            await self.connect()
+
+            # Now get services
+            await self.get_services()
+
+            return True
+
+        def get_paired_taps(self):
+            paired_taps = self._central_manager_delegate.central_manager.retrieveConnectedPeripheralsWithServices_(
+                            [string2uuid(tap_service)])
+            logger.debug("Found connected Taps @ {}".format(paired_taps))
+            return paired_taps
+
+elif platform.system() == "Windows":
+    try:
+        from bleak_winrt.windows.devices.bluetooth import (BluetoothLEDevice,  # noqa: F401
+                                                           BluetoothConnectionStatus, BluetoothCacheMode)
+        from bleak_winrt.windows.devices.bluetooth.genericattributeprofile import GattSession, GattSessionStatus
+        from bleak_winrt.windows.devices.enumeration import DeviceInformation, DeviceInformationKind
+    except ImportError as e:
+        # bleak>=0.22.0 no longer depends on bleak_winrt (see #21), so it must be
+        # installed explicitly; setup.py pins bleak==0.22.3 + bleak-winrt==1.2.0
+        # for Windows. Fail fast if that pin was not honored, rather than
+        # silently disabling the Windows BLE backend at runtime.
+        raise ImportError(
+            "tapsdk requires bleak==0.22.3 and bleak-winrt==1.2.0 on Windows. "
+            "Reinstall with the pinned dependencies from setup.py, or see "
+            "https://github.com/TapWithUs/tap-python-sdk/issues/21."
+        ) from e
+
+    async def get_connected_taps():
+        # use the following device properties: Paired, Connected, Device Address
+        request_properties = [
+            "System.Devices.Aep.IsPaired",
+            "System.Devices.Aep.IsConnected",
+            "System.Devices.Aep.DeviceAddress",]
+        aqs_filter = BluetoothLEDevice.get_device_selector_from_connection_status(BluetoothConnectionStatus.CONNECTED)
+        devices = await DeviceInformation.find_all_async(aqs_filter, request_properties,
+                                                         DeviceInformationKind.ASSOCIATION_ENDPOINT)
+        taps = []
+        for device in devices:
+            try:
+                # Extract the Bluetooth address from the device id
+                # device.id format: "BluetoothLE#BluetoothLExx:xx:xx:xx:xx:xx-yy:yy:yy:yy:yy:yy"
+                device_address_str = device.id.split("-")[-1].upper()
+                # Convert MAC address string (e.g. "AA:BB:CC:DD:EE:FF") to a uint64
+                address_int = int(device_address_str.replace(":", ""), 16)
+                ble_device = await BluetoothLEDevice.from_bluetooth_address_async(address_int)
+                if ble_device is None:
+                    logger.error(f"Could not create BLE device for {device.name}")
+                    continue
+                services = await ble_device.get_gatt_services_async()
+                logger.info(f"Device {device.name} has the following services:")
+                for service in services.services:
+                    logger.info(f"Service UUID: {service.uuid}")
+                    if str(service.uuid).lower() == tap_service.lower():
+                        taps.append(device)
+                        break
+            except Exception as e:
+                logger.error(f"Failed to retrieve services for device {device.name}: {e}")
+        # taps = [device for device in devices if tap_service.lower() in [x.lower() for x in device.properties.keys()]]
+        return taps
+
+    async def get_tap_device():
+        taps = await get_connected_taps()
+        if not taps:
+            logger.info("No connected Tap devices found.")
+            return None
+        return taps[0].id  # Return the full WinRT device ID for BleakClient
+
+    class TapClient(BleakClient):
+        def __init__(self, address="", **kwargs):
+            super().__init__(address, **kwargs)
+
+        async def connect_retrieved(self, **kwargs) -> bool:
+            if not self.address:
+                logger.info("No connected Tap devices found.")
+                return False
+            logger.info(f"Connecting to Tap device @ {self.address}")
+
+            # Bypass Bleak's connect() entirely because the device is already connected
+            # at the OS level. Bleak's connect() waits for a GattSessionStatus.ACTIVE event,
+            # but that event has already fired before the handler is attached — so it hangs.
+            # Instead, we manually set up _requester and _session on the backend.
+            try:
+                remote_mac = self.address.split("-")[-1]
+                address_int = int(remote_mac.replace(":", ""), 16)
+
+                backend = self._backend
+
+                # Get the BluetoothLEDevice for the already-connected device
+                backend._requester = await BluetoothLEDevice.from_bluetooth_address_async(address_int)
+                if backend._requester is None:
+                    logger.error(f"Could not get BluetoothLEDevice for {self.address}")
+                    return False
+
+                # Open the GATT session (already ACTIVE since device is connected)
+                backend._session = await GattSession.from_device_id_async(
+                    backend._requester.bluetooth_device_id
+                )
+                backend._session.maintain_connection = True
+
+                # Force uncached GATT discovery so Windows does not serve a
+                # stale cached table that may be missing characteristics.
+                backend.services = None
+                backend.services = await backend.get_services(
+                    service_cache_mode=BluetoothCacheMode.UNCACHED,
+                    cache_mode=BluetoothCacheMode.UNCACHED,
+                )
+                if backend.services:
+                    for svc in backend.services.services.values():
+                        char_uuids = [str(c.uuid) for c in svc.characteristics]
+                        logger.debug("Discovered service %s with characteristics: %s", svc.uuid, char_uuids)
+
+                is_active = backend._session.session_status == GattSessionStatus.ACTIVE
+                logger.info(f"Session status ACTIVE: {is_active}")
+                return is_active
+
+            except Exception as e:
+                logger.error(f"connect_retrieved failed: {e}")
+                return False
+
+
+elif platform.system() == "Linux":
+    class TapClient(BleakClient):
+        def __init__(self, address=None, **kwargs):
+            address = address if address else get_mac_addr()
+            super().__init__(address, **kwargs)
+
+        async def connect_retrieved(self, **kwargs) -> bool:
+            await self.connect()
+            connected = self.is_connected()
+            if connected:
+                logger.info("Connected to {0}".format(self.address))
+                await self.__debug()
+            else:
+                logger.error("Failed to connect to {0}".format(self.address))
+            return connected
+
+        async def __debug(self):
+            for service in self.services:
+                logger.info("[service] {}: {}".format(service.uuid, service.description))
+                for char in service.characteristics:
+                    if "read" in char.properties:
+                        try:
+                            value = bytes(await self.read_gatt_char(char.uuid))
+                        except Exception as e:
+                            value = str(e).encode
+                    else:
+                        value = None
+                    # if value:
+                    logger.info(
+                        "\t[Characteristic] {0}: (Handle: {1}) ({2}) | Name: {3}, Value: {4} ".format(
+                            char.uuid,
+                            "<handle geos here>",  # char.handle,
+                            ",".join(char.properties),
+                            char.description,
+                            value,
+                        )
+                    )
+
+    def get_mac_addr() -> str:
+        from subprocess import PIPE, Popen
+        try:
+            with Popen(["bt-device", "--list"], stdout=PIPE, text=True) as btdevice_process:
+                exit_code = btdevice_process.wait()
+                if exit_code:
+                    raise ConnectionError("Failed to find any TAP decive")
+                connected_bt_devices = btdevice_process.stdout.read().splitlines()
+                tap_devices = list(filter(lambda line: line.startswith("Tap"), connected_bt_devices))
+                for d in tap_devices:
+                    logger.info("Found tap device: %s", d)
+                if len(tap_devices) > 1:
+                    logger.info("Found more than 1 Tap device:")
+                    for i, d in enumerate(tap_devices):
+                        logger.info("%s. %s", i + 1, d)
+                    tap_devices = [tap_devices[int(input("Select the device number: ")) - 1]]
+                if len(tap_devices) == 0:
+                    raise ValueError(
+                        "No Tap device was found. Make sure the device is connected and its human readable name "
+                        "starts with Tap.")
+                device_decs = tap_devices[0]
+                tap_mac_address = device_decs[-18:-1]  # only the mac_address part of the description.
+                return tap_mac_address
+        except Exception as e:
+            logger.error("Failed to find any TAP device: {}".format(e))
+            raise e
+
+
+class TapSDK():
+    def __init__(self, **kwargs):
+        self.client = TapClient(address=kwargs.get("address"))
+        self.mouse_event_cb = None
+        self.tap_event_cb = None
+        self.air_gesture_event_cb = None
+        self.raw_data_event_cb = None
+        self.air_gesture_state_event_cb = None
+        self.connection_cb = None
+        self.input_mode_refresh = InputModeAutoRefresh(self._refresh_input_mode, timeout=10)
+        self.mouse_mode = MouseModes.STDBY
+        self.input_mode = InputModeText()  # Default input mode is Text Mode
+        self.input_type = InputType.AUTO
+
+    @staticmethod
+    def _client_connected(client) -> bool:
+        is_connected = getattr(client, "is_connected", False)
+        return is_connected() if callable(is_connected) else is_connected
+
+    def register_tap_events(self, cb: Callable):
+        self.tap_event_cb = cb
+
+    def register_mouse_events(self, cb: Callable):
+        self.mouse_event_cb = cb
+
+    def register_air_gesture_events(self, cb: Callable):
+        self.air_gesture_event_cb = cb
+
+    def register_air_gesture_state_events(self, cb: Callable):
+        self.air_gesture_state_event_cb = cb
+
+    def register_raw_data_events(self, cb: Callable):
+        self.raw_data_event_cb = cb
+
+    def register_connection_events(self, cb: Callable):
+        self.connection_cb = cb
+
+    def register_disconnection_events(self, cb: Callable):
+        self.client.set_disconnected_callback(cb)
+
+    def on_moused(self, identifier, data):
+        if self.mouse_event_cb:
+            args = parsers.mouse_data_msg(data)
+            self.mouse_event_cb(identifier, *args)
+
+    def on_tapped(self, identifier, data):
+        args = parsers.tap_data_msg(data)
+        if self.mouse_mode == MouseModes.AIR_MOUSE:
+            tapcode = args[0]
+            if tapcode in [2, 4]:
+                self.on_air_gesture(identifier, [tapcode + 10])
+        elif self.tap_event_cb:
+            self.tap_event_cb(identifier, *args)
+
+    def on_raw_data(self, identifier, data):
+        if self.raw_data_event_cb:
+            scale_factors = None
+            if isinstance(self.input_mode, InputModeRaw):
+                if self.input_mode.scaled:
+                    scale_factors = self.input_mode.sensitivity.get_scale_factors()
+            args = parsers.raw_data_msg(data, scale_factors=scale_factors)
+            self.raw_data_event_cb(identifier, args)
+
+    def on_air_gesture(self, identifier, data):
+        if data[0] == 0x14:  # mouse mode event
+            self.mouse_mode = MouseModes(data[1])
+            if self.air_gesture_state_event_cb:
+                self.air_gesture_state_event_cb(identifier, self.mouse_mode)
+        elif self.air_gesture_event_cb:
+            args = parsers.air_gesture_data_msg(data)
+            self.air_gesture_event_cb(identifier, *args)
+
+    async def send_vibration_sequence(self, sequence, identifier=None):
+        if len(sequence) > 18:
+            sequence = sequence[:18]
+        for i, d in enumerate(sequence):
+            sequence[i] = max(0, min(255, d // 10))
+
+        write_value = bytearray([0x0, 0x2] + sequence)
+        await self.client.write_gatt_char(ui_cmd_characteristic, write_value)
+
+    async def set_input_mode(self, input_mode: InputMode, identifier=None):
+        if (isinstance(input_mode, InputModeRaw) and isinstance(self.input_mode, InputModeRaw) and
+           self.input_mode.get_command() != input_mode.get_command()):
+            logger.warning("Can't change \"raw\" sensitivities while in \"raw\"")
+            return
+
+        self.input_mode = input_mode
+        write_value = input_mode.get_command()
+
+        if not self.input_mode_refresh.is_running:
+            await self.input_mode_refresh.start()
+
+        await self._write_input_mode(write_value)
+
+    async def set_input_type(self, input_type: InputType, identifier=None):
+        assert isinstance(input_type, InputType), "input_type must be of type InputType"
+        self.input_type = input_type
+        write_value = input_type_command(self.input_type)
+
+        if not self.input_mode_refresh.is_running:
+            await self.input_mode_refresh.start()
+
+        await self._write_input_mode(write_value)
+
+    async def _refresh_input_mode(self):
+        await self.set_input_mode(self.input_mode)
+        logger.debug(f"Input Mode Refreshed: {self.input_mode}")
+        await self.set_input_type(self.input_type)
+        logger.debug(f"Input Type Refreshed: {self.input_type}")
+
+    async def _write_input_mode(self, value):
+        await self.client.write_gatt_char(tap_mode_characteristic, value)
+
+    async def run(self):
+        stop_event = asyncio.Event()
+        devices = []
+        connected = False
+
+        if platform.system() == "Windows":
+            # First, try to attach to an already-connected Tap device
+            tap_device = await get_tap_device()
+            if tap_device:
+                self.client = TapClient(tap_device)
+                connected = await self.client.connect_retrieved()
+
+            if not connected:
+                # Run BleakScanner and Windows reconnect-poller concurrently.
+                # - BleakScanner finds unpaired/advertising devices and pairs them.
+                # - The poller detects already-paired devices reconnecting (not advertising).
+                logger.info("No connected Tap found. Scanning and waiting for a Tap device...")
+                found_event = asyncio.Event()
+                found_device = {}  # shared mutable container
+
+                async def detection_cb(device, adv_data):
+                    if tap_service.lower() in adv_data.service_uuids:
+                        logger.info(f"Found advertising Tap via scan: {device.address}")
+                        found_device["scanned"] = device
+                        found_event.set()
+
+                async def windows_reconnect_poller():
+                    """Poll Windows for already-paired Tap devices reconnecting."""
+                    while not found_event.is_set():
+                        await asyncio.sleep(3)
+                        tap_id = await get_tap_device()
+                        if tap_id:
+                            logger.info(f"Found already-paired Tap reconnected: {tap_id}")
+                            found_device["winrt"] = tap_id
+                            found_event.set()
+
+                async with BleakScanner(detection_callback=detection_cb):
+                    poller_task = asyncio.create_task(windows_reconnect_poller())
+                    await found_event.wait()
+                    poller_task.cancel()
+
+                if "winrt" in found_device:
+                    # Already-paired device reconnected — attach via WinRT path
+                    self.client = TapClient(found_device["winrt"])
+                    connected = await self.client.connect_retrieved()
+                elif "scanned" in found_device:
+                    # Device was seen advertising. Windows may have already claimed the
+                    # connection by now, so try the WinRT path first, then fall back to
+                    # Bleak's connect()+pair() if the device is still advertising.
+                    await asyncio.sleep(1)  # brief wait for Windows to finish pairing
+                    tap_id = await get_tap_device()
+                    if tap_id:
+                        logger.info(f"Scanned device is now connected via Windows: {tap_id}")
+                        self.client = TapClient(tap_id)
+                        connected = await self.client.connect_retrieved()
+                    if not connected:
+                        logger.info("Falling back to Bleak connect+pair...")
+                        self.client = TapClient(found_device["scanned"])
+                        await self.client.connect()
+                        await self.client.pair(protection_level=2)
+                        connected = self._client_connected(self.client)
+
+        else:
+            async def detection_cb(device, adv_data):
+                logger.debug("detected %s %s", device, adv_data)
+                if tap_service.lower() in adv_data.service_uuids:
+                    if device.address not in [d.address for d in devices]:
+                        devices.append(device)
+                        stop_event.set()
+
+            connected = await self.client.connect_retrieved()
+            if not connected:
+                logger.info("Couldn't find connected Tap device. Scanning for Tap devices...")
+                async with BleakScanner(detection_callback=detection_cb):
+                    await stop_event.wait()
+
+                self.client = TapClient(devices[0])
+                await self.client.connect()
+                if platform.system() != "Darwin":
+                    await self.client.pair()
+
+        if self.client.is_connected:
+            for ch, cb in [(tap_data_characteristic, self.on_tapped),
+                           (mouse_data_characteristic, self.on_moused),
+                           (air_gesture_data_characteristic, self.on_air_gesture),
+                           (raw_sensors_characteristic, self.on_raw_data)]:
+                try:
+                    await self.client.start_notify(ch, cb)
+                except Exception as e:
+                    logger.warning("Failed to start notify for air gesture state: " + str(e))
+            if self.connection_cb:
+                self.connection_cb(self)
+
+
+class InputModeAutoRefresh:
+    def __init__(self, set_function, timeout=10):
+        self.set_function = set_function
+        self.is_running = False
+        self.timeout = timeout
+        self.wd_task = None
+
+    async def start(self):
+        if not self.is_running:
+            self.wd_task = asyncio.create_task(self.periodic())
+            self.is_running = True
+            logger.debug("Input Mode Auto Refresh Started")
+
+    async def stop(self):
+        if self.is_running:
+            self.wd_task.cancel()
+            self.is_running = False
+            logger.debug("Input Mode Auto Refresh Stopped")
+
+    async def periodic(self):
+        while True:
+            await self.set_function()
+            await asyncio.sleep(self.timeout)