Update MacOS doc

JakubAndrysek · Apr 20, 2024 · 87293ad · 87293ad
1 parent 3470c9a
commit 87293ad
Show file tree

Hide file tree

Showing 6 changed files with 217 additions and 20 deletions.
diff --git a/Makefile b/Makefile
@@ -36,6 +36,7 @@ run-demo:
 fixRelativeLinkDocs:
 	sed  's/\.\/docs/\./g'  README.md > docs/README.md
 	sed  's/\.\/docs/\./g'  CONTRIBUTING.md > docs/CONTRIBUTING.md
+	sed  's/\.\/docs/\./g'  troubleshooting.md > docs/troubleshooting.md
 
 # Docs
 docs-build: fixRelativeLinkDocs

diff --git a/README.md b/README.md
@@ -93,6 +93,7 @@ pip install pyspacemouse
         - In case of problem with M1 chip, try to run you code with Rosseta 2
             - How to use Rosseta 2 - [Setup Rosetta](https://apple.stackexchange.com/questions/428768/on-apple-m1-with-rosetta-how-to-open-entire-terminal-iterm-in-x86-64-architec)
         - Tested and developed by [consi](https://github.com/JakubAndrysek/PySpaceMouse/issues/10#issuecomment-1768362007) - thanks!
+        - More info in [Troubleshooting - Mac OS (M1)](./troubleshooting.md#mac-os-m1) page.
 
 - [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms
     - `pip install git+https://github.com/bglopez/python-easyhid.git`
@@ -163,6 +164,8 @@ if __name__ == '__main__':
 
 ## API
 
+The module-level API is as follows:
+
     open(callback=None, button_callback=None, button_callback_arr=None, set_nonblocking_loop=True, device=None)
         Open a 3D space navigator device. Makes this device the current active device, which enables the module-level read() and close()
         calls. For multiple devices, use the read() and close() calls on the returned object instead, and don't use the module-level calls.
@@ -181,8 +184,8 @@ if __name__ == '__main__':
     close()             Close the connection to the current device, if it is open
     list_devices()      Return a list of supported devices found, or an empty list if none found
 
-open() returns a DeviceSpec object. If you have multiple 3Dconnexion devices, you can use the object-oriented API to
-access them individually.
+`open()` returns a DeviceSpec object.
+If you have multiple 3Dconnexion devices, you can use the object-oriented API to access them individually.
 Each object has the following API, which functions exactly as the above API, but on a per-device basis:
 
     dev.open()          Opens the connection (this is always called by the module-level open command,
@@ -222,11 +225,4 @@ Print all buttons states
 
 ## Troubleshooting
 
-### ModuleNotFoundError: No module named 'easyhid'
-
-- Install `easyhid` by `pip install easyhid`.
-
-### AttributeError: function/symbol 'hid_enumerate' not found in library '<None>': python3: undefined symbol: hid_enumerate
-
-- HID library for your computer is not installed.
-- Follow the instructions in [requirements](#requirements).
+Look at the [Troubleshooting](./troubleshooting.md) page for help with common issues.
diff --git a/docs/README.md b/docs/README.md
@@ -35,6 +35,7 @@ Control a [robot](https://roboruka.robotickytabor.cz/) with a Space Mouse
 * SpaceMouse Compact
 * SpacePilot
 * SpacePilot Pro
+* SpaceMouse Enterprise
 * [Add more devices](https://github.com/johnhw/pyspacenavigator/issues/1)
 
 ## Installation
@@ -60,6 +61,15 @@ pip install pyspacemouse
             sudo usermod -aG plugdev $USER
             newgrp plugdev
             ```
+            <details>
+            <summary>Aleternative option - with tee (RPi)</summary>
+            <pre>
+            echo 'KERNEL=="hidraw*", SUBSYSTEM=="hidraw", MODE="0664", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-hidraw-permissions.rules
+            sudo usermod -aG plugdev $USER
+            newgrp plugdev
+            </pre>
+            </details>
+
 
     - ### Windows
         - Install the latest release of hidapi.dll and hidapi.lib from
@@ -80,6 +90,7 @@ pip install pyspacemouse
         - In case of problem with M1 chip, try to run you code with Rosseta 2
             - How to use Rosseta 2 - [Setup Rosetta](https://apple.stackexchange.com/questions/428768/on-apple-m1-with-rosetta-how-to-open-entire-terminal-iterm-in-x86-64-architec)
         - Tested and developed by [consi](https://github.com/JakubAndrysek/PySpaceMouse/issues/10#issuecomment-1768362007) - thanks!
+        - More info in [Troubleshooting - Mac OS (M1)](./troubleshooting.md#mac-os-m1) page.
 
 - [easyhid](https://github.com/bglopez/python-easyhid) is `hidapi` interface for Python - required on all platforms
     - `pip install git+https://github.com/bglopez/python-easyhid.git`
@@ -147,6 +158,8 @@ if __name__ == '__main__':
 
 ## API
 
+The module-level API is as follows:
+
     open(callback=None, button_callback=None, button_callback_arr=None, set_nonblocking_loop=True, device=None)
         Open a 3D space navigator device. Makes this device the current active device, which enables the module-level read() and close()
         calls. For multiple devices, use the read() and close() calls on the returned object instead, and don't use the module-level calls.
@@ -165,8 +178,8 @@ if __name__ == '__main__':
     close()             Close the connection to the current device, if it is open
     list_devices()      Return a list of supported devices found, or an empty list if none found
 
-open() returns a DeviceSpec object. If you have multiple 3Dconnexion devices, you can use the object-oriented API to
-access them individually.
+`open()` returns a DeviceSpec object. 
+If you have multiple 3Dconnexion devices, you can use the object-oriented API to access them individually.
 Each object has the following API, which functions exactly as the above API, but on a per-device basis:
 
     dev.open()          Opens the connection (this is always called by the module-level open command,
@@ -206,11 +219,4 @@ Print all buttons states
 
 ## Troubleshooting
 
-### ModuleNotFoundError: No module named 'easyhid'
-
-- Install `easyhid` by `pip install easyhid`.
-
-### AttributeError: function/symbol 'hid_enumerate' not found in library '<None>': python3: undefined symbol: hid_enumerate
-
-- HID library for your computer is not installed.
-- Follow the instructions in [requirements](#requirements).
+Look at the [Troubleshooting](./troubleshooting.md) page for help with common issues.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
@@ -0,0 +1,96 @@
+# Troubleshooting
+
+If you encounter any issues, you can find help in the following section.
+
+## Common issues
+
+### ModuleNotFoundError: No module named 'easyhid'
+
+- Install `easyhid` by `pip install easyhid`.
+
+### AttributeError: function/symbol 'hid_enumerate' not found in library '<None>': python3: undefined symbol: hid_enumerate
+
+- HID library for your computer is not installed.
+- Follow the instructions in [requirements](./README.md#dependencies).
+
+<hr>
+
+## Mac OS (M1)
+
+!!! info "External dependencies"
+    You don't have to install original 3Dconnexion driver `3DxWare 10`. This library works directly with `hidapi` device interface.
+
+If you are using a Mac with an M1 chip or newer, you may encounter issues when installing the dependencies.
+Required dependency is `hidapi` which you can install using Homebrew `brew install hidapi`.
+
+By  default, the `hidapi` library is installed in `/opt/homebrew/Cellar/hidapi/0.14.0/lib` directory, and you need to add it to your `DYLD_LIBRARY_PATH` environment variable.
+It is possible to add it to your `.bashrc` or `.zshrc` file, but you can also add it directly in the terminal (only for the current session).
+
+Replace `0.14.0` with the version you have installed on your system (`brew info hidapi`).
+```bash
+export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH
+```
+
+In case of changes in MacOS M1, architecture name, you have to use patched version of `easyhid` library.
+Updated version is not yet available on PyPi, so you have to uninstall the current version and install the patched version from GitHub.
+```bash
+pip install git+https://github.com/bglopez/python-easyhid.git
+```
+
+After this setup everything works correctly directly on MacOS M1.
+Tested on:
+- MacBook Pro 14 (M1 Pro, 2021)
+- ??? (add your device and feedback)
+
+I have probably tested it also in Rosetta 2 mode, but right now it works directly on M1 chip with python from `brew`.
+
+<hr>
+
+## Testing Hidapi
+
+If you are not sure if `hidapi` is installed correctly, you can test it with the console tool [hidapitester](https://github.com/todbot/hidapitester).
+This tool provides a simple interface to test the communication with HID devices.
+On GitHub, you can find the source code and precompiled binaries for Windows, Linux, and Mac OS.
+
+Just download the binary for your system and run it in the terminal.
+
+List connected devices:
+```bash
+./hidapitester --list
+```
+??? note "My output"
+    ```bash
+    046D/C626: 3Dconnexion - SpaceNavigator
+    045E/07A5: Microsoft - Microsoft 2.4GHz Transceiver v9.0
+    ...
+    ```
+Read data from the device (replace `<VID/PID>` with the VID/PID of your device):
+```bash
+./hidapitester --vidpid <VID/PID> --open --read-input
+```
+
+??? note "My output"
+    ```bash
+    ./hidapitester --vidpid 046D/C626 --open --read-input
+    Opening device, vid/pid: 0x046D/0xC626
+    Reading 64-byte input report 0, 250 msec timeout...read 7 bytes:
+    01 76 00 00 00 FA FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    Closing device
+    ```
+
+Read descriptor from the device (replace `<VID/PID>` with the VID/PID of your device):
+```bash
+./hidapitester --vidpid <VID/PID> --open --get-report-descriptor
+```
+
+??? note "My output"
+    ```bash
+    ./hidapitester --vidpid 046D/C626 --open --get-report-descriptor
+    Opening device, vid/pid: 0x046D/0xC626
+    Report Descriptor:
+    05 01 09 08 A1 01 A1 00 85 01 16 A2 FE 26 5E 01 36 88 FA 46 78 05 55 0C 65 11 09 30 09 31 09 32
+    75 10 95 03 81 06 C0 A1 00 85 02 09 33 09 34 09 35 75 10 95 03 81 06 C0 A1 02 85 03 05 01 05 09
+    ...
+    Closing device
+    ```
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -98,6 +98,8 @@ markdown_extensions:
 nav:
   - Home: 'README.md'
   - Contributing: 'CONTRIBUTING.md'
+  - Troubleshooting: 'troubleshooting.md'
+
   - API:
       - mouseApi/index.md
       - 'Links': 'mouseApi/links.md'

diff --git a/troubleshooting.md b/troubleshooting.md
@@ -0,0 +1,96 @@
+# Troubleshooting
+
+If you encounter any issues, you can find help in the following section.
+
+## Common issues
+
+### ModuleNotFoundError: No module named 'easyhid'
+
+- Install `easyhid` by `pip install easyhid`.
+
+### AttributeError: function/symbol 'hid_enumerate' not found in library '<None>': python3: undefined symbol: hid_enumerate
+
+- HID library for your computer is not installed.
+- Follow the instructions in [requirements](./README.md#dependencies).
+
+<hr>
+
+## Mac OS (M1)
+
+!!! info "External dependencies"
+    You don't have to install original 3Dconnexion driver `3DxWare 10`. This library works directly with `hidapi` device interface.
+
+If you are using a Mac with an M1 chip or newer, you may encounter issues when installing the dependencies.
+Required dependency is `hidapi` which you can install using Homebrew `brew install hidapi`.
+
+By  default, the `hidapi` library is installed in `/opt/homebrew/Cellar/hidapi/0.14.0/lib` directory, and you need to add it to your `DYLD_LIBRARY_PATH` environment variable.
+It is possible to add it to your `.bashrc` or `.zshrc` file, but you can also add it directly in the terminal (only for the current session).
+
+Replace `0.14.0` with the version you have installed on your system (`brew info hidapi`).
+```bash
+export DYLD_LIBRARY_PATH=/opt/homebrew/Cellar/hidapi/0.14.0/lib:$DYLD_LIBRARY_PATH
+```
+
+In case of changes in MacOS M1, architecture name, you have to use patched version of `easyhid` library.
+Updated version is not yet available on PyPi, so you have to uninstall the current version and install the patched version from GitHub.
+```bash
+pip install git+https://github.com/bglopez/python-easyhid.git
+```
+
+After this setup everything works correctly directly on MacOS M1.
+Tested on:
+- MacBook Pro 14 (M1 Pro, 2021)
+- ??? (add your device and feedback)
+
+I have probably tested it also in Rosetta 2 mode, but right now it works directly on M1 chip with python from `brew`.
+
+<hr>
+
+## Testing Hidapi
+
+If you are not sure if `hidapi` is installed correctly, you can test it with the console tool [hidapitester](https://github.com/todbot/hidapitester).
+This tool provides a simple interface to test the communication with HID devices.
+On GitHub, you can find the source code and precompiled binaries for Windows, Linux, and Mac OS.
+
+Just download the binary for your system and run it in the terminal.
+
+List connected devices:
+```bash
+./hidapitester --list
+```
+??? note "My output"
+    ```bash
+    046D/C626: 3Dconnexion - SpaceNavigator
+    045E/07A5: Microsoft - Microsoft 2.4GHz Transceiver v9.0
+    ...
+    ```
+Read data from the device (replace `<VID/PID>` with the VID/PID of your device):
+```bash
+./hidapitester --vidpid <VID/PID> --open --read-input
+```
+
+??? note "My output"
+    ```bash
+    ./hidapitester --vidpid 046D/C626 --open --read-input
+    Opening device, vid/pid: 0x046D/0xC626
+    Reading 64-byte input report 0, 250 msec timeout...read 7 bytes:
+    01 76 00 00 00 FA FF 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+    Closing device
+    ```
+
+Read descriptor from the device (replace `<VID/PID>` with the VID/PID of your device):
+```bash
+./hidapitester --vidpid <VID/PID> --open --get-report-descriptor
+```
+
+??? note "My output"
+    ```bash
+    ./hidapitester --vidpid 046D/C626 --open --get-report-descriptor
+    Opening device, vid/pid: 0x046D/0xC626
+    Report Descriptor:
+    05 01 09 08 A1 01 A1 00 85 01 16 A2 FE 26 5E 01 36 88 FA 46 78 05 55 0C 65 11 09 30 09 31 09 32
+    75 10 95 03 81 06 C0 A1 00 85 02 09 33 09 34 09 35 75 10 95 03 81 06 C0 A1 02 85 03 05 01 05 09
+    ...
+    Closing device
+    ```