tap-python-sdk 0.7.0__tar.gz

tap_python_sdk-0.7.0/History.md

@@ -0,0 +1,87 @@
+# 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/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/MANIFEST.in

@@ -0,0 +1,9 @@
+include History.md
+include LICENSE
+include Readme.md
+
+recursive-include tests *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+recursive-include docs *.rst *.md conf.py Makefile make.bat *.jpg *.png *.gif

tap_python_sdk-0.7.0/PKG-INFO

@@ -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.
+