Lucca Pirovano
106 lines
4.2 KiB
Markdown
106 lines
4.2 KiB
Markdown
# naowalk
|
|
|
|
A keyboard teleop client for the NAO robot: live video, walking, head control,
|
|
two-way audio (hear the robot's mics, make it speak via TTS), and a YouTube
|
|
music player that downloads a track with `yt-dlp` and plays it through the
|
|
robot's own speakers.
|
|
|
|
## Requirements
|
|
|
|
**System packages** (Debian/Ubuntu names — adjust for your OS):
|
|
|
|
```bash
|
|
sudo apt install portaudio19-dev ffmpeg sshpass openssh-client
|
|
```
|
|
|
|
- `portaudio19-dev` — needed to build/install `pyaudio`
|
|
- `ffmpeg` — needed by `yt-dlp` to extract audio to mp3
|
|
- `sshpass` + `openssh-client` — used to `scp` downloaded tracks onto the
|
|
robot and to run `mkdir` over `ssh` (the script assumes the default
|
|
`nao`/`nao` credentials)
|
|
|
|
**NAOqi Python SDK (`qi`)** — not on PyPI. Download the `pynaoqi-python`
|
|
wheel that matches your OS/Python version from the Aldebaran/SoftBank
|
|
Robotics developer site and install it:
|
|
|
|
```bash
|
|
pip install ./pynaoqi-*.whl
|
|
```
|
|
|
|
**Python packages:**
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
python3 naowalk.py --ip <robot-ip> [options]
|
|
```
|
|
|
|
| Flag | Default | Description |
|
|
|---|---|---|
|
|
| `--ip` | `127.0.0.1` | Robot's IP address |
|
|
| `--port` | `9559` | NAOqi port |
|
|
| `--audio-device-index` | auto | Output device index for hearing the robot's mic on your machine |
|
|
| `--mic-channel` | `left` | Which robot mic to stream (`left`, `right`, `front`, `rear`) — pick a working one, see Troubleshooting |
|
|
| `--mic-gain` | `8.0` | Amplification applied to the streamed mic audio |
|
|
| `--video-scale` | `2.0` | Display window scale (base feed is 320x240) |
|
|
|
|
## Controls
|
|
|
|
| Key | Action |
|
|
|---|---|
|
|
| `W`/`A`/`S`/`D` or arrows | Walk forward/turn/back |
|
|
| `I`/`K`/`J`/`L` | Head pitch/yaw |
|
|
| `Space` | Reset head to center |
|
|
| `1` | Wave gesture |
|
|
| `M` | Open music search (type query, `Enter` to search, `↑↓` to select, `Enter`/`1`-`5` to play) |
|
|
| `P` | Pause / resume music (resume restarts the track from the beginning — see Notes) |
|
|
| `X` | Stop music |
|
|
| `-` / `=` | Volume down/up |
|
|
| `T` | Type a message for the robot to speak (TTS) |
|
|
| `Esc` | Quit (or cancel current mode) |
|
|
|
|
## How it works
|
|
|
|
- **`SoundReceiver`** — registered as a NAOqi service that receives the
|
|
robot's mic stream and plays it out your local speakers via `pyaudio`, with
|
|
gain and a prebuffer to smooth out network jitter.
|
|
- **`NaoMusicPlayer`** — searches YouTube with `yt-dlp`, downloads and
|
|
converts the top match to mp3, `scp`s it to the robot, and plays it with
|
|
`ALAudioPlayer`.
|
|
- **`NaoTeleop`** — the main loop: pygame window for video/input, keyboard
|
|
handling, head/walk control, and wiring everything above together.
|
|
|
|
## Notes / design decisions
|
|
|
|
- **No seek.** Seeking was removed entirely — it added the most complexity
|
|
for the least-used feature. `P` is a simple play/stop toggle; resuming
|
|
restarts the track from the beginning rather than tracking a playback
|
|
position.
|
|
- **`moveInit()` on startup.** The robot used to need its walk buttons
|
|
jittered for a few seconds before its first walk would work. `run()` now
|
|
calls `ALMotionProxy::moveInit()` once at startup, which settles the walk
|
|
engine into the right pose before any real move command — this is the
|
|
documented NAOqi fix for exactly this symptom.
|
|
- **`_safe()` helper.** Most one-off NAOqi calls (setting angles, volume,
|
|
stopping movement, unsubscribing services) are wrapped in a small
|
|
`self._safe(label, fn)` helper instead of a repeated `try/except` block, so
|
|
one failed call logs and moves on without crashing the teleop loop or the
|
|
shutdown sequence.
|
|
|
|
## Troubleshooting
|
|
|
|
- **Mic sounds dead / silent on one channel:** some robots have one or more
|
|
physical mics that produce no signal. Test all four with a quick energy
|
|
check, then pick a working channel with `--mic-channel`.
|
|
- **Robot falls over on the very first walk command:** make sure you're on a
|
|
build that includes the `moveInit()` startup call described above; if it's
|
|
still happening, increase the `time.sleep(1.0)` after `goToPosture` to give
|
|
the posture more time to settle first.
|
|
- **`scp`/`ssh` failures for music:** confirm the robot is reachable at
|
|
`--ip` and that `nao`/`nao` are still the correct credentials; the script
|
|
hardcodes them via `sshpass`.
|