Skip to content

Commit 697e905

Browse files
JakubAndrysekJakubAndrysek
committed
Update mkdocs.yml and mouseApi/index.md, and add examples.md to mouseApi folder
1 parent c2ba4d7 commit 697e905

File tree

7 files changed

+147
-229
lines changed

7 files changed

+147
-229
lines changed

‎README.md

+14-114
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# PySpaceMouse
22

3-
A Python library for 3Dconnexion SpaceMouse devices
3+
🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.
44

55
3Dconnexion Space Mouse in Python using raw HID.
66
Note: you **don't** need to install or use any of the drivers or 3Dconnexion software to use this package.
@@ -17,11 +17,11 @@ It interfaces with the controller directly with `hidapi` and python wrapper libr
1717

1818
[PySpaceMouse](https://github.com/JakubAndrysek/pyspacemouse) is forked from: [johnhw/pyspacenavigator](https://github.com/johnhw/pyspacenavigator)
1919

20-
Implements a simple interface to the 6 DoF 3Dconnexion [Space Mouse](https://3dconnexion.com/uk/spacemouse/) device as
20+
Implements a simple interface for 6 DoF 3Dconnexion [Space Mouse](https://3dconnexion.com/uk/spacemouse/) device as
2121
well as similar devices.
2222

2323
![](https://github.com/JakubAndrysek/pyspacemouse/raw/master/media/spacemouse-robot.jpg)
24-
Control a [robot](https://roboruka.robotickytabor.cz/) with a Space Mouse
24+
Control [Robo Arm](https://roboruka.robotickytabor.cz/) with a Space Mouse.
2525

2626
## Supported 3Dconnexion devices
2727

@@ -41,17 +41,19 @@ Control a [robot](https://roboruka.robotickytabor.cz/) with a Space Mouse
4141
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install [pyspacemouse](https://pypi.org/project/pyspacemouse/). If you are using a Mac with an ARM processor, you'll need a patched version of `easyhid`.
4242

4343
```bash
44-
# Only needed for ARM Macs
45-
pip install git+https://github.com/bglopez/python-easyhid.git
46-
4744
# Install package
4845
pip install pyspacemouse
46+
47+
# Only needed for ARM MacOs
48+
pip install git+https://github.com/bglopez/python-easyhid.git
4949
```
5050

51-
## Dependencies
51+
## Dependencies (required)
52+
53+
The library uses `hidapi` as low-level interface to the device and `easyhid` as a Python abstraction for easier use.
5254

53-
- [hidapi](https://github.com/libusb/hidapi) is `C` library for direct communication with HID devices
54-
- ### Linux
55+
- ### [hidapi](https://github.com/libusb/hidapi) is `C` library for direct communication with HID devices
56+
- #### Linux
5557
- [libhidapi-dev]() to access HID data
5658
- `sudo apt-get install libhidapi-dev` (Debian/Ubuntu)
5759
- Compile and install [hidapi](https://github.com/libusb/hidapi/#build-from-source). (other Linux
@@ -93,7 +95,7 @@ pip install pyspacemouse
9395
- Tested and developed by [consi](https://github.com/JakubAndrysek/PySpaceMouse/issues/10#issuecomment-1768362007) - thanks!
9496
- More info in [Troubleshooting - Mac OS (M1)](./troubleshooting.md#mac-os-m1) page.
9597

96-
- [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms
98+
- ### [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms
9799
- `pip install git+https://github.com/bglopez/python-easyhid.git`
98100
- this fork fix problems with `hidapi` on MacOS.
99101
- on other platforms it possible works with original package `pip install easyhid`
@@ -102,101 +104,9 @@ pip install pyspacemouse
102104

103105
If the 3Dconnexion driver is installed, please ensure to stop `3DconnexionHelper` before running your python scripts.
104106

105-
[basicExample.py](https://github.com/JakubAndrysek/PySpaceMouse/blob/master/examples/basicExample.py)
106-
````py
107-
import pyspacemouse
108-
import time
109-
110-
success = pyspacemouse.open()
111-
if success:
112-
while 1:
113-
state = pyspacemouse.read()
114-
print(state.x, state.y, state.z)
115-
time.sleep(0.01)
116-
````
117-
118-
## State objects
119-
120-
State objects returned from `read()` have 7 attributes: [t,x,y,z,roll,pitch,yaw,button].
121-
122-
* t: timestamp in seconds since the script started.
123-
* x,y,z: translations in the range [-1.0, 1.0]
124-
* roll, pitch, yaw: rotations in the range [-1.0, 1.0].
125-
* button: list of button states (0 or 1), in order specified in the device specifier
126-
127-
## Usage with callback
128-
[callbackExample.py](https://github.com/JakubAndrysek/PySpaceMouse/blob/master/examples/callbackExample.py)
129-
````py
130-
import pyspacemouse
131-
import time
132-
133-
134-
def button_0(state, buttons, pressed_buttons):
135-
print("Button:", pressed_buttons)
136107

137108

138-
def button_0_1(state, buttons, pressed_buttons):
139-
print("Buttons:", pressed_buttons)
140-
141-
142-
def someButton(state, buttons):
143-
print("Some button")
144-
145-
146-
def callback():
147-
button_arr = [pyspacemouse.ButtonCallback(0, button_0),
148-
pyspacemouse.ButtonCallback([1], lambda state, buttons, pressed_buttons: print("Button: 1")),
149-
pyspacemouse.ButtonCallback([0, 1], button_0_1), ]
150-
151-
success = pyspacemouse.open(dof_callback=pyspacemouse.print_state, button_callback=someButton,
152-
button_callback_arr=button_arr)
153-
if success:
154-
while True:
155-
pyspacemouse.read()
156-
time.sleep(0.01)
157-
158-
159-
if __name__ == '__main__':
160-
callback()
161-
````
162-
163-
## API
164-
165-
The module-level API is as follows:
166-
167-
open(callback=None, button_callback=None, button_callback_arr=None, set_nonblocking_loop=True, device=None)
168-
Open a 3D space navigator device. Makes this device the current active device, which enables the module-level read() and close()
169-
calls. For multiple devices, use the read() and close() calls on the returned object instead, and don't use the module-level calls.
170-
171-
Parameters:
172-
callback: If callback is provided, it is called on each HID update with a copy of the current state namedtuple
173-
dof_callback: If dof_callback is provided, it is called only on DOF state changes with the argument (state).
174-
button_callback: If button_callback is provided, it is called on each button push, with the arguments (state_tuple, button_state)
175-
device: name of device to open, as a string like "SpaceNavigator". Must be one of the values in `supported_devices`.
176-
If `None`, chooses the first supported device found.
177-
Returns:
178-
Device object if the device was opened successfully
179-
None if the device could not be opened
180-
181-
read() Return a namedtuple giving the current device state (t,x,y,z,roll,pitch,yaw,button)
182-
close() Close the connection to the current device, if it is open
183-
list_devices() Return a list of supported devices found, or an empty list if none found
184-
185-
`open()` returns a DeviceSpec object.
186-
If you have multiple 3Dconnexion devices, you can use the object-oriented API to access them individually.
187-
Each object has the following API, which functions exactly as the above API, but on a per-device basis:
188-
189-
dev.open() Opens the connection (this is always called by the module-level open command,
190-
so you should not need to use it unless you have called close())
191-
dev.read() Return the state of the device as namedtuple [t,x,y,z,roll,pitch,yaw,button]
192-
dev.close() Close this device
193-
194-
There are also attributes:
195-
196-
dev.connected True if the device is connected, False otherwise
197-
dev.state Convenience property which returns the same value as read()
198-
199-
## Predefined callbacks
109+
## Basic example
200110

201111
````py
202112
import pyspacemouse
@@ -208,18 +118,8 @@ if success:
208118
state = pyspacemouse.read()
209119
time.sleep(0.01)
210120
````
121+
More examples can be found in the [/examples](https://github.com/JakubAndrysek/PySpaceMouse/tree/master/examples) directory or in page with [Examples](https://spacemouse.kubaandrysek.cz/mouseApi/examples/).
211122

212-
### Callback: print_state
213-
214-
Print all axis states
215-
216-
x +0.00 y +0.00 z +0.00 roll +0.00 pitch +0.00 yaw +0.00 t +0.0
217-
218-
### Callback: print_buttons
219-
220-
Print all buttons states
221-
222-
[ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ]
223123

224124
## Troubleshooting
225125

‎docs/README.md

+14-114
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# PySpaceMouse
22

3-
A Python library for 3Dconnexion SpaceMouse devices
3+
🎮 Multiplatform Python library for 3Dconnexion SpaceMouse devices using raw HID.
44

55
3Dconnexion Space Mouse in Python using raw HID.
66
Note: you **don't** need to install or use any of the drivers or 3Dconnexion software to use this package.
@@ -17,11 +17,11 @@ It interfaces with the controller directly with `hidapi` and python wrapper libr
1717

1818
[PySpaceMouse](https://github.com/JakubAndrysek/pyspacemouse) is forked from: [johnhw/pyspacenavigator](https://github.com/johnhw/pyspacenavigator)
1919

20-
Implements a simple interface to the 6 DoF 3Dconnexion [Space Mouse](https://3dconnexion.com/uk/spacemouse/) device as
20+
Implements a simple interface for 6 DoF 3Dconnexion [Space Mouse](https://3dconnexion.com/uk/spacemouse/) device as
2121
well as similar devices.
2222

2323
![](https://github.com/JakubAndrysek/pyspacemouse/raw/master/media/spacemouse-robot.jpg)
24-
Control a [robot](https://roboruka.robotickytabor.cz/) with a Space Mouse
24+
Control [Robo Arm](https://roboruka.robotickytabor.cz/) with a Space Mouse.
2525

2626
## Supported 3Dconnexion devices
2727

@@ -41,17 +41,19 @@ Control a [robot](https://roboruka.robotickytabor.cz/) with a Space Mouse
4141
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install [pyspacemouse](https://pypi.org/project/pyspacemouse/). If you are using a Mac with an ARM processor, you'll need a patched version of `easyhid`.
4242

4343
```bash
44-
# Only needed for ARM Macs
45-
pip install git+https://github.com/bglopez/python-easyhid.git
46-
4744
# Install package
4845
pip install pyspacemouse
46+
47+
# Only needed for ARM MacOs
48+
pip install git+https://github.com/bglopez/python-easyhid.git
4949
```
5050

51-
## Dependencies
51+
## Dependencies (required)
52+
53+
The library uses `hidapi` as low-level interface to the device and `easyhid` as a Python abstraction for easier use.
5254

53-
- [hidapi](https://github.com/libusb/hidapi) is `C` library for direct communication with HID devices
54-
- ### Linux
55+
- ### [hidapi](https://github.com/libusb/hidapi) is `C` library for direct communication with HID devices
56+
- #### Linux
5557
- [libhidapi-dev]() to access HID data
5658
- `sudo apt-get install libhidapi-dev` (Debian/Ubuntu)
5759
- Compile and install [hidapi](https://github.com/libusb/hidapi/#build-from-source). (other Linux
@@ -93,7 +95,7 @@ pip install pyspacemouse
9395
- Tested and developed by [consi](https://github.com/JakubAndrysek/PySpaceMouse/issues/10#issuecomment-1768362007) - thanks!
9496
- More info in [Troubleshooting - Mac OS (M1)](./troubleshooting.md#mac-os-m1) page.
9597

96-
- [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms
98+
- ### [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms
9799
- `pip install git+https://github.com/bglopez/python-easyhid.git`
98100
- this fork fix problems with `hidapi` on MacOS.
99101
- on other platforms it possible works with original package `pip install easyhid`
@@ -102,101 +104,9 @@ pip install pyspacemouse
102104

103105
If the 3Dconnexion driver is installed, please ensure to stop `3DconnexionHelper` before running your python scripts.
104106

105-
[basicExample.py](https://github.com/JakubAndrysek/PySpaceMouse/blob/master/examples/basicExample.py)
106-
````py
107-
import pyspacemouse
108-
import time
109-
110-
success = pyspacemouse.open()
111-
if success:
112-
while 1:
113-
state = pyspacemouse.read()
114-
print(state.x, state.y, state.z)
115-
time.sleep(0.01)
116-
````
117-
118-
## State objects
119-
120-
State objects returned from `read()` have 7 attributes: [t,x,y,z,roll,pitch,yaw,button].
121-
122-
* t: timestamp in seconds since the script started.
123-
* x,y,z: translations in the range [-1.0, 1.0]
124-
* roll, pitch, yaw: rotations in the range [-1.0, 1.0].
125-
* button: list of button states (0 or 1), in order specified in the device specifier
126-
127-
## Usage with callback
128-
[callbackExample.py](https://github.com/JakubAndrysek/PySpaceMouse/blob/master/examples/callbackExample.py)
129-
````py
130-
import pyspacemouse
131-
import time
132-
133-
134-
def button_0(state, buttons, pressed_buttons):
135-
print("Button:", pressed_buttons)
136107

137108

138-
def button_0_1(state, buttons, pressed_buttons):
139-
print("Buttons:", pressed_buttons)
140-
141-
142-
def someButton(state, buttons):
143-
print("Some button")
144-
145-
146-
def callback():
147-
button_arr = [pyspacemouse.ButtonCallback(0, button_0),
148-
pyspacemouse.ButtonCallback([1], lambda state, buttons, pressed_buttons: print("Button: 1")),
149-
pyspacemouse.ButtonCallback([0, 1], button_0_1), ]
150-
151-
success = pyspacemouse.open(dof_callback=pyspacemouse.print_state, button_callback=someButton,
152-
button_callback_arr=button_arr)
153-
if success:
154-
while True:
155-
pyspacemouse.read()
156-
time.sleep(0.01)
157-
158-
159-
if __name__ == '__main__':
160-
callback()
161-
````
162-
163-
## API
164-
165-
The module-level API is as follows:
166-
167-
open(callback=None, button_callback=None, button_callback_arr=None, set_nonblocking_loop=True, device=None)
168-
Open a 3D space navigator device. Makes this device the current active device, which enables the module-level read() and close()
169-
calls. For multiple devices, use the read() and close() calls on the returned object instead, and don't use the module-level calls.
170-
171-
Parameters:
172-
callback: If callback is provided, it is called on each HID update with a copy of the current state namedtuple
173-
dof_callback: If dof_callback is provided, it is called only on DOF state changes with the argument (state).
174-
button_callback: If button_callback is provided, it is called on each button push, with the arguments (state_tuple, button_state)
175-
device: name of device to open, as a string like "SpaceNavigator". Must be one of the values in `supported_devices`.
176-
If `None`, chooses the first supported device found.
177-
Returns:
178-
Device object if the device was opened successfully
179-
None if the device could not be opened
180-
181-
read() Return a namedtuple giving the current device state (t,x,y,z,roll,pitch,yaw,button)
182-
close() Close the connection to the current device, if it is open
183-
list_devices() Return a list of supported devices found, or an empty list if none found
184-
185-
`open()` returns a DeviceSpec object.
186-
If you have multiple 3Dconnexion devices, you can use the object-oriented API to access them individually.
187-
Each object has the following API, which functions exactly as the above API, but on a per-device basis:
188-
189-
dev.open() Opens the connection (this is always called by the module-level open command,
190-
so you should not need to use it unless you have called close())
191-
dev.read() Return the state of the device as namedtuple [t,x,y,z,roll,pitch,yaw,button]
192-
dev.close() Close this device
193-
194-
There are also attributes:
195-
196-
dev.connected True if the device is connected, False otherwise
197-
dev.state Convenience property which returns the same value as read()
198-
199-
## Predefined callbacks
109+
## Basic example
200110

201111
````py
202112
import pyspacemouse
@@ -208,18 +118,8 @@ if success:
208118
state = pyspacemouse.read()
209119
time.sleep(0.01)
210120
````
121+
More examples can be found in the [/examples](https://github.com/JakubAndrysek/PySpaceMouse/tree/master/examples) directory or in page with [Examples](https://spacemouse.kubaandrysek.cz/mouseApi/examples/).
211122

212-
### Callback: print_state
213-
214-
Print all axis states
215-
216-
x +0.00 y +0.00 z +0.00 roll +0.00 pitch +0.00 yaw +0.00 t +0.0
217-
218-
### Callback: print_buttons
219-
220-
Print all buttons states
221-
222-
[ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ]
223123

224124
## Troubleshooting
225125

0 commit comments

Comments
 (0)