From 9ff1d9a4d33f597847b34d2c9fd892b307215548 Mon Sep 17 00:00:00 2001 From: Twirre Date: Thu, 11 Dec 2025 10:58:56 +0000 Subject: [PATCH] Improve installation instructions --- .gitignore | 2 + README.md | 106 ++++------------------------------- docs/installation/linux.md | 75 +++++++++++++++++++++++++ docs/installation/macos.md | 106 +++++++++++++++++++++++++++++++++++ docs/installation/windows.md | 44 +++++++++++++++ 5 files changed, 237 insertions(+), 96 deletions(-) create mode 100644 docs/installation/linux.md create mode 100644 docs/installation/macos.md create mode 100644 docs/installation/windows.md diff --git a/.gitignore b/.gitignore index 8be1803..6b42733 100644 --- a/.gitignore +++ b/.gitignore @@ -220,3 +220,5 @@ __marimo__/ # Docs docs/* !docs/conf.py +!docs/installation/ +!docs/installation/** diff --git a/README.md b/README.md index 37458df..64a4e2a 100644 --- a/README.md +++ b/README.md @@ -8,90 +8,21 @@ This is an implementation for the Pepper robot, using the Pepper SDK and Python ## Installation -### Linux (or WSL) +- [Linux](./docs/installation/linux.md) +- [macOS](./docs/installation/macos.md) +- [Windows](./docs/installation/windows.md) -Start off by installing [Pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) and walk through the steps outlined there (be sure to also add it to PATH). Also install the [Python build requirements](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). Afterwards, install Python 2.7 and activate it for your current shell: + + +### Git Hooks + +To activate automatic linting, formatting, branch name checks and commit message checks, run (after installing requirements): ```bash -pyenv install 2.7 -pyenv shell 2.7 +pre-commit install +pre-commit install --hook-type commit-msg ``` -You can check that this worked by typing - -```bash -python -V -``` - -Which should return `Python 2.7.18`. - -Next, `cd` into this repository and create (and activate) a virtual environment: - -```bash -cd / -python -m pip install virtualenv -python -m virtualenv .venv -source .venv/bin/activate -``` - -We depend on PortAudio for the `pyaudio` package, so install it with: - -```bash -sudo apt install -y portaudio19-dev -``` - -On WSL, also install: - -```bash -sudo apt install -y libasound2-plugins -``` - -Install the required packages with - -```bash -pip install -r requirements.txt -``` - -Now we need to install the NaoQi SDK into our virtual environment, which we need to do manually. Begin by downloading the SDK: - -```bash -wget https://community-static.aldebaran.com/resources/2.5.10/Python%20SDK/pynaoqi-python2.7-2.5.7.1-linux64.tar.gz -``` - -Next, move into the `site-packages` directory and extract the file you just downloaded: - -```bash -cd .venv/lib/python2.7/site-packages/ -tar xvfz /pynaoqi-python2.7-2.5.7.1-linux64.tar.gz -rm /pynaoqi-python2.7-2.5.7.1-linux64.tar.gz -``` - -Lastly, we need to inform our virtual environment where to find our newly installed package: - -```bash -echo /.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.5.7.1-linux64/lib/python2.7/site-packages/ > pynaoqi-python2.7.pth -``` - -That's it! Verify that it works with - -```bash -python -c "import qi; print(qi)" -``` - -You should now be able to run this project. - -### macOS - -Similar to Linux, but don't bother installing `pyenv` as it won't be able to install Python 2 on Apple Silicon. Instead, install Python 2.7.18 from the [Python website](https://www.python.org/downloads/release/python-2718/). - -Create the virtual environment as described above in the Linux section. Stop at the point where it shows you how to download the NaoQi SDK. Instead, use: - -```shell -curl -OL https://community-static.aldebaran.com/resources/2.5.10/Python%20SDK/pynaoqi-python2.7-2.5.7.1-mac64.tar.gz -``` - -Then resume the steps from above. - ## Usage @@ -134,23 +65,6 @@ For coverage, add `--cov=robot_interface` as an argument to `pytest`. -## Git Hooks - -To activate automatic linting, formatting, branch name checks and commit message checks, run (after installing requirements): - -```bash -pre-commit install -pre-commit install --hook-type commit-msg -``` - -You might get an error along the lines of `Can't install pre-commit with core.hooksPath` set. To fix this, simply unset the hooksPath by running: - -```bash -git config --local --unset core.hooksPath -``` - -Then run the pre-commit install commands again. - ## Documentation Generate documentation web pages using: diff --git a/docs/installation/linux.md b/docs/installation/linux.md new file mode 100644 index 0000000..742a87c --- /dev/null +++ b/docs/installation/linux.md @@ -0,0 +1,75 @@ +# Installation + +Of the Pepper Robot Interface on Linux (or WSL). + +Start off by installing [Pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) and walk through the steps outlined there (be sure to also add it to PATH). Also install the [Python build requirements](https://github.com/pyenv/pyenv/wiki#suggested-build-environment). Afterwards, install Python 2.7 and activate it for your current shell: + +```bash +pyenv install 2.7 +pyenv shell 2.7 +``` + +You can check that this worked by typing + +```bash +python -V +``` + +Which should return `Python 2.7.18`. + +Next, `cd` into this repository and create (and activate) a virtual environment: + +```bash +cd / +python -m pip install virtualenv +python -m virtualenv .venv +source .venv/bin/activate +``` + +We depend on PortAudio for the `pyaudio` package, so install it with: + +```bash +sudo apt install -y portaudio19-dev +``` + +On WSL, also install: + +```bash +sudo apt install -y libasound2-plugins +``` + +Install the required packages with + +```bash +pip install -r requirements.txt +``` + +Now we need to install the NaoQi SDK into our virtual environment, which we need to do manually. Begin by downloading the SDK: + +```bash +wget https://community-static.aldebaran.com/resources/2.5.10/Python%20SDK/pynaoqi-python2.7-2.5.7.1-linux64.tar.gz +``` + +Next, move into the `site-packages` directory and extract the file you just downloaded: + +```bash +cd .venv/lib/python2.7/site-packages/ +tar xvfz /pynaoqi-python2.7-2.5.7.1-linux64.tar.gz +rm /pynaoqi-python2.7-2.5.7.1-linux64.tar.gz +``` + +Lastly, we need to inform our virtual environment where to find our newly installed package: + +```bash +echo /.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.5.7.1-linux64/lib/python2.7/site-packages/ > pynaoqi-python2.7.pth +``` + +That's it! Verify that it works with + +```bash +python -c "import qi; print(qi)" +``` + +You should now be able to run this project. + +See the README for how to run. diff --git a/docs/installation/macos.md b/docs/installation/macos.md new file mode 100644 index 0000000..6eac59d --- /dev/null +++ b/docs/installation/macos.md @@ -0,0 +1,106 @@ +# Installation + +Of the Pepper Robot Interface on macOS. + + + +## Python 2.7 + +Install Python 2.7.18 from the [Python website](https://www.python.org/downloads/release/python-2718/). + +Check that it worked by executing + +```shell +python2 -V +``` + +Which should return Python 2.7.18. + + + +## Virtual Environment + +Next, cd into this repository and create (and activate) a virtual environment: + +```shell +cd /path/to/project/ +python2 -m pip install virtualenv +python2 -m virtualenv .venv +source .venv/bin/activate +``` + +We depend on PortAudio for the `pyaudio` package. If on Intel, run `brew install portaudio`. If on Apple Silicon, compile manually using the steps described in [the YouTrack article](https://utrechtuniversity.youtrack.cloud/articles/N25B-A-22/Install-PyAudio-for-Python-2-on-Apple-Silicon). + +Then install the required Python packages with + +```shell +pip install -r requirements.txt +``` + + + +## NaoQi SDK + +We need to manually install the NaoQi SDK into our virtual environment. There are two options: + +1. Install a newer version (2.8) which will make running easier, but compatibility is uncertain. +2. Install the version expected by the robot (2.5). This will complicate running slightly. + +### Option 1 + +Download the SDK from [twirre.io](https://twirre.io/files/pynaoqi-python2.7-2.8.6.23-mac64-20191127_144231.tar.gz), or find one on the Aldebaran website, or an archived version on Web Archive. + +Extract it to `/path/to/project/.venv/lib/python2.7/site-packages/`. + +We need to inform our virtual environment where to find our newly installed package: + +```bash +echo "/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.8.6.23-mac64-20191127_144231/lib/python2.7/site-packages/" > /path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7.pth +``` + +Now continue with [verifying](#verifying). + +### Option 2 + +This method of installation requires setting the `DYLD_LIBRARY_PATH` environment variable before running. How will be explained. + +Download the SDK from [twirre.io](https://twirre.io/files/pynaoqi-2.5.7.1-mac64-deps.tar.gz). This is a modified version of the one from Aldebaran, this one including required Choregraphe dependencies. + +Extract it to `/path/to/project/.venv/lib/python2.7/site-packages/`. + +We need to inform our virtual environment where to find our newly installed package: + +```shell +echo "/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.5.7.1-mac64/lib/python2.7/site-packages/" > /path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7.pth +``` + +Now, anytime before running you need to set the `DYLD_LIBRARY_PATH` environment variable. + +```shell +export DYLD_LIBRARY_PATH="/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.5.7.1-mac64/choregraphe_lib:${DYLD_LIBRARY_PATH}" +``` + +You may want to simplify environment activation with a script `activate.sh` like: + +```shell +#!/bin/zsh + +export DYLD_LIBRARY_PATH="/path/to/project/.venv/lib/python2.7/site-packages/pynaoqi-python2.7-2.8.6.23-mac64-20191127_144231/choregraphe_lib:${DYLD_LIBRARY_PATH}" +source .venv/bin/activate +``` + +[Verify](#verifying) if it works. + + + +## Verifying + +Verify that the NaoQI SDK installation works with + +```bash +python -c "import qi; print(qi)" +``` + +If so, you should now be able to run this project. + +See the README for how to run. diff --git a/docs/installation/windows.md b/docs/installation/windows.md new file mode 100644 index 0000000..b56453e --- /dev/null +++ b/docs/installation/windows.md @@ -0,0 +1,44 @@ +# Installation + +Of the Pepper Robot Interface on Windows. + +Install Python 2.7.18 from [the Python website](https://www.python.org/downloads/release/python-2718/), choose the x86-64 installer (at the bottom of the page). + +To see if it worked: + +```shell +py -2 -V +``` + +Which should return `Python 2.7.18`. + +Next, `cd` into this repository and create (and activate) a virtual environment: + +```bash +cd / +py -2 -m pip install virtualenv +py -2 -m virtualenv .venv +.\.venv\Scripts\activate +``` + +Install the required packages with + +```bash +pip install -r requirements.txt +``` + +Now we need to install the NaoQi SDK into our virtual environment, which we need to do manually. Download the SDK from [Aldebaran](https://community-static.aldebaran.com/resources/2.5.5/sdk-python/pynaoqi-python2.7-2.5.5.5-win32-vs2013.zip), [Web Archive](https://web.archive.org/web/20240120111043/https://community-static.aldebaran.com/resources/2.5.5/sdk-python/pynaoqi-python2.7-2.5.5.5-win32-vs2013.zip) or [twirre.io](https://twirre.io/files/pynaoqi-python2.7-2.8.6.23-win64-vs2015-20191127_152649.zip). + +Extract to `.\.venv\Lib\site-packages`. + +Create a file `.venv\Lib\site-packages\pynaoqi-python2.7.pth`, put the full path of `pynaoqi-python2.7-2.8.6.23-win64-vs2015-20191127_152649\lib\python2.7\Lib\site-packages` in there. + +Test if it worked by running: + +```bash +python -c "import qi; print(qi)" +``` + +You should now be able to run this project. + +See the README for how to run.