用Python控制动物行为实验|pyControl

把实验写成状态机

牛津大学等团队发表于eLife的模块化开源科研仪器,用Python状态机控制鼻触、声光刺激和奖励输出。附原厂整套采购清单、11章图解、软件与硬件分项许可,以及柏林洪堡大学团队的独立实测证据。

alan000

eLife 2022

参数信息

原版行为端口
6 个

复现文档

选定套件并核对装箱

### 选定套件并核对装箱

按官方 Complete Set No 1 路线准备一套硬件。对照原厂清单逐件点收:含 pyboard 的控制板、3 个鼻触、2 个阀及管路、音频板、扬声器、12 V 3 A 电源、4 根 RJ45、USB 线,以及箱体、备用盖和装配包。将每袋紧固件拍照并记录;清单未注明的螺钉/垫片数量以实物包装和供应方确认为准。底层板级 BOM 是自制板路线,不与成品套件重复采购。完成检查:上述套件部件齐全,数量与装箱清单一致。

![pyControl官方文档图 hardware-overview.png;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/b15bf5f2fcf94032a84eca1dc0cfa9be.png)

![pyControl官方文档图 breakout-1-2-back.jpg;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/e8ec12d44dca45b7948114aa7cc85ddf.jpg)

干装箱体与控制板

### 干装箱体与控制板

先不通电,将 Breakout 板与箱体/绝缘隔柱试装,确认 USB、电源桶形插座及 RJ45 插座均能从箱体开口接入,PCB 焊点不碰金属。仅使用随箱、能与对应孔位自然对齐的螺钉;若长度或孔位不匹配、板子被压弯或焊点可能接触箱体,停止并向套件供应方确认,不强行锁紧。完成检查:板边与孔位对正、连接器可插拔、板底与金属隔离。

![pyControl官方文档图 breakout-1-2-back.jpg;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/e8ec12d44dca45b7948114aa7cc85ddf.jpg)![breakout-1-2-front.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/3ade6199e9da4107b83cbef798e38ae1.jpg)

按端口连接鼻触和音频板

### 按端口连接鼻触和音频板

以 Breakout 板丝印 PORT-1 至 PORT-6 为准,用 RJ45 线连接:左鼻触接 PORT-1,中间鼻触接 PORT-2,右鼻触接 PORT-3,Audio board 接 PORT-4;扬声器接音频板。给四根线两端贴上对应标签。RJ45 仅作设备线缆,不能接以太网交换机或 PoE。先保持阀门和水路断开。完成检查:每根线两端标签一致,端口与硬件定义对应,PORT-5/6 保持未接。

![pyControl官方文档图 breakout-1-2-back.jpg;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/e8ec12d44dca45b7948114aa7cc85ddf.jpg)![poke-front.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/aae5fc77b38a45709400ef3bf45b16b5.jpg)![poke-side.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/9c88837b44c24f62b10eca7b3021b724.jpg)

核对电源与信号电压范围

### 核对电源与信号电压范围

接入外设前核对套件 12 V 3 A 电源的输出极性与 Breakout 桶形插座标记;确认一致后再给板卡供电。USB 可能只使主控工作,不能据此判断外设已供电。按板上丝印核对信号边界:4 路 BNC 数字输出为 3.3 V;BNC-1/2 数字输入耐 5 V;DAC-1/2 不耐 5 V;模拟输入限制 0–3.3 V。POW 是低侧开关,不是电压输出;外接负载不得超过官方额定电流。发现极性不符、异常发热或气味立即断电。完成检查:供电极性已确认,外接信号电压位于对应输入范围内。

![pyControl官方文档图 breakout-1-2-front.jpg;MIT署名见正文](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/3ade6199e9da4107b83cbef798e38ae1.jpg)![driver-diagram.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/81b5b6f412fa4c6c8da6b8aa5f663692.jpg)

准备固定版本的软件环境

### 准备固定版本的软件环境

从固定代码提交 f3415197 获取 v2.1.1 软件,按官方安装说明准备 Python 3 和 numpy、pyserial、PyQt6、pyqtgraph,再启动仓库中的 `pyControl_GUI.pyw`。pyboard 使用匹配的 MicroPython 固件;只有选用新版 `UART_handler` 时,需 MicroPython ≥1.26。完成检查:GUI 可打开并显示 Run task、Experiments、Setups 页面;记录实际 Python、依赖和固件版本。

![pyControl官方文档图 run_task_tab.png;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/370c48bb114c42db894f990ec5798fec.png)

连接 pyboard 并加载框架

### 连接 pyboard 并加载框架

用 USB 数据线将 pyboard 接到电脑。在 GUI 的 Run task 页选择已识别的 Setup,点 Connect;若连接失败,核对串口选择并检查 USB 线。按官方流程在 Config 菜单加载 pyControl framework;如需禁用板载 USB 闪存模式,先确认这是该板配置的需要,再重新选择串口连接。然后在 Tasks 中选择 `example/blinker`,执行 Upload,再点 Start。完成检查:板载蓝色 LED 按任务节奏闪烁;点 Stop 后任务停止。此项只验证主控和框架。

![pyControl官方文档图 run_task_tab.png;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/370c48bb114c42db894f990ec5798fec.png)![setups_tab.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/a9f3dd287bfc4bf9b486bcdad27ced03.png)

运行三次按键状态机

### 运行三次按键状态机

在 Tasks 中加载 `example/button`。每按一次 pyboard 的 USR 按钮,事件日志应出现一次 `button_press`;累计第 3 次后进入 LED-on 状态,蓝灯亮约 1 秒,再返回 LED-off,按键计数归零。按状态图逐项对照事件、状态和灯光。完成检查:三次按键对应三条事件,第三次触发一次 LED-on,随后自动返回 LED-off。

![pyControl官方文档图 run_task_tab.png;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/370c48bb114c42db894f990ec5798fec.png)![button_task_diagram.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/d55c505d8f3f4ab7ac8d0e0678086960.png)

加载硬件定义并检查鼻触输入

### 加载硬件定义并检查鼻触输入

先按实际接线核对并加载 `example_hardware_definition`。该定义将 PORT-1/2/3 对应左/中/右鼻触;中间鼻触的 SOL 别名为 `houselight`,但套件清单不含独立室内灯,因此保持该别名端口空载。运行 `example/hardware_test`,逐一遮挡左、右鼻触光束,观察活动端口指示 LED;中间鼻触用于选择对应侧的 SOL 输出,首次检查时保持阀门断开。完成检查:左右输入能分别改变对应活动端口指示;未接独立灯或阀时不向该别名接负载;退出任务后确认输出关闭。

![pyControl官方文档图 poke-front.jpg;MIT署名见正文](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/aae5fc77b38a45709400ef3bf45b16b5.jpg)

![pyControl官方文档图 run_task_tab.png;MIT署名见正文](https://cdn.lunlunapp.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/cover/370c48bb114c42db894f990ec5798fec.png)

检查音频并保持阀门断开

### 检查音频并保持阀门断开

音频板接 PORT-4,先将板上蓝色音量旋钮调低。用官方提供、明确调用 speaker 接口的任务逐步增加音量,并确认扬声器有声且无削波;现有资料未给出该任务的文件名与音量步进值,无法确认对应代码时先停在此项,不猜测任务或参数。奖励阀和水路暂不接入:`hardware_test` 在中间光束持续遮挡时会持续驱动选定 SOL,不能用它做出液测试。后续阀测试须先有明确的脉冲时长、负载接法和台架收液方案,并逐次实测流量;测试范围限于空载及台架检查。完成检查:音频任务可控播放并能停止;阀仍断开,PCB 区域无液体。

![pyControl官方文档图 poke-side.jpg;MIT署名见正文](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/9c88837b44c24f62b10eca7b3021b724.jpg)![audio-board.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/1dfdd028fd1c44bf8fdac0b8891c4fe6.jpg)

配置实验并核对数据文件

### 配置实验并核对数据文件

在 Experiments 页选择或新建实验,指定 Task 和 Data directory;在 Subjects 表给台架测试设置 Subject ID(例如 `bench01`),并确认该行被勾选运行。保存实验配置后运行任务;Run task 页的按钮状态从 Start 变为 Record 时,确认记录已开始。停止任务后到所选目录检查生成的 TSV 事件/状态文件;如启用相应记录,再核对 NPY 数据文件。保存任务代码、硬件定义、pcx 实验配置和版本信息。完成检查:目录中出现本次测试的文件,能读出事件/状态记录,文件使用台架测试编号。

![configure_experiment_tab.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/4966e0a46f304c998f85b134c703c91a.png)![experiment_plots.png](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/c58e9a6aa6394c298f28aeaf1db9d798.png)

完成无动物台架验收

### 完成无动物台架验收

按顺序完成闪灯、三次按键、逐个鼻触和数据保存检查:每项记录预期与实际现象;任务停止后确认输出关闭,并从保存目录重新打开至少一份 TSV。若需与外部设备同步,另按官方脉冲同步说明连接并记录两侧时钟。在记录中写明使用的设备和任务版本;需要评估延迟时,另行测量并保存测试方法与原始结果。

![pyControl官方文档图 experiment_plots.png;MIT署名见正文](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/c58e9a6aa6394c298f28aeaf1db9d798.png)![sync-diagram.jpg](https://orecord-files.oss-cn-zhangjiakou.aliyuncs.com/sbp/projects/56101ade-f8d1-4bee-98a7-b67b6aa5e095/files/image/a796874af87849f79b3f76fcc91bd63f.jpg)

相关科技单元