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.

   ┌──────────────┐                          ┌──────────────┐
   │   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:

The robot's own screen / app / teach pendant — usually shows the IP in a network or system settings page. Most reliable.
Your router's DHCP client list — log into the router (often 192.168.1.1), look for a newly-connected device.

Scan the subnet from the PC. First find your own subnet:

ipconfig                      # look at IPv4 Address, e.g. 192.168.1.23

Then sweep it:

# 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

# if you have nmap (any OS) - much better
nmap -sn 192.168.1.0/24

mDNS, if the robot advertises itself:
```
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

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:

Test-NetConnection 192.168.1.50 -Port 8080

nc -vz 192.168.1.50 8080          # Linux/macOS

Then let this project probe it properly:

python scripts/discover_robot.py 192.168.1.50

4. Configure this app

In .env:

ROBOT_MODE=real
ROBOT_IP=192.168.1.50
ROBOT_PORT=8080

Restart the server, or:

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:
```
# 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:

python scripts/discover_robot.py <ROBOT_IP>     # what the robot exposes
curl http://localhost:8000/api/robot/diagnostics # what this app tried and saw

6.7 KiB Raw Blame History Unescape Escape