一、基础系统环境准备

1 更新软件源

sudo apt update
sudo apt upgrade -y

安装paho-mqtt

Ubuntu24.04 的 Python3.12 默认开启 PEP‑668 外部环境保护，不允许直接 pip3 install 往系统 Python 装包，优先用虚拟环境

2、先安装虚拟环境工具

sudo apt update
sudo apt install -y python3-venv python3-full

3、在你的项目文件夹创建虚拟环境

假设你的代码文件 robot_main.py 在当前目录，在当前目录下打开终端：

# 创建venv虚拟环境文件夹
python3 -m venv venv_robot

4、激活虚拟环境

source venv_robot/bin/activate

激活成功后终端提示符前面会出现 (venv_robot)

✨此时再 pip 安装，全部装在这个独立虚拟环境，不会触碰系统 Python

pip install requests paho-mqtt psutil

2 安装系统级依赖

sudo apt install -y python3 python3-pip git psmisc net-tools iputils-ping
# ffmpeg用于RTSP推流图传
sudo apt install -y ffmpeg

mediamtx：RTSP 流媒体服务，不能 apt 安装，需要下载对应 amd64 二进制包

# 下载mediamtx(amd64 x86工控机版本)
wget https://github.com/bluenviron/mediamtx/releases/download/v1.10.0/mediamtx_v1.10.0_linux_amd64.tar.gz
mkdir -p ~/mediamtx
tar -xvzf mediamtx_v1.10.0_linux_amd64.tar.gz -C ~/mediamtx

2. 系统 apt 依赖（ffmpeg、摄像头 v4l2、mqtt broker）

① ffmpeg（做 RTSP 推流，代码里 subprocess 调用 ffmpeg）

sudo apt install ffmpeg

② MQTT 服务端 broker（代码连接 127.0.0.1:1883，本地 mosquitto）

代码中机器人 mqtt、AI‑BOX mqtt 都连接本地 1883 端口，必须安装 mosquitto

sudo apt install mosquitto mosquitto-clients
# 设置开机自启并启动
sudo systemctl enable --now mosquitto
# 查看状态
systemctl status mosquitto

③ v4l2 摄像头工具（usb 摄像头 /dev/video0）

sudo apt install v4l-utils
# 查看摄像头是否识别
v4l2-ctl --list-devices

3. ubuntu系统需要放行1883端口

1 修改 mosquitto 配置

sudo nano /etc/mosquitto/mosquitto.conf

文件末尾追加这两行：

listener 1883 0.0.0.0
allow_anonymous true

listener 1883 0.0.0.0：监听本机所有网卡（包含局域网 IP 192.168.0.104） allow_anonymous true：允许无密码连接，调试用；上线务必加账号密码。

保存：Ctrl+O →回车保存，Ctrl+X退出。

2 重启 mosquitto 服务

sudo systemctl restart mosquitto
sudo systemctl status mosquitto

3 再次检查监听端口

sudo ss -tulpn | grep 1883

正确输出应该出现 0.0.0.0:1883，类似：

tcp   LISTEN 0      100          0.0.0.0:1883              0.0.0.0:*    users:(("mosquitto",pid=xxx,fd=xx))
tcp   LISTEN 0      100                 [::]:1883                 [::]:*    users:(("mosquitto",pid=xxx,fd=xx))

注意：还会保留原来 127.0.0.1 那行是正常的，不影响。

4 防火墙放行 1883 端口

sudo ufw allow 1883/tcp
sudo ufw status

使用另外局域网另外一台电脑进行测试，

MQTTX 电脑连接参数

• Broker：192.168.0.104
• Port：1883
• Client ID：随便写，不要用 robot_control / Camera_AI_BOX（会冲突）
• 用户名密码留空