/etee-Python-API

Official Python API for the eteeControllers.

Primary LanguagePythonApache License 2.0Apache-2.0


Logo Dark Logo Light

Official Python API for the eteeControllers.
Explore the docs »
Report Bug · Request Feature


Tag for latest stable release Compatible Platforms License

Check our Docs! Check our Website! Support e-mail Follow us in Twitter!

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Contributing
  5. License
  6. Authors
  7. Contact

About the Project

This API enables easy device data reading and communication.

In this repository, you can access:

  • etee Python API package source code
  • etee Python API example scripts
  • Setup files

With this API, you will be able to retrieve a wide range of data from the eteeControllers:

  • Tactile data: individual finger curling and pressure, trackpad, slider LED, tracker (connection, proximity sensor; no positional tracking) and system button.


Tactile and sensing data from the eteeController.

  • Gestures: grip, pinch and point gestures.


Main eteeController gestures.

  • Inertial Measuring Units (IMU) and 3D rotation: raw 9-axis IMU data (accelerometer, gyroscope, magnetometer data) and 3D rotation estimations (quaternion, euler angles).
  • Device State: right or left hand.
  • Battery State: charge level, charge status.

For more information, please, visit our documentation site: Developer Documentation - etee Python API

(back to top)

Getting Started

Step 1: Clone the repository

  1. Open a command prompt.
  2. Change the current working directory to the location where you want the cloned directory.
  3. Type git clone, and then paste the URL for the Github repository. 
    git clone https://github.com/eteeXR/etee-Python-API.git

Step 2: Package Installation & Environment

This repository comes ready with two different setup files:

  • setup_repo.py will create a virtual environment (venv) using the dependencies listed in requirements.txt.
  • setup.py will automate the etee-api package installation.

Note: You will need the pip package to run the installation. If you do not have Python or pip installed, follow the Python guide on package installation.

2.1. Setting Up a Virtual Environment

If you do not want to run the example scripts, please skip this step and move to: 2.2. Installing the Package.

After cloning the repository, you will need to install all the project dependencies to run the example code. Unlike step 2.2., these steps will install extra dependencies required only when running the example scripts (e.g. keyboard, matplotlib).

  1. Open a command prompt.
  2. Navigate to the directory where the setup_repo.py is located.
  3. Run the script. 
    python setup_repo.py
  4. This should have created a venv inside your project directory. You can activate it at any time by navigating to the directory containing the /venv folder and entering the following command line: 
    .venv\Scripts\activate.bat

2.2. Installing the Package

You can automate the installation of the etee-api package and all its dependencies in your Python environment, by using the setup.py script.

  1. Open a command prompt.
  2. If you followed step 2.1., make sure that you activate the venv (see previous section).
  3. Navigate to the directory where the setup.py is located.
  4. Use the pip method to run the installation file. 
    pip install .
  5. To check that the package has been successfully installed, you can run the pip list command. 
    pip list
    If the package was installed, you will see its name and version listed: 
    Package         Version
--------------- -------
etee-api        1.0.0

(back to top)

Usage

Hardware Setup

To get started, set up the hardware. This involves connecting the eteeDongle to your PC or laptop, and turning ON the eteeControllers. You will know they are connected if the eteeDongle keeps blinking in the following pattern: pink-pink-blue.

Example Scripts

If you followed the previous steps on installation, you should be able to run any example scripts.

  1. Open a command prompt.
  2. In case you followed step 2.1., make sure that you activate the venv.
  3. Navigate to the directory where the example script is located.
  4. Use the python method to run the example script. 
    python example_script_name.py

Further Information

We also have quickstart and more detailed developer guides in our documentation page. This might help you understand the different API functionalities and how to integrate them in your custom applications.

To learn more about the API and the eteeController data, visit our Developer Documentation Site

Check our Docs!

(back to top)

Contributing

How to Contribute

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue to describe your suggestion or report a bug.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

Semantic Type Prefixes

To help us and the community easily identify the nature of your commit or issue, use semantic type prefixes to precede your message / title.

Some common type prefixes include:

  • feat: A new feature for the user, not a new feature for a build script.
  • fix: Bug fix for the user, not a fix for a build scripts.
  • enhanc: Enhancement or improvement to existing feature.
  • perf: Code improved in terms of processing performance.
  • refactor: Refactoring production code (e.g. renaming a variable).
  • chore: Changes to the build process or auxiliary tools and libraries.
  • docs: Changes to documentation.
  • style: Formatting, missing semicolons, etc. No code change.
  • vendor: Update version for dependencies and other packages.
  • test: Adding missing tests or refactoring tests. No production code change.

Format: <type>(<scope>): <subject>, where < scope > is optional.

For example, your commit message header might look like this:

feat(imu): Implemented Euler angles estimation from quaternion

For more references and guides on semantic code messages, see:

(back to top)

License

Distributed under the Apache 2.0 License. See LICENSE.txt for more information.

(back to top)

Authors

This repository was created by the TG0 team, for the etee brand.

Code and documentation authors include:

  • Dimitri Chikhladze (API development and documentation)
  • Pilar Zhang Qiu (API development, documentation and releases)

(back to top)

Contact

For any queries or reports about the API, please use the Issues tab in this repository. When possible, use an identifier to help us describe your query, report or request. See more at: Semantic Type Prefixes.

For further support or queries, you can contact us:

(back to top)