Skip to content

About

上海交通大学工程学导论项目——自动溶液配制与滴定智能体

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

ChemAuto-Agent

上海交通大学工程学导论课程项目:自动溶液配制与滴定智能体。

当前仓库提供项目的软件 Agent 框架。现阶段已经拆分为两个任务入口:

  • Solution_Preparation_Agent.py:自动溶液配制 Agent,当前主要可运行版本。
  • Titration_Agent.py:酸碱滴定曲线自动绘制 Agent,作为后续开发入口。

命令行智能体和桌面 GUI 的完整操作步骤见 USAGE_GUIDE.md。

当前重点

现阶段重点是“自动溶液配制”。DeepSeek 大模型负责理解自然语言、完成浓度计算,并通过串口向 Arduino 发送蠕动泵控制指令。

当前 Solution_Preparation_Agent.py 支持:

  • 使用 DeepSeek 在线模型解析自然语言实验任务
  • 根据 C1V1 = C2V2 完成基础稀释计算
  • 调用工具控制蠕动泵抽取酸液或去离子水
  • 通过串口向 Arduino 发送真实泵控指令
  • 通过同一串口按需读取 pH 计数据
  • 记录当前实验台中已加入的酸液、水和总液量

泵控和 pH 采集已经集成到同一个 Arduino 固件中。GUI 会在左侧状态区自动刷新最近 pH;自动滴定和滴定曲线绘制仍将在 Titration_Agent.py 中实现。

文件结构

chem_auto_desktop.py                                  # 桌面 GUI 控制台:配液配置、自然语言、手动泵控、实时 pH、设置与日志
Solution_Preparation_Agent.py                         # 溶液配制 Agent:DeepSeek + 共享串口泵控/pH
Titration_Agent.py                                    # 滴定曲线 Agent:后续开发入口
USAGE_GUIDE.md                                        # CLI 与桌面 GUI 完整使用说明
ino/AutoLab_Combined_Controller/                      # 当前必须烧录的泵控与 pH 合并固件
  AutoLab_Combined_Controller.ino
ino/peristaltic_pump_v2_1/peristaltic_pump_v2_1.ino   # 独立泵控测试程序
ino/Calibrated_ph_meter/Calibrated_ph_meter.ino       # 独立 pH 测试程序
ino/motor_readme.md                                   # 蠕动泵驱动说明
ino/ph_readme.md                                      # pH 计使用与校准说明
requirements.txt                                      # 运行依赖
requirements-dev.txt                                  # 打包依赖
scripts/build_macos_dmg.sh                            # macOS DMG 打包脚本
scripts/build_windows_exe.ps1                         # Windows EXE 打包脚本

硬件与串口协议

正式运行 Agent 时使用合并固件:

ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino

Arduino 串口设置:

baud rate: 9600
line ending: Newline

泵与 Arduino 轴的约定:

  • X 轴泵:酸液泵,Agent 中的 pump_id="acid"
  • Y 轴泵:去离子水泵,Agent 中的 pump_id="water"。当前硬件接线下 Y 轴方向与 Arduino 默认方向相反,因此 Python 端已将 water 进液映射为 yo。

Python 端发送的实际指令格式来自 Arduino v2.1:

xi 600 5.000
yo 600 5.000
s
e0
status
ph
phstatus

其中 xi 表示 X 轴酸液泵进液,yo 表示当前硬件下的 Y 轴去离子水泵进液,600 是步进速度,最后一个数字是运行秒数。

合并固件持续在后台采样 pH,但默认不自动向串口输出。Python 在需要读数时发送 ph,从而避免 pH 日志与泵命令响应混杂。

Agent 工具

当前 Solution_Preparation_Agent.py 使用 DeepSeek 的 OpenAI-compatible API 实现工具调用循环,暴露给大模型的工具包括:

  • pump_liquid:控制酸液泵或去离子水泵抽取指定体积;长时间运行会按安全上限自动分段
  • run_pump_seconds:按秒运行指定蠕动泵,用于排气、预灌、清洗和标定
  • get_lab_state:查询当前实验台状态
  • reset_lab_state:重置 Python 端记录的实验台状态
  • stop_pumps:停止蠕动泵,普通停止会执行防滴漏回抽
  • get_pump_controller_status:向 Arduino 发送 status 并读取返回
  • read_ph:通过合并固件按需读取当前 pH

磁力搅拌器默认常开,不由 Agent 控制。

运行方式

1. 安装依赖

当前代码依赖 Python 3,以及以下库:

  • openai
  • httpx[socks]
  • pyserial

可以直接安装仓库中的依赖文件:

python3 -m pip install -r requirements.txt

在 macOS 上,如果 python3 指向没有 Tk 的 Anaconda 环境,请改为:

/usr/local/bin/python3 -m pip install -r requirements.txt

1.1 启动桌面 GUI 控制台

如果不想使用纯 CLI,可以启动桌面版控制台:

python3 chem_auto_desktop.py

建议使用 Python 3.11 或更新版本。macOS 自带的 /usr/bin/python3 可能会因为系统 Tcl/Tk 版本过旧而无法启动桌面窗口;如果遇到 Tk 报错,请改用 Homebrew 或 python.org 安装的 Python。

当前 GUI 会在检测到 Anaconda 缺少 _tkinter 时自动尝试切换到 /usr/local/bin/python3。也可以直接运行:

/usr/local/bin/python3 chem_auto_desktop.py

桌面版包含:

  • 自然语言实验指令面板
  • 配液配置与示例计算面板
  • 手动泵控面板
  • 左侧实时 pH 数值区
  • 串口、模型、API Key 设置页
  • 实验台状态与安全停止按钮

当前项目允许在 Solution_Preparation_Agent.py 中配置默认 DeepSeek API Key。GUI 的 API Key 输入框留空时会使用代码内置值;填写后会优先使用 GUI 配置,也可以通过环境变量覆盖:

AUTOLAB_API_KEY=你的DeepSeekKey python3 chem_auto_desktop.py

桌面 GUI 使用说明

桌面 GUI 的入口文件是:

chem_auto_desktop.py

推荐完整启动流程如下。

1. 启动前检查

  1. 确认 Arduino 已烧录泵控与 pH 合并程序:
ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino
  1. 确认 Arduino IDE 的 Serial Monitor 已关闭。Serial Monitor 如果占用串口,GUI 会无法连接 Arduino。

  2. 确认硬件连接符合当前约定:

acid  -> X 轴泵,Python 发送 xi
water -> Y 轴泵,当前硬件方向反向,Python 发送 yo
baud rate -> 9600
line ending -> Newline
  1. 安装依赖并启动 GUI:
python3 -m pip install -r requirements.txt
python3 chem_auto_desktop.py

如果当前 python3 无法启动窗口,可以直接使用本机带 Tk 的 Python:

/usr/local/bin/python3 -m pip install -r requirements.txt
/usr/local/bin/python3 chem_auto_desktop.py

2. 第一次使用:设置页

打开 GUI 后,先进入顶部标签页中的“设置”。

需要填写或确认:

串口设备:Arduino 对应串口,例如 /dev/cu.usbmodemXXXX
波特率:9600
超时秒数:0.2
启动等待:2.0
最长运行秒数:60
API Key:可留空,留空时使用代码内置值
Base URL:https://api.deepseek.com
模型:deepseek-chat

如果不知道 Arduino 串口名,可以点击“刷新”,再从串口设备下拉框选择。macOS 上通常类似:

/dev/cu.usbmodemXXXX
/dev/cu.usbserial-XXXX

Windows 上通常类似:

COM3
COM4

填写完成后,按顺序点击:

保存设置
测试合并控制器
初始化智能体

设置会保存到本机用户目录:

~/.chemauto_agent/config.json

这个文件不会提交到 GitHub。GUI 中填写的 API Key 会优先于代码内置值。

3. 配液配置页:查看稀释计算

进入“配液配置”页,可以直接查看 README 示例对应的配液方案。

默认示例:

用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸

页面会按 C1V1 = C2V2 计算:

V1 = C2 x V2 / C1 = 0.1 x 50 / 1 = 5 mL
去离子水 = 50 - 5 = 45 mL

对应泵控计划:

acid  -> 加入 5 mL 1 mol/L 盐酸母液
water -> 加入 45 mL 去离子水

如果某一泵的预计运行时间超过“最长运行秒数”,pump_liquid 会自动拆分为多段串口指令,避免单次运行被安全限制拦截。

点击“填入智能体”后,GUI 会把生成的自然语言指令填入“智能体”页。

4. 智能体页:自然语言控制实验

进入“智能体”页,在输入框中输入自然语言实验任务,然后点击“运行”。

示例:

用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸

Agent 会完成以下流程:

  1. 调用 DeepSeek 理解任务。
  2. 根据 C1V1 = C2V2 计算酸液和水的体积。
  3. 调用 pump_liquid 工具。
  4. 按当前流量标定换算泵运行时间。
  5. 通过串口向 Arduino 发送泵控指令。
  6. 更新左侧实验台状态。

智能体页也提供几个快捷按钮:

运行:执行输入框中的自然语言指令
状态:查询当前 Python 端记录的酸液、水和总液量
查询控制器:向 Arduino 发送 status
读取 pH:读取当前 pH 传感器串口输出
停止泵:发送普通停止指令

常用自然语言指令:

状态
reset
查询泵控制器状态
读取当前 pH
停止泵
让酸液泵运行 1 秒
让水泵反向运行 1 秒
用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸

5. 手动泵控页:不经过大模型直接控制

进入“手动泵控”页,可以直接调用底层泵控工具,适合排气、预灌、清洗、标定和单独测试。

按体积进液:

泵:acid 或 water
体积 mL:例如 5
点击:按体积进液

此模式会使用当前流量标定自动换算运行时间,例如酸泵 5 mL 会使用 5 mL 标定点。

按秒运行:

泵:acid 或 water
运行秒数:例如 1
方向:intake 或 reverse
速度 steps/s:默认 600
点击:按秒运行

参数含义:

acid:酸液泵
water:去离子水泵
intake:进液方向
reverse:反向运行
600:步进速度,单位 steps/s

手动泵控页不需要 DeepSeek API Key,但仍然需要串口设置正确。

6. 实时 pH 数值区

GUI 左侧会在任意页面只显示最近一次 pH 数值,并以约 0.5 秒间隔尽可能快地自动刷新。需要立即更新时,点击“立即刷新 pH”;“智能体”页中的“刷新 pH”按钮也会直接调用同一串口上的 pH 工具,不经过大模型。

正式使用 GUI 或同时使用泵控与 pH 时,必须烧录合并固件。合并固件已经内置 ph_meter_2.0 的 RawAvg 分段校准;ino/ph_meter_2.0/ph_meter_2.0.ino 仅用于单独测试 pH 计。pH 模块接在当前代码约定的引脚:

firmware = ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino
PH_SENSOR_PIN = A3
baud rate = 9600

读取步骤:

自动刷新:打开 GUI 后自动开始
手动刷新:点击左侧“立即刷新 pH”或智能体页“刷新 pH”

GUI 会解析 Arduino 报告中的 RawAvg,按 ino/ph_meter_2.0/ph_meter_2.0.ino 的三点分段参数重新计算 pH,并应用代码中的 PH_DISPLAY_OFFSET 作为最终显示修正。界面只显示最终 pH 数值,不显示稳定状态、电压或更新时间。

泵控和 pH 读取必须由同一个 Agent/GUI 进程完成。不要同时打开 Arduino IDE Serial Monitor,也不要同时启动两个 Python 控制程序,否则它们会争用同一个串口。

当前 Titration_Agent.py 仍是后续开发入口,完整自动滴定序列尚未接入 GUI。

7. 左侧实验台状态与安全按钮

GUI 左侧会持续展示:

酸液:Python 端累计加入的 acid 体积
去离子水:Python 端累计加入的 water 体积
总液量:acid + water
实时 pH:最近一次 pH 数值
最近指令:最近一次发送给 Arduino 的串口命令

安全按钮:

停止泵:发送普通停止指令 s,执行正常停止逻辑
紧急停止:立即发送 e0,不等待 Arduino 返回
查询控制器:发送 status
刷新状态:读取 Python 端实验台状态
重置记录:清零 Python 端记录,不会抽液,也不会倒液

如果泵动作异常,优先点击“紧急停止”。

8. 运行日志页

“运行日志”页会显示:

任务开始和结束时间
Python 端打印的串口通信记录
Arduino 返回内容
工具执行失败原因

如果实验没有按预期运行,优先查看这个页面。常见问题一般是串口被占用、串口名错误、Arduino 没有烧录对应程序、API Key 未填写。

9. 常见问题

GUI 启动时报 Tk 或 macOS 版本错误

通常是当前 Python 没有 Tk 支持。请直接使用本机 python.org Python:

/usr/local/bin/python3 chem_auto_desktop.py

点击运行后提示无法打开串口

检查:

Arduino 是否连接
串口名是否正确
Arduino IDE Serial Monitor 是否关闭
是否有其他程序占用串口

智能体无法启动

检查“设置”页是否填写了 API Key,或者使用环境变量:

AUTOLAB_API_KEY=你的DeepSeekKey python3 chem_auto_desktop.py

Arduino 没有返回信息

当前 Python 端不强依赖 Arduino 必须返回日志。只要串口写入成功,程序会根据运行时间等待泵动作完成。可以用“查询控制器”进一步检查 Arduino 状态。

泵控后无法读取 pH,或读取 pH 后泵不工作

确认烧录的是 AutoLab_Combined_Controller.ino,而不是独立泵控或独立 pH 测试程序。关闭 Serial Monitor 和其他串口程序后,只启动一个 Solution_Preparation_Agent.py 或 chem_auto_desktop.py 进程。

Agent 连接串口时会自动检查 status 和 phstatus。如果 Arduino 仍运行纯泵控固件, 程序会直接提示重新烧录合并固件,不再以“泵可用、pH 不可用”的半功能状态继续运行。

左侧体积记录不等于烧杯真实体积

左侧状态只是 Python 端累计记录。点击“重置记录”只会清零软件记录,不会改变真实烧杯中的液体。正式实验前请确认烧杯状态和软件状态一致。

CLI 运行方式(可选)

如果只想使用原来的命令行入口,可以按下面步骤运行。

1. 上传 Arduino 程序

将 ino/AutoLab_Combined_Controller/AutoLab_Combined_Controller.ino 上传到 Arduino,并确认 Serial Monitor 已关闭,否则 Python 可能无法打开串口。

2. 检查串口

默认串口配置在 Solution_Preparation_Agent.py 中:

SERIAL_PORT = os.getenv("AUTOLAB_SERIAL_PORT", "/dev/cu.usbmodem141011")
SERIAL_BAUD_RATE = int(os.getenv("AUTOLAB_SERIAL_BAUD_RATE", "9600"))

如果 Arduino 串口不是 /dev/cu.usbmodem141011,可以用环境变量覆盖:

AUTOLAB_SERIAL_PORT=/dev/cu.usbmodemXXXX python3 Solution_Preparation_Agent.py

3. 启动溶液配制 Agent

python3 Solution_Preparation_Agent.py

程序启动后会进入 DeepSeek 在线工具调用模式。第一次真正调用泵控工具时,Python 会打开串口并发送 Arduino 指令。

注意:当前硬件测试中,Arduino 串口可以打开并接收命令,但不一定会返回文本回显。因此 Python 端以“串口写入成功 + 等待运行时间结束”作为泵控工具完成条件,不依赖 Arduino 必须返回日志。

桌面版 Release 打包

本仓库已经加入 PyInstaller 打包脚本,可生成 GitHub Release 可用的桌面程序。

macOS DMG

在 macOS 上运行:

bash scripts/build_macos_dmg.sh

如果本机默认 python3 不是你想用于打包的版本,可以指定:

PYTHON_BIN=/usr/local/bin/python3 bash scripts/build_macos_dmg.sh

产物位置:

dist/ChemAuto-Agent-macOS.dmg

Windows EXE

在 Windows PowerShell 中运行:

.\scripts\build_windows_exe.ps1

如果需要指定 Python:

$env:PYTHON_BIN="C:\Path\To\python.exe"
.\scripts\build_windows_exe.ps1

产物位置:

dist\ChemAuto-Agent-Windows.zip

压缩包内包含 ChemAuto-Agent.exe。

GitHub 自动发布

推送形如 v0.1.0 的 tag 后,GitHub Actions 会自动构建 macOS DMG 和 Windows EXE,并发布到 GitHub Release:

git tag v0.1.0
git push origin v0.1.0

也可以在 GitHub Actions 页面手动运行 Build desktop release workflow。

示例指令

用现有的 1 mol/L 盐酸配制 50 mL 0.1 mol/L 稀盐酸
查询泵控制器状态
让酸液泵运行 1 秒
停止泵
状态
reset

流量标定

当前 Python 端采用时间控制:

运行时间 = 目标体积 / 泵流速

当前已完成 5 mL 和 10 mL 两组标定。Python 端会根据目标运输体积选择更接近的标定点:

酸泵 acid:
5 mL  -> 0.46 mL/s
10 mL -> 0.44 mL/s

水泵 water:
5 mL  -> 0.50 mL/s
10 mL -> 0.46 mL/s

例如酸泵需要运输 6 mL,由于 6 更接近 5 而不是 10,因此运行时间为:

6 / 0.46 = 13.04 s

如果目标体积刚好位于两个标定点中间,例如 7.5 mL,程序默认选择 10 mL 标定点,因为较长时间标定通常受启动斜坡影响更小。

由于 Arduino 泵控程序带有加速斜坡,过短运行时间的剂量误差会比较明显。当前 Python 端会对低于 0.8 s 的泵运行给出提示;正式实验应优先完成流量标定,并避免依赖极短时间脉冲获得高精度体积。

后续更严谨的方案是改为“步数-体积”标定,即记录每个泵的 steps_per_ml,再由 Python 直接按目标体积换算步数。

后续计划

  1. 完成酸液泵和水泵的流量标定
  2. 将溶液配制从时间控制升级为更可靠的步数-体积控制
  3. 在 Titration_Agent.py 中复用当前 pH 读取工具并实现自动采样序列
  4. 实现酸碱滴定曲线自动采集与绘图
  5. 增加实验日志保存和异常保护机制

About

上海交通大学工程学导论项目——自动溶液配制与滴定智能体

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages