197 lines
6.7 KiB
Markdown
197 lines
6.7 KiB
Markdown
# Network setup: PC ↔ AGIBOT A3
|
||
|
||
Everything here is standard LAN networking. Nothing in this file assumes anything
|
||
about the A3's software — that lives in
|
||
[AGIBOT_A3_INTEGRATION.md](AGIBOT_A3_INTEGRATION.md).
|
||
|
||
```
|
||
┌──────────────┐ ┌──────────────┐
|
||
│ Your PC │ │ AGIBOT A3 │
|
||
│ │ same LAN / subnet │ │
|
||
│ browser │ ───────────────────────► │ speech svc │
|
||
│ ↓ │ 192.168.x.x │ ↓ │
|
||
│ backend │ │ speaker │
|
||
└──────────────┘ └──────────────┘
|
||
```
|
||
|
||
The PC and the robot must be able to reach each other by IP. That is the whole
|
||
requirement.
|
||
|
||
---
|
||
|
||
## 1. Put both machines on the same network
|
||
|
||
Ranked by how well they work in practice:
|
||
|
||
| Setup | Latency | Notes |
|
||
| --- | --- | --- |
|
||
| **Wired Ethernet, same switch** | best, ~0.2–1 ms | Ideal for a demo. Nothing to go wrong. |
|
||
| **Both on the same Wi-Fi AP** | ~2–20 ms, variable | Fine, but a crowded venue Wi-Fi is the #1 cause of a bad demo. |
|
||
| **PC wired, robot Wi-Fi (same subnet)** | mixed | Works. Check they are on the same subnet, not two VLANs. |
|
||
| **Direct cable PC ↔ robot** | best | Needs static IPs on both, or link-local. Useful when there is no venue network. |
|
||
| Different subnets / guest Wi-Fi | — | Usually blocked. Guest networks isolate clients from each other. |
|
||
|
||
> **Demo advice:** if you can run a cable, run a cable. Client isolation on a
|
||
> conference Wi-Fi will silently block PC→robot traffic while both devices show
|
||
> "connected to the internet".
|
||
|
||
---
|
||
|
||
## 2. Find the robot's IP address
|
||
|
||
Any of these, easiest first:
|
||
|
||
1. **The robot's own screen / app / teach pendant** — usually shows the IP in a
|
||
network or system settings page. Most reliable.
|
||
2. **Your router's DHCP client list** — log into the router (often
|
||
`192.168.1.1`), look for a newly-connected device.
|
||
3. **Scan the subnet from the PC.** First find your own subnet:
|
||
|
||
```powershell
|
||
ipconfig # look at IPv4 Address, e.g. 192.168.1.23
|
||
```
|
||
|
||
Then sweep it:
|
||
|
||
```powershell
|
||
# Windows: ping every host, then read the ARP table
|
||
1..254 | ForEach-Object { Start-Process -WindowStyle Hidden ping "192.168.1.$_" -ArgumentList "-n 1 -w 200" }
|
||
Start-Sleep 5
|
||
arp -a
|
||
```
|
||
|
||
```bash
|
||
# if you have nmap (any OS) - much better
|
||
nmap -sn 192.168.1.0/24
|
||
```
|
||
|
||
4. **mDNS**, if the robot advertises itself:
|
||
|
||
```bash
|
||
ping agibot-a3.local
|
||
```
|
||
|
||
A hostname works anywhere this project asks for `ROBOT_IP`.
|
||
|
||
> Ask whoever commissions the robot to give it a **DHCP reservation** (a fixed
|
||
> IP tied to its MAC address). Otherwise the IP can change on reboot and you will
|
||
> be editing `.env` before every demo.
|
||
|
||
---
|
||
|
||
## 3. Test reachability
|
||
|
||
```bash
|
||
ping 192.168.1.50
|
||
```
|
||
|
||
| Result | Meaning |
|
||
| --- | --- |
|
||
| Replies with a time | The robot is reachable. Continue. |
|
||
| `Request timed out` | Wrong IP, robot off, different subnet, or ICMP blocked (see below). |
|
||
| `Destination host unreachable` | No route — you are on a different subnet. |
|
||
|
||
**ICMP being blocked does not mean the robot is unreachable.** Some robots drop
|
||
ping but still answer on their service port. Test the port directly:
|
||
|
||
```powershell
|
||
Test-NetConnection 192.168.1.50 -Port 8080
|
||
```
|
||
|
||
```bash
|
||
nc -vz 192.168.1.50 8080 # Linux/macOS
|
||
```
|
||
|
||
Then let this project probe it properly:
|
||
|
||
```bash
|
||
python scripts/discover_robot.py 192.168.1.50
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Configure this app
|
||
|
||
In `.env`:
|
||
|
||
```env
|
||
ROBOT_MODE=real
|
||
ROBOT_IP=192.168.1.50
|
||
ROBOT_PORT=8080
|
||
```
|
||
|
||
Restart the server, or:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8000/api/config/reload
|
||
```
|
||
|
||
The header pill turns green within a few seconds if the connection succeeds. If
|
||
it does not, `GET /api/robot/diagnostics` says exactly what was attempted and
|
||
what failed.
|
||
|
||
---
|
||
|
||
## 5. Firewall
|
||
|
||
The PC makes **outbound** connections to the robot, so a Windows Firewall inbound
|
||
rule is usually unnecessary. Two exceptions:
|
||
|
||
- **`HOST=0.0.0.0`** — you want to open the dashboard from another device.
|
||
Windows will prompt to allow Python on private networks the first time; allow
|
||
it for *Private* networks only, never *Public*.
|
||
- **ROS 2 / DDS transport** — DDS uses multicast discovery and a wide range of
|
||
UDP ports **inbound** to the PC. This is the one case where the firewall
|
||
usually needs a rule:
|
||
|
||
```powershell
|
||
# run as Administrator, only if you use A3_TRANSPORT=ros2
|
||
New-NetFirewallRule -DisplayName "ROS2 DDS" -Direction Inbound -Protocol UDP `
|
||
-LocalPort 7400-7600 -Action Allow -Profile Private
|
||
```
|
||
|
||
DDS discovery is multicast and does **not** cross subnets or most Wi-Fi APs.
|
||
ROS 2 realistically requires the PC and robot on the same wired L2 segment,
|
||
with the same `ROS_DOMAIN_ID`.
|
||
|
||
---
|
||
|
||
## 6. Latency expectations
|
||
|
||
Measured by this app and shown in the header. What to expect on a healthy LAN:
|
||
|
||
| Hop | Typical |
|
||
| --- | --- |
|
||
| Browser → local backend | < 2 ms (loopback) |
|
||
| Backend → robot, wired | 0.5–3 ms |
|
||
| Backend → robot, Wi-Fi | 2–30 ms, occasionally spiking |
|
||
| Robot's own TTS synthesis start | the dominant term — tens to hundreds of ms |
|
||
|
||
The network is almost never the bottleneck; the robot's speech synthesis is. That
|
||
is exactly why this project sends **text** and lets the robot synthesise, instead
|
||
of generating audio on the PC and transferring it.
|
||
|
||
If the header shows latency above ~50 ms on Wi-Fi, move to Ethernet before
|
||
blaming the software.
|
||
|
||
---
|
||
|
||
## 7. Troubleshooting
|
||
|
||
| Symptom | Cause | Fix |
|
||
| --- | --- | --- |
|
||
| Pill stuck on *Connecting…* | Wrong IP or port, robot booting | `ping`, then `discover_robot.py` |
|
||
| `Robot is offline` immediately | Nothing listening on `ROBOT_PORT` | Confirm the port with the discovery script |
|
||
| Ping works, app says offline | Right host, wrong port or path | Check `ROBOT_PORT` and `A3_HTTP_SPEAK_PATH` |
|
||
| Works, then drops after minutes | Wi-Fi roaming, DHCP lease change | Wired connection + DHCP reservation |
|
||
| Connects but nothing is heard | Robot volume, muted speaker, wrong audio sink | Check the robot's own volume first |
|
||
| Fine on the bench, fails at the venue | Client isolation on guest Wi-Fi | Bring your own switch/router |
|
||
| ROS 2 sees no topics | Different `ROS_DOMAIN_ID`, multicast blocked | Same domain ID, same wired segment |
|
||
|
||
Two commands answer most questions:
|
||
|
||
```bash
|
||
python scripts/discover_robot.py <ROBOT_IP> # what the robot exposes
|
||
curl http://localhost:8000/api/robot/diagnostics # what this app tried and saw
|
||
```
|