Improve installation instructions
This commit is contained in:
Twirre
committed by
Luijkx,S.O.H. (Storm)
Luijkx,S.O.H. (Storm)
parent
c86eda497c
commit
9ff1d9a4d3
2
.gitignore
vendored
2
.gitignore
vendored
@@ -220,3 +220,5 @@ __marimo__/
|
||||
# Docs
|
||||
docs/*
|
||||
!docs/conf.py
|
||||
!docs/installation/
|
||||
!docs/installation/**
|
||||
|
||||
106
README.md
106
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 <path to project>/
|
||||
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 <path to SDK>/pynaoqi-python2.7-2.5.7.1-linux64.tar.gz
|
||||
rm <path to SDK>/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 <path to project>/.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:
|
||||
|
||||
|
||||
75
docs/installation/linux.md
Normal file
75
docs/installation/linux.md
Normal file
@@ -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 <path to project>/
|
||||
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 <path to SDK>/pynaoqi-python2.7-2.5.7.1-linux64.tar.gz
|
||||
rm <path to SDK>/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 <path to project>/.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.
|
||||
106
docs/installation/macos.md
Normal file
106
docs/installation/macos.md
Normal file
@@ -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.
|
||||
44
docs/installation/windows.md
Normal file
44
docs/installation/windows.md
Normal file
@@ -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 <path to project>/
|
||||
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.
|
||||
Reference in New Issue
Block a user