简介openrTMS是一套面向神经科学研究与临床应用的开放式经颅磁刺激TMS软件平台采用C开发适合具备一定编程基础的研究人员、工程师及临床医生使用用于搭建刺激方案设定、参数监控与数据分析的完整工作流。资源包共57个文件约182KB以18个h头文件与15个cpp源文件为核心辅以CMake构建脚本、spin与eagle硬件设计文件、i18n国际化资源及README说明文档覆盖控制软件、固件与信号发生器等模块。该版本重点实现了对macOS的全面支持借助OpenGL与wxWidgets保证跨平台兼容性并包含刺激参数配置、数据采集与大脑激活分析等功能。目前已有153人学习下载适合希望理解TMS软硬件协同架构、参考C桌面应用工程组织方式的读者研读与二次开发。1. 开放式 rTMS 到底开放了什么从一台“黑匣子”到可改参数的刺激系统如果你在神经调控实验室待过大概率见过这样的场景一台经颅磁刺激TMS设备摆在屏蔽室里配套软件锁得死死的刺激波形、脉冲时序、线圈定位协议全是厂商预设你想改一个 inter-train interval 的毫秒值得发邮件等技术支持排期。这就是传统 rTMS 系统的现状——硬件性能不差但软件层是个黑匣子。开放式 rTMSopenrTMS要解决的核心问题就一个把刺激参数的控制权从厂商手里拿回到研究者手里让脉冲序列、触发逻辑、与 EEG/fMRI 的同步协议都变成可编程、可复现、可共享的配置而不是焊死在固件里的常量。这套思路适合两类人一类是做方案探索的神经调控研究者需要快速迭代刺激协议另一类是做脑机接口或认知实验的工程师需要把磁刺激精确嵌进多模态采集流程里。它不意味着你自己绕线圈而是说控制层开放了。2. 开放式 rTMS 的系统拆解哪些模块必须自己掌控2.1 从脉冲发生器到控制层开放边界在哪里要理解 openrTMS 能做什么先得把 rTMS 系统拆成四层。最底层是高压储能与脉冲发生电路负责在几百微秒内放出上千安培的电流往上是线圈与冷却系统决定刺激的聚焦性和耐受功率再往上是时序控制与触发层这一层管的是什么时候放、放几个、间隔多久、和外部设备怎么对齐最上面是实验控制与数据记录层负责协议编排、被试管理、日志落盘。开放式 rTMS 的“开放”主要落在第三层和第四层。第一层和第二层涉及高压安全和热管理普通实验室不会去动也没必要动。但第三层的时序控制传统设备往往只给你几个固定模式单脉冲、双脉冲、重复刺激rTMS、theta burst。你想做一个非标准模式比如把 cTBS 的 burst 间隔从 200ms 改成 150ms 再穿插一个 10ms 的双脉冲对很多设备直接不支持。openrTMS 的思路是把时序控制做成可编程的状态机用外部触发信号或软件时间轴来驱动脉冲输出。具体来说开放的控制层通常暴露三类接口外部触发输入接受来自 EEG 放大器、刺激呈现软件或 DAQ 的 TTL 信号、脉冲参数配置接口通过串口、USB 或网络协议设置强度、频率、脉冲数、状态回读接口输出实际发放的脉冲时间戳用于事后校验。这三类接口一开放你就能把 TMS 当成一个可编程的执行器而不是一个只会按预设按钮的仪器。2.2 最小可复现系统需要哪些硬件与软件件如果你要从零搭一套可复现的开放式 rTMS 控制环境不需要重新造一台刺激器但需要把控制链路理清楚。常见做法是保留一台支持外部触发的商用或自制刺激器然后在外面挂一个实时控制单元。这个控制单元可以是一块带 FPGA 的 DAQ 板也可以是一台跑实时内核的工控机甚至是一块树莓派配合高精度定时扩展板。软件侧需要三样东西一个能发 TTL 的时序引擎、一个能记录实际脉冲时间的日志模块、一个能把刺激协议描述成配置文件的格式。时序引擎的抖动直接决定实验可复现性一般要求触发抖动在微秒级至少不能超过 1ms否则和 EEG 的锁时平均就会糊掉。日志模块要记录的是刺激器实际输出的脉冲时间不是软件以为发出去的时间这两者之间可能差几十毫秒尤其是经过光耦隔离或长线缆之后。配置文件格式我一般推荐用 YAML 或 JSON把脉冲序列写成事件列表每个事件带时间戳、通道号、强度值。这样协议可以进版本控制换一台设备只要改硬件映射层协议本身不动。下面是一个最小配置示例描述一个自定义的 burst 模式# openrtms_protocol.yaml protocol_name: custom_burst_v1 description: 3 pulses at 50Hz, repeated every 200ms, 20 trains global: intensity_percent_mso: 80 # 刺激强度占最大输出百分比 pulse_width_us: 280 # 单相脉冲宽度微秒 channel: 1 # 线圈通道 sequence: train_count: 20 # 总串数 train_interval_ms: 200 # 串间隔 pulses_per_train: 3 # 每串脉冲数 inter_pulse_interval_ms: 20 # 串内脉冲间隔对应 50Hz trigger: source: external_ttl # 触发源外部 TTL 上升沿启动 edge: rising pre_trigger_offset_ms: 0 logging: output_format: csv timestamp_unit: microsecond record_actual_pulse: true # 记录实际发放时间而非计划时间这个配置里intensity_percent_mso和pulse_width_us是安全相关参数改之前必须确认线圈和刺激器的耐受范围。train_interval_ms和inter_pulse_interval_ms决定刺激模式是实验设计的核心变量。record_actual_pulse建议永远设为 true否则你拿到的日志只是“计划时间”不是“实际时间”事后对 EEG 做锁时分析时会吃大亏。2.3 把协议配置变成可执行脉冲时序引擎的四个关键参数配置文件写好了下一步是让时序引擎把它翻译成硬件能懂的触发信号。这一步的核心是一个实时循环按微秒级精度检查事件队列到点就翻转 GPIO。听起来简单但实际跑起来有四个参数必须调对。第一个是时钟源。用系统时钟还是外部晶振决定了长期漂移。如果实验持续超过几分钟系统时钟的累积误差可能到毫秒级建议用外部晶振或 GPS 驯服时钟。第二个是事件队列深度。队列太浅长协议会在中途断流队列太深内存占用上去实时性反而下降。一般 1024 到 4096 个事件够用。第三个是输出抖动补偿。GPIO 翻转本身有几十纳秒抖动但经过隔离器和线缆后可能放大到微秒级需要在固件里做固定延迟补偿。第四个是安全联锁。任何时刻如果检测到线圈温度超限、阻抗异常或外部急停信号时序引擎必须在一个脉冲周期内停止输出这个响应时间要写进规格里。下面是一个用 Python 配合实时 GPIO 库做时序引擎的骨架代码跑在带 PREEMPT_RT 补丁的 Linux 上# openrtms_timing_engine.py import time import yaml import csv from gpiozero import DigitalOutputDevice # 实际项目常用更底层的 mmap 或 pigpio class TimingEngine: def __init__(self, config_path, gpio_pin17): with open(config_path, r) as f: self.cfg yaml.safe_load(f) self.trigger_out DigitalOutputDevice(gpio_pin) self.actual_pulses [] # 记录实际发放时间戳 self._build_event_queue() def _build_event_queue(self): 把协议展开成 (绝对时间us, 动作) 的事件列表 seq self.cfg[sequence] self.events [] t 0 for train in range(seq[train_count]): for pulse in range(seq[pulses_per_train]): # 每个脉冲的上升沿时间 self.events.append((t, pulse_on)) # 脉冲宽度后拉低 self.events.append((t self.cfg[global][pulse_width_us], pulse_off)) t seq[inter_pulse_interval_ms] * 1000 # 跳到下一串减去最后一个脉冲间隔多加的时间 t (train 1) * seq[train_interval_ms] * 1000 def run(self): 实时循环按事件队列翻转 GPIO start time.perf_counter_ns() // 1000 # 微秒基准 for event_time, action in self.events: target start event_time # 忙等待到目标时间避免调度器睡眠精度不足 while (time.perf_counter_ns() // 1000) target: pass if action pulse_on: self.trigger_out.on() self.actual_pulses.append(time.perf_counter_ns() // 1000) else: self.trigger_out.off() self._save_log() def _save_log(self): with open(pulse_log.csv, w, newline) as f: writer csv.writer(f) writer.writerow([pulse_index, actual_time_us]) for i, ts in enumerate(self.actual_pulses): writer.writerow([i, ts])这段代码的关键在run方法里的忙等待。用time.sleep做微秒级定时在普通 Linux 上不可靠调度器可能让你睡过头几毫秒。忙等待虽然吃 CPU但能保证抖动在几十微秒以内。_build_event_queue里有一个容易翻车的地方串内最后一个脉冲之后到下一串开始之间的时间计算。上面用t (train 1) * train_interval_ms * 1000直接跳到下一串起点前提是train_interval_ms大于pulses_per_train * inter_pulse_interval_ms否则事件会重叠。实际用的时候要加一个校验不满足就报错退出。3. 把 openrTMS 接进多模态实验同步、触发与数据落盘3.1 和 EEG 锁时触发对齐的三种方案与误差预算rTMS 和 EEG 联合采集时最怕的是刺激伪迹和神经信号混在一起分不开。要分开前提是知道每个脉冲的精确发放时间。触发对齐有三种常见方案误差预算差别很大。第一种是刺激器直接输出 TTL 给 EEG 放大器。这是最干净的方案TTL 上升沿和脉冲发放之间的延迟由刺激器规格决定一般在几微秒到几十微秒。但前提是刺激器有同步输出口而且线缆长度要匹配否则 TTL 和实际脉冲之间会有传播延迟差。第二种是软件同时控制刺激器和 EEG 标记。时序引擎在发脉冲的同一个循环里通过另一个 GPIO 给 EEG 发标记。这种方案的问题是软件抖动会同时影响两路输出虽然相对延迟稳定但绝对时间戳可能偏。误差预算大概在几百微秒。第三种是事后对齐用刺激器的实际脉冲日志和 EEG 的连续记录做互相关。这种方案不需要硬件同步线但要求刺激器能输出实际脉冲时间戳而且 EEG 采样率要足够高否则互相关峰值定位不准。误差预算取决于采样率1kHz 采样下大概 1ms。我一般推荐第一种加第三种组合硬件 TTL 做实时标记实际脉冲日志做事后校验。这样即使 TTL 线缆出问题日志还能救回来。误差预算要写进实验方案里锁时平均的时间窗如果只有 10ms那 1ms 的误差就占了 10%不能忽略。3.2 用外部触发启动刺激序列从 TTL 输入到状态机跳转很多实验设计不是让刺激器自己按时间表跑而是等一个外部事件——比如被试看到某个视觉刺激、或者 EEG 检测到某个振荡相位——再启动刺激序列。这要求 openrTMS 的控制层能响应外部 TTL 输入并在微秒级内启动预设序列。实现上外部触发输入通常接在一个中断引脚上中断服务程序里做两件事记录触发时间戳把状态机从 idle 跳到 running。状态机跳转本身很快但序列启动的第一个脉冲可能因为刺激器充电需要几毫秒到几十毫秒的延迟。这个延迟必须提前测出来写进协议配置里否则你以为刺激发生在触发后 0ms实际是 20ms。下面是一个带外部触发等待的时序引擎片段展示状态机怎么处理# 外部触发等待与状态跳转 import RPi.GPIO as GPIO class TriggeredEngine(TimingEngine): def __init__(self, config_path, trigger_in_pin27, **kwargs): super().__init__(config_path, **kwargs) self.trigger_in_pin trigger_in_pin GPIO.setmode(GPIO.BCM) GPIO.setup(trigger_in_pin, GPIO.IN, pull_up_downGPIO.PUD_DOWN) self.trigger_timestamp None def wait_for_trigger(self, timeout_s10): 阻塞等待外部 TTL 上升沿带超时保护 start time.perf_counter() while time.perf_counter() - start timeout_s: if GPIO.input(self.trigger_in_pin) GPIO.HIGH: self.trigger_timestamp time.perf_counter_ns() // 1000 return True time.sleep(0.0001) # 100us 轮询实际项目用中断更好 return False def run_triggered(self): if not self.wait_for_trigger(): raise TimeoutError(外部触发超时序列未启动) # 补偿刺激器充电延迟 charge_delay_us self.cfg[trigger].get(pre_trigger_offset_ms, 0) * 1000 time.sleep(charge_delay_us / 1e6) self.run()这里wait_for_trigger用轮询而不是中断是为了代码简单。实际项目里 100us 轮询会引入最多 100us 的触发延迟抖动如果实验要求更高得用 GPIO 中断加时间戳捕获。pre_trigger_offset_ms这个参数就是用来补偿刺激器充电延迟的设成负值没意义设成正值会让序列延后启动。调这个参数的方法是用示波器同时看触发输入和刺激器输出量出实际延迟填进去。3.3 刺激日志与实验元数据事后复现需要的字段清单实验做完数据能不能复现取决于日志里记了多少东西。我见过太多案例刺激参数记了但线圈位置没记或者记了位置但没记坐标系换个人就复现不了。开放式 rTMS 的一个优势是你可以自定义日志格式把该记的都记上。下面这张表是我一般会落盘的字段清单分三类刺激参数、硬件状态、实验上下文。字段名类型说明是否必填protocol_namestring协议配置文件名是intensity_percent_msofloat刺激强度占最大输出百分比是pulse_width_usint脉冲宽度是train_countint总串数是train_interval_msfloat串间隔是actual_pulse_timeslist[int]实际脉冲时间戳微秒是coil_temperature_startfloat实验开始线圈温度建议coil_temperature_endfloat实验结束线圈温度建议coil_positiondict线圈位置与朝向带坐标系说明是subject_idstring被试编号去标识化是session_datestring实验日期是operatorstring操作者代号建议eeg_sync_channelstringEEG 同步通道名是trigger_delay_measured_usint实测触发到脉冲延迟是coil_position这个字段最容易偷懒。只记“左侧 M1”不够要记坐标系和定位方法。用神经导航的记导航坐标系下的矩阵用定位帽的记帽上刻度用徒手的至少记头皮标记点。没有这个跨天复现基本靠玄学。4. 避坑与排查开放式 rTMS 落地时最容易翻车的五个地方4.1 触发抖动超标从 50us 变成 5ms 的排查路径现象实验跑起来EEG 锁时平均的波形糊成一团检查日志发现实际脉冲间隔和计划值偏差很大抖动从预期的几十微秒变成几毫秒。原因最常见的是实时性没配好。普通 Linux 内核的调度器会把你的忙等待循环抢走 CPU尤其是在有网络中断或磁盘 IO 的时候。另一个原因是 GPIO 库本身的开销有些高层库每次翻转要经过多层抽象耗时不稳定。解决先确认内核是不是 PREEMPT_RT 或至少是低延迟内核。然后用cyclictest测一下系统的最坏调度延迟如果超过 100us说明系统本身不适合做微秒级定时。GPIO 操作尽量用 mmap 直接写寄存器别用高层库。如果还不行把时序引擎挪到独立的微控制器上比如一块跑裸机程序的 STM32通过串口接收事件队列微控制器负责精确翻转 GPIO。这样抖动可以压到几微秒以内。4.2 刺激器不响应外部触发电平、极性和隔离的三个坑现象时序引擎明明发了 TTL刺激器就是不放电或者偶尔放一次。原因三个地方容易出问题。一是电平不匹配时序引擎输出 3.3V TTL刺激器要求 5V 或 12V看起来接了但识别不到。二是极性反了刺激器要上升沿触发你给了下降沿。三是光耦隔离的方向搞反了或者隔离器的响应速度不够窄脉冲被吃掉。解决先用示波器直接量刺激器触发输入端的波形确认幅度、极性、宽度都符合规格。如果幅度不够加一级电平转换或驱动芯片。极性反了就在配置里改edge参数或者硬件上反相。隔离器要选高速型上升时间小于 100ns 的普通光耦可能跟不上微秒级脉冲。另外注意线缆长度长线缆会引入振铃必要时加终端电阻。4.3 线圈温度漂移导致强度不准一个被忽视的慢变量现象实验前半段和后半段同样的刺激强度设置被试的感知阈值变了或者运动诱发电位MEP幅度漂移。原因线圈温度升高后铜线电阻增加同样的电压下电流下降实际刺激强度就弱了。很多刺激器不补偿这个或者补偿算法不对外公开。开放式系统里如果你只控制电压或百分比不监控温度这个漂移就会混进实验效应里。解决在日志里记录实验前后的线圈温度如果温差超过 5 摄氏度中间也要记。有条件的话每跑完一串就读一次温度画温度-时间曲线。如果漂移明显要么降低刺激频率让线圈有时间冷却要么在协议里做强度补偿根据温度查表调整百分比。这个表需要自己测用场强计或 MEP 阈值做标定。4.4 配置文件版本混乱协议改了但日志没跟上现象过了三个月回头分析数据发现日志里的protocol_name对应的配置文件已经改了不知道当时用的到底是哪个版本。原因配置文件没有进版本控制或者进了但日志里只记了文件名没记哈希。实验中途改参数也没在日志里留痕。解决配置文件必须进 Git每次实验的日志里记录配置文件的 commit hash 和文件内容的 SHA256。实验中途如果改了参数在日志里追加一条变更记录带时间戳和变更原因。这个习惯看起来麻烦但当你需要复现半年前的一个效应时能省掉大量猜测。我一般会在时序引擎启动时自动算配置文件的哈希写进日志第一行。4.5 安全联锁失效急停按钮按了但序列还在跑现象测试急停功能时按下按钮后刺激器还在输出剩余脉冲没有立即停止。原因急停信号只接到了刺激器的硬件使能端但时序引擎不知道还在继续发触发。或者联锁逻辑写在了软件层但软件循环卡在忙等待里没及时检查急停状态。解决急停必须同时切断两路一路直接硬件切断刺激器使能另一路给时序引擎一个高优先级中断让状态机立刻跳到 stopped 并清空事件队列。软件层检查急停的频率要高于脉冲发放频率最好每个事件之前都查一次。测试的时候要模拟最坏情况在串刺激中间按急停确认剩余脉冲不超过一个。这个测试每次实验前都要做不能省。5. 进阶技巧用配置哈希和回放日志做跨设备复现开放式 rTMS 最大的价值不是让你多改几个参数而是让刺激协议变成可版本化、可回放、可跨设备迁移的工程对象。我现在的习惯是任何一次实验的刺激部分最终都落成两个文件一个协议配置的哈希一个实际脉冲的回放日志。哈希保证协议内容可追溯回放日志保证时间轴可重建。具体做法是在时序引擎启动时除了加载配置还算一个规范化哈希。规范化的意思是把配置里的注释、空行、键顺序都去掉只留语义内容然后算 SHA256。这样两个人写的配置只要语义一样哈希就一样。日志里记这个哈希而不是文件名。文件名会改哈希不会。回放日志的格式我一般用二进制每个脉冲记 8 字节时间戳加 2 字节通道号比 CSV 紧凑长时间实验也不会太大。回放的时候写一个独立的回放脚本读日志文件按记录的时间戳重新发 TTL但不接刺激器只接示波器或 EEG 标记通道。这样可以验证另一台设备的时序引擎能不能复现同样的时间轴。如果回放出来的脉冲间隔和原始日志的偏差在允许范围内说明跨设备迁移成功。下面是一个算规范化哈希和回放日志的代码片段# protocol_hash_and_replay.py import hashlib import json import struct import yaml def canonical_hash(config_path): 算配置文件的语义哈希忽略注释和键顺序 with open(config_path, r) as f: cfg yaml.safe_load(f) # 递归排序键保证语义相同则哈希相同 canonical json.dumps(cfg, sort_keysTrue, separators(,, :)) return hashlib.sha256(canonical.encode(utf-8)).hexdigest() def write_binary_log(pulse_times_us, channels, path): 写二进制回放日志每个脉冲 8 字节时间 2 字节通道 with open(path, wb) as f: for ts, ch in zip(pulse_times_us, channels): f.write(struct.pack(QH, ts, ch)) def read_binary_log(path): 读回放日志返回 (时间戳列表, 通道列表) times, channels [], [] with open(path, rb) as f: while True: data f.read(10) # 8 2 if not data: break ts, ch struct.unpack(QH, data) times.append(ts) channels.append(ch) return times, channels def replay(times, channels, gpio_map, speed1.0): 按日志回放speed1 放慢speed1 加快 import time if not times: return t0 times[0] start time.perf_counter_ns() // 1000 for ts, ch in zip(times, channels): target start (ts - t0) / speed while (time.perf_counter_ns() // 1000) target: pass gpio_map[ch].on() # 假设脉冲宽度 280us实际从配置读 pulse_end target 280 while (time.perf_counter_ns() // 1000) pulse_end: pass gpio_map[ch].off()canonical_hash里用json.dumps加sort_keysTrue是关键YAML 加载后是字典字典键顺序在 Python 3.7 是插入序不同人写的配置键顺序可能不同排序后就能保证语义相同的配置哈希一致。write_binary_log用QH格式小端 8 字节无符号整数加 2 字节无符号短整数一个脉冲 10 字节一小时连续刺激按 10Hz 算也就 360KB完全可接受。replay里的speed参数用来做时间缩放测试比如用 0.5 倍速回放看慢速下时序引擎的抖动特性有没有变化。跨设备复现的验证标准我一般定两条回放日志和原始日志的脉冲间隔偏差在 ±50us 以内总时长偏差在 0.01% 以内。达不到就说明目标设备的时序引擎有问题需要调实时参数或换硬件。这个验证做完你才敢说这套协议在另一台设备上也能跑出同样的刺激模式。最后说一个我踩过的坑有一次换了一台新工控机所有配置和日志都迁移过去了回放验证也过了但实际实验时被试的 MEP 幅度就是和旧机器不一样。查了两天才发现新机器的 GPIO 驱动默认输出 3.3V旧机器是 5V刺激器虽然都能触发但内部充电电路的响应时间差了 1ms 左右导致实际脉冲强度有细微差异。从那以后我在回放验证里加了一条不光比时间戳还要用示波器量刺激器输出端的实际波形确认幅度和上升时间一致。硬件层的差异软件日志是看不出来的。希望帮到你。本文还有配套的精品资源点击获取