# 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 # what the robot exposes curl http://localhost:8000/api/robot/diagnostics # what this app tried and saw ```