simplified code

2026-07-16 13:29:56 -04:00
parent a5cdb4e4bd
commit bf3e197a20
4 changed files with 199 additions and 68 deletions
@@ -0,0 +1,105 @@
+# 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`.