177 lines
5.2 KiB
Markdown
177 lines
5.2 KiB
Markdown
# raspbot_v2
|
|
|
|
ROS 2 robot platform based on the Yahboom Raspbot V2. Multiple services run as Docker containers, coordinated by Docker Compose.
|
|
|
|
---
|
|
|
|
## Sub-projects
|
|
|
|
| Directory | Description |
|
|
|---|---|
|
|
| [robot/](robot/README.md) | Differential-drive motor control, pan/tilt camera, and ultrasonic range sensor |
|
|
| [lidar/](lidar/README.md) | RPLIDAR A1 laser scanner |
|
|
| [oled/](oled/README.md) | OLED display dashboard |
|
|
| [wifi/](wifi/README.md) | Wi-Fi hotspot fallback manager |
|
|
| [camera_publisher/](camera_publisher/README.md) | V4L2 camera → ROS 2 topic publisher |
|
|
| [webrtc_streamer/](webrtc_streamer/README.md) | WebRTC browser stream server |
|
|
| [webui/](webui/README.md) | Browser-based robot controller |
|
|
| [ansible/](ansible/README.md) | Provisioning playbook for the Raspberry Pi |
|
|
| [teleop/](teleop/README.md) | Keyboard and joystick teleoperation container |
|
|
|
|
---
|
|
|
|
## Setting up the robot
|
|
|
|
### 1. Flash Raspberry Pi OS
|
|
|
|
Use the [Raspberry Pi Imager](https://www.raspberrypi.com/software/) to write Raspberry Pi OS (64-bit, Lite recommended) to a microSD card.
|
|
|
|
Before writing, open **Advanced options** (⚙) and configure:
|
|
|
|
| Setting | Value |
|
|
|---|---|
|
|
| Hostname | `raspbot-v2.local` |
|
|
| SSH | Enabled |
|
|
| Username / Password | Your preferred credentials |
|
|
| Wi-Fi | Your network SSID and password (if not using Ethernet) |
|
|
|
|
Write the image, insert the card, and power on the Pi. Once it is reachable on the network (test with `ping raspbot-v2.local`), proceed to the next step.
|
|
|
|
### 2. Provision with Ansible
|
|
|
|
The [ansible/](ansible/) directory contains a playbook that handles the remaining setup (enabling SPI, installing Docker). See [ansible/README.md](ansible/README.md) for full instructions.
|
|
|
|
---
|
|
|
|
## Building
|
|
|
|
### Prerequisites
|
|
|
|
- Docker with BuildKit enabled
|
|
- For cross-compilation from an amd64 host, register QEMU user-space emulation once:
|
|
|
|
```bash
|
|
docker run --rm --privileged tonistiigi/binfmt --install arm64
|
|
```
|
|
|
|
### Build all images
|
|
|
|
```bash
|
|
docker compose build
|
|
```
|
|
|
|
Or build a single service:
|
|
|
|
```bash
|
|
docker compose build robot
|
|
docker compose build lidar
|
|
```
|
|
|
|
---
|
|
|
|
## Deploying
|
|
|
|
Pipe images directly to the target over SSH — no intermediate file or registry needed:
|
|
|
|
```bash
|
|
# Upload all images
|
|
docker save $(docker compose config --images) | ssh <user>@raspbot-v2.local docker load
|
|
|
|
# Upload a single image
|
|
docker save raspbot_v2_oled:latest | ssh <user>@raspbot-v2.local docker load
|
|
```
|
|
|
|
`docker compose config --images` resolves all image names from the compose file, including any environment variable substitutions.
|
|
|
|
Then copy the compose file and any `.env` to the target:
|
|
|
|
```bash
|
|
scp docker-compose.yml <user>@raspbot-v2.local:~/
|
|
```
|
|
|
|
Replace `<user>` with the username configured in [ansible/inventory.ini](ansible/inventory.ini).
|
|
|
|
---
|
|
|
|
## Launching
|
|
|
|
### Start everything
|
|
|
|
```bash
|
|
docker compose up
|
|
```
|
|
|
|
To run in the background:
|
|
|
|
```bash
|
|
docker compose up -d
|
|
docker compose logs -f # follow logs
|
|
docker compose down # stop and remove containers
|
|
```
|
|
|
|
### Dev container
|
|
|
|
An interactive ROS desktop environment (`osrf/ros:kilted-desktop-full`) is provided for development, visualisation, and ad-hoc `ros2` commands. It shares the host network so it participates in the same DDS domain as the robot.
|
|
|
|
Allow X11 forwarding from Docker (required once per session):
|
|
|
|
```bash
|
|
xhost +local:docker
|
|
```
|
|
|
|
Then launch the container:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml run --rm dev
|
|
```
|
|
|
|
The container drops you into a bash shell with the ROS underlay sourced. Set `FASTDDS_INTERFACE` in your `.env` (or inline) to bind DDS traffic to the correct network interface when connecting over Wi-Fi:
|
|
|
|
```bash
|
|
FASTDDS_INTERFACE=wlp195s0 docker compose -f docker-compose.dev.yml run --rm dev
|
|
```
|
|
|
|
See [teleop/README.md](teleop/README.md#working-out-the-network-interface-to-bind-to) for instructions on identifying the correct interface name.
|
|
|
|
---
|
|
|
|
### Environment variables
|
|
|
|
Create a `.env` file alongside `docker-compose.yml` to override defaults:
|
|
|
|
```bash
|
|
ROS_DOMAIN_ID=0
|
|
LIDAR_PORT=/dev/ttyUSB0
|
|
LIDAR_FRAME_ID=laser
|
|
WIFI_SSID=MyNetwork
|
|
```
|
|
|
|
| Variable | Default | Description |
|
|
|---|---|---|
|
|
| `ROS_DOMAIN_ID` | `0` | ROS 2 domain — must match on all nodes |
|
|
| `LIDAR_PORT` | `/dev/ttyUSB0` | Host device node for the RPLIDAR |
|
|
| `LIDAR_FRAME_ID` | `laser` | `frame_id` in published `LaserScan` messages |
|
|
| `WIFI_SSID` | _(empty)_ | Target SSID; if unset the Wi-Fi container creates a hotspot immediately |
|
|
| `HOTSPOT_SSID` | `raspbot-hotspot` | Fallback hotspot SSID |
|
|
| `HOTSPOT_PASSWORD` | `raspbot1234` | Fallback hotspot passphrase |
|
|
|
|
---
|
|
|
|
## Project layout
|
|
|
|
```
|
|
.
|
|
├── docker-compose.yml
|
|
├── docker-compose.dev.yml # Interactive dev/visualisation container
|
|
├── docker-entrypoint.sh
|
|
├── raspbot_v2/ # ROS 2 packages (control, description, hardware interface)
|
|
├── lidar/ # RPLIDAR A1
|
|
├── oled/ # OLED display dashboard
|
|
├── wifi/ # Wi-Fi hotspot fallback
|
|
├── camera_publisher/ # V4L2 camera → ROS 2 topic
|
|
├── webrtc_streamer/ # WebRTC browser stream
|
|
├── webui/ # Browser-based controller UI
|
|
├── teleop/ # Keyboard and joystick teleoperation
|
|
└── ansible/ # Raspberry Pi provisioning
|
|
```
|