简介这份徕卡TS30、TS50系列测量机器人Geocom中文说明书面向从事徕卡测量机器人二次开发的工程师以及具备一定编程基础的学习者重点解决GEOCOM接口理解、通信协议掌握和应用程序搭建问题。压缩包仅含1个docx文件大小约1.49MB内容围绕GEOCOM使用背景、TPS1200系统软件、ASCII协议语法、C/C与VBA函数调用协议、数据类型定义及程序示例展开并涉及基本应用框架、仪器操作方式和常见通信错误。已有2426人学习说明其在测量机器人开发资料中具有一定参考价值。读者可据此梳理GEOCOM编程基础理解ASCII通信的数据格式与调用规则并结合C/C或VBA示例搭建二次开发框架为自动化数据采集、传输与后端处理等场景提供查证依据。1. 工地半夜那台自己会转的仪器靠的是什么凌晨两点桥面监测点位上没人一台测量机器人自己松开水平制动、转过一个角度、停住、微调、锁定棱镜、测距、把结果写进后台数据库——这套动作重复了几十次。很多第一次见的人会以为这是厂商自带的固定程序其实多数现场跑的是开发者自己写的上位机软件中间隔着一层叫 GEOCOM 的接口。这份《TS30、TS50 系列测量机器人 GEOCOM 中文说明书》讲的就是这层接口怎么用从 COM 端口握手、ASCII 报文拼装到 AUT 自动照准、BAP 测距测角、FTR 文件传输、IMG 图像抓取一整套函数族。测量机器人二次开发里最费时间的从来不是业务逻辑而是把这些 RPC 调用摸清楚、把返回码读懂、把现场偶发的超时和不锁定排掉。这份文档适合两类人手上已经有 TS30、TS50、TS60 或 TM30 这类仪器想用 C/C、VBA 或 Python 把它接进自己系统的开发者以及正在做自动化监测方案、需要判断这台设备到底能不能被外部程序控制的技术负责人。下面按我拆这类接口文档的习惯把结构、通信链路、核心模块和现场踩过的坑一层层铺开。2. 协议与子系统GEOCOM 到底暴露了哪些能力拿到一份接口文档第一件事不是翻函数列表而是先搞清它的分层。GEOCOM 的结构很清晰底下是 RPC远程过程调用模型中间是若干按业务划分的子系统上面才是你实际调用的函数。子系统的划分方式基本就等于仪器的功能模块划分看懂这张表后面翻到任何一章都不会迷路。2.1 九个子系统的职责边界按文档目录列出来的部分能整理出这样一张对照表。我在实际项目里通常会把这张表直接抄进自己的接口封装文档首页团队里谁要加功能先看该落在哪个子系统。子系统代号中文名负责的事情常用函数前缀COM通信服务端口开关、超时、双精度设置、错误文本COM_AUT自动化望远镜转向、搜索、锁定、微调、跟踪AUT_AUS用户/ATR 状态ATR 模式、锁定模式开关AUS_BAP基本应用EDM 类型、棱镜定义、测距测角BAP_BMM基本人机界面蜂鸣提示、报警音BMM_ / IOS_CSV中央服务仪器型号、序列号、时间、温度、电源CSV_EDM电子测距激光指示、发光强度EDM_FTR文件传输列表、下载、删除仪器内文件FTR_IMG图像处理望远镜相机配置、抓图IMG_COM 是最底层任何一条指令发出去之前端口必须由它打开CSV 是信息查询层我一般用它做设备自检——程序启动时先读一遍仪器型号、软件版本、当前电量和内部温度写进日志出问题时这份日志比什么都值钱AUT 和 BAP 是干活的主力一个负责看哪儿一个负责测什么FTR 和 IMG 属于锦上添花做巡检报告和远程可视化的时候才用得上。有一点容易忽略AUS 和 AUT 是两个不同的子系统前者管状态开关后者管动作执行。很多人写代码时把AUS_SetUserLockState和AUT_LockOnTarget混着用结果出现锁定了但状态还是关的这种诡异现象后面避坑那章会展开说。2.2 请求-应答模型事务号和返回码GEOCOM 不管底层走串口还是走网络上层都是严格的请求-应答一问一答没有推送。客户端发一条报文仪器回一条中间不允许插队。所以报文里必须有一个事务号Transaction ID让仪器的应答能和你的请求配对。ASCII 协议的报文形态大致是这样请求%R1P,0,0:rcsid[,param1,param2,...]\r\n应答%R1P,0,0:rcsid,RC[,ret1,ret2,...]\r\n逐段解释一下。%R是报文起始标记表示这是一个请求紧跟的数字1是事务号范围一般 1 到 255用完回绕P,0,0这三段是协议头和请求类型标识按说明书 2.3 节的 ASCII 协议语法固定填冒号后面第一个字段是rcsid也就是远程调用的函数编号这个编号必须去文档第 4 章 RPC 描述的结构 里查表不能猜再往后是入参用逗号分隔没有参数就不写。应答里的RC是返回码这是整个开发过程中你要盯得最紧的东西。RC 0表示成功非 0 就是各种错误——参数越界、设备忙、目标丢失、通信超时各有各的编号。文档 5.4.12 提供了COM_GetErrorText把返回码翻译成可读文本我在所有项目的日志函数里都强制调它一次宁可多一次往返也不要日志里出现一堆裸数字。提示事务号不是必须从 1 开始但一定要保证同一时刻未应答的报文事务号唯一。单线程同步收发的场景下简单的自增回绕就够用。2.3 ASCII、C/C 与 VBA三条调用路径怎么选文档第 2 章把函数调用协议拆成了三种形式纯 ASCII 字符串、C/C 调用、VBA 调用。这三者不是三套不同的接口而是同一套 RPC 函数的不同包装层次。纯 ASCII 是最原始的一层你自己拼字符串、自己解析返回。优点是跨语言、跨平台Python、C#、LabVIEW、甚至一个串口助手都能跑缺点是没有类型检查一个逗号写错仪器直接给你一个参数错误码排查全靠对照文档。C/C 那一层文档 3.3 节给了基本应用框架和数据类型说明。它本质上是厂商提供的一套头文件和库把 ASCII 拼装和解析封装成函数调用你写COM_Init()而不是拼%R1P,0,0:...。这套方式适合做长期维护的上位机编译期能拦住一部分错误。VBA 那一层主要面向 Excel 或仪器自带软件里的宏文档 3.4 节讲了 VBA 的数据类型派生规则和框架。实际项目里我很少用但如果甲方要求测量数据直接进 Excel 表格并现场出图VBA 反而是阻力最小的路径。我的选择习惯是原型验证和跨平台集成走 ASCII稳定交付的桌面端走 C/C办公场景走 VBA。三条路径共用一套rcsid表所以文档里那张函数编号表是核心资产值得单独抄出来做成一张配置表用代码生成常量定义别手打。2.4 类型系统双精度、角度制和字符串文档 5.3 节专门讲了COM_SetDoublePrecision和获取双精度设置。这个函数看着不起眼但它决定了浮点数在报文里保留几位小数直接影响测角测距的精度表现。默认精度下角度可能只保留到小数点后 4 位做精密监测时不够用需要在初始化阶段显式设置。角度单位是另一个高频翻车点。GEOCOM 内部的角度值通常以弧度或百分度gon表示具体取决于仪器配置而现场工程师脑子里想的是度分秒。我在封装层里固定做一次转换绝不让原始值直接流到业务代码里否则半年后接手的人一定会算错。字符串参数按 ASCII 传中文路径和中文文件名不要指望能透传FTR 下载文件时用纯英文文件名这是我吃过亏之后定下的规矩。3. 通信链路从打开端口到第一次握手协议看懂了接下来是让程序真的和仪器说上话。这一段看着简单实际上是新人卡住最多的地方——不是代码写错而是时序和参数没对上。3.1 端口参数与连接方式TS30、TS50 这类仪器对外一般提供几种物理通道串口RS232、USB、以及部分型号支持的 TCP。串口参数常见配置是 8 数据位、无校验、1 停止位波特率可配出厂常见 115200 或 9600。TCP 方式下仪器相当于一个服务端你连它的 IP 和端口报文内容完全一致只是传输层换了。初始化顺序是有讲究的不能乱1. COM_Init 初始化 GEOCOM 环境客户端侧 2. COM_OpenConnection 打开物理端口指定端口号和波特率 3. COM_SetTimeout 设置应答超时 4. COM_SetDoublePrecision 设置浮点精度 5. ...业务函数... 6. COM_CloseConnection 关闭端口 7. COM_End 释放 GEOCOM 环境COM_OpenConnection的参数里端口号在串口模式下是 COM1、COM2 这种逻辑编号波特率必须和仪器端设置完全一致。我遇到过现场仪器被上一家单位改成 19200而程序里写死 115200表现就是发什么都没反应用串口助手一看全是乱码改了波特率立刻正常。COM_SetTimeout设的是等待应答的毫秒数。默认值偏短做自动搜索这种耗时操作时容易提前超时我一般设到 5000 到 10000 毫秒具体看动作类型搜索类给足状态查询类可以短一些。3.2 一个能跑起来的最小客户端下面这段 Python 是我验证链路时常用的骨架用 pyserial 发 ASCII 帧。它不是生产代码但把报文拼装、发送、接收、返回码检查这条链路完整走了一遍改成 C 或 C# 只是换 API。import serial import time class GeoComClient: def __init__(self, port, baud115200, timeout_ms5000): # 串口八参数端口、波特率、字节位、校验、停止位、超时 self.ser serial.Serial( portport, baudratebaud, bytesizeserial.EIGHTBITS, parityserial.PARITY_NONE, stopbitsserial.STOPBITS_ONE, timeouttimeout_ms / 1000.0 ) self.trans_id 0 def _next_trans(self): # 事务号 1..255 回绕用来把应答和请求对上 self.trans_id self.trans_id % 255 1 return self.trans_id def call(self, rcsid, *params): tid self._next_trans() body ,.join(str(p) for p in params) # 协议头 %RtidP,0,0: 固定rcsid 后的逗号只在有参数时出现 frame f%R{tid}P,0,0:{rcsid} if body: frame , body frame \r\n self.ser.reset_input_buffer() # 丢掉上一次残留避免错位 self.ser.write(frame.encode(ascii)) # 应答以 \r\n 结尾读到超时或读到完整帧为止 raw self.ser.readline().decode(ascii, errorsignore).strip() if not raw: raise TimeoutError(fno reply for rcsid{rcsid}) # 形如 %R1P,0,0:rcsid,RC,ret1,ret2 payload raw.split(:, 1)[1] fields payload.split(,) rc int(fields[1]) return rc, fields[2:]核心逻辑就三段。第一段拼帧前缀固定事务号自增rcsid从文档第 4 章的 RPC 表里查参数按文档标注的顺序追加。第二段发送前先reset_input_buffer()这一步看着多余实际很关键仪器有时候会多吐一个换行或者残留上一帧的后半截不清缓冲就会解析错位。第三段解析按冒号切成两半取后半段按逗号切第二个字段固定是返回码。rcsid我特意没有写死数字。文档第 4 章给了完整的 RPC 结构描述但不同固件版本会有微小差异正确做法是照着你自己那台仪器的软件版本对应的表来填然后把它做成常量字典# 键名按子系统归类值从说明书第 4 章 RPC 描述表查得 RCSID { COM_NullProc: None, # 通信自检无参数 COM_GetSWVersion: None, # 查固件版本 CSV_GetInstrumentName: None, # 查仪器型号 AUT_LockOnTarget: None, # 锁定目标 BAP_MeasDistanceAngle: None, # 测距测角 }3.3 握手成功后先做四件事链路刚打通的时候别急着调业务函数先做一轮自检把设备状态摸清楚。我固定会跑这四个调用CSV_GetInstrumentName确认连的是不是预期那台仪器。现场多台设备同时在线接错串口的低级错误真实发生过。CSV_GetSWVersion记录固件版本。这份说明书是 2019 年前后的版本如果你的仪器固件比它新或者比它老个别函数的参数个数和行为可能有出入出问题时第一个要怀疑的就是版本不匹配。CSV_CheckPower查电源状态。自动监测点位往往没人值守电池耗尽导致程序假死的案例不少我一般把它做成定时轮询低于阈值就告警。COM_NullProc做通信自检。这个函数不带任何业务含义只验证一问一答的通路是否通畅用来区分通信断了和通信正常但业务函数报错这两种完全不同的故障。3.4 双精度设置和错误文本COM_SetDoublePrecision的入参是一个布尔或枚举控制浮点数的输出格式。做精密监测时我一般开高精度代价是报文变长、解析时要按完整长度取字段不能随便截断。反过来如果只是做目标搜索这类粗定位默认精度足够报文短了往返也快。COM_GetErrorText是把返回码翻译成文本的函数参数就是你要翻译的那个 RC 值。所有非 0 返回我都建议走一次这个调用然后把函数名 入参 RC 文本一起写进日志。现场排障的时候一句 目标未找到 比 error 1023 能省掉半小时。4. 核心模块拆解从搜索到测距这一条链路自动监测这类应用90% 的业务都落在同一条链路上望远镜转过去、找到棱镜、锁定、测距测角、把数据取回来。这条链路横跨 AUT、AUS、BAP 三个子系统下面按执行顺序拆。4.1 AUT定位公差、超时与转向AUT 子系统是自动化能力的核心。文档 7.4 节列了十几个函数真正高频用的就那么几个其余都是参数微调。动手之前先读两个设置AUT_ReadTol读当前的定位公差AUT_ReadTimeout读当前的定位超时。公差决定望远镜认为到位了的角度阈值超时决定它转多久还没到位就认输。这两个值出厂有默认但不同应用差别很大——近距固定点位可以放宽公差、缩短超时快速出结果远距或震动环境必须收紧公差、拉长超时否则会出现转到位了但其实偏了 20 角秒的隐性误差。设完参数就调AUT_LockOnTarget把望远镜转到指定的水平角Hz和垂直角V并尝试锁定。入参是目标角度返回码告诉你锁没锁上。这个函数内部其实包含粗转 精调两个阶段文档 7.4.7 的自动微调和 7.4.6 的自动转换面是它的可拆分版本需要更细粒度控制的时候用。锁定之后能不能搜到目标取决于搜索窗口。AUT_PS_SetRange设置 PowerSearch 的范围AUT_PS_SearchNext搜下一个目标。范围设太小目标稍微偏一点就搜不到设太大附近有别的棱镜容易被抓错。工地附近有反射面的时候这两行参数调起来是真的烦。4.2 BAPEDM 类型、棱镜常数与单次测量BAP 负责测什么、怎么测、按什么标准算。这里有几个参数如果不对测出来的数会系统性偏移而且偏移量看起来特别正常最难发现。BAP_GetTargetType和对应的设置函数管 EDM 测量类型——是无棱镜、是圆棱镜、还是反射片测距方式完全不同。BAP_GetPrismType2和设置函数管棱镜常数的取值来源可以取默认棱镜类型也可以取用户自定义的棱镜定义BAP_GetUserPrismDefinition/BAP_SetUserPrismDefinition。棱镜常数填错测距结果会整体差一个固定值三十米和三百米都一样差很容易被当成仪器故障其实是配置问题。BAP_MeasDistanceAngle是最常用的测量函数一次调用返回水平角、垂直角和距离。文档 8.3.12 标注了它的三个返回值顺序不能记错。4.3 一条完整的搜索-锁定-测量-取数流程把上面的函数按顺序串起来就是实际项目里最常写的那段def measure_once(client, hz, v): # 1) 设置定位公差与超时单位按说明书 7.4 节角度为弧度制 client.call(RCSID[AUT_SetTol], 0.0003, 0.0003, 0.0003) client.call(RCSID[AUT_SetTimeout], 20000, 20000) # 2) 望远镜转向目标角度并锁定 rc, _ client.call(RCSID[AUT_LockOnTarget], hz, v) if rc ! 0: # 锁定失败常见原因是遮挡或目标偏离搜索窗口 raise RuntimeError(flock failed: {rc}) # 3) 开一次精调把残余角度偏差压到公差内 rc, _ client.call(RCSID[AUT_FineAdjust], 1) if rc ! 0: raise RuntimeError(ffine adjust failed: {rc}) # 4) 单次测距测角返回 Hz、V、斜距 rc, ret client.call(RCSID[BAP_MeasDistanceAngle], 1) if rc ! 0: raise RuntimeError(fmeasure failed: {rc}) hz_out, v_out, dist float(ret[0]), float(ret[1]), float(ret[2]) return hz_out, v_out, dist逐段看。第一步设公差和超时三个公差参数分别对应水平、垂直和距离方向的收敛阈值单位是弧度或米具体看文档 7.4.1 的说明超时用毫秒。第二步AUT_LockOnTarget是动作主体失败就直接抛不要硬着头皮往下走——锁不上还去测距测出来的多半是天空或者挡板。第三步AUT_FineAdjust的入参通常是 1 表示单次精调0 表示连续连续模式会一直微调直到超时做动态跟踪时用得上静点测量用单次就够了。第四步BAP_MeasDistanceAngle的入参控制测量模式1 一般表示单次标准测量。整个流程里最关键的不是代码结构而是失败时不要吞掉返回码。我见过有人为了让程序跑得稳把返回值全用_接掉结果是程序确实不崩了但数据里混进了一堆上一次的残留值等发现的时候已经出了几十期报告。4.4 角度单位与状态一致性再强调一次单位。GEOCOM 的角度参数多数以弧度表示AUT_SetTol的公差也是弧度而国内工程习惯用度分秒或百分度。封装层里我固定提供两个函数dms_to_rad和rad_to_dms所有外部接口只接受度分秒内部转换一次杜绝混用。状态一致性是另一个隐蔽点。AUS_GetUserLockState读的是锁定模式的状态AUS_SetUserLockState设置它这是开关层面的东西AUT_LockOnTarget是动作层面的东西。逻辑上应该是先开锁定模式再执行锁定动作否则可能出现动作成功但模式未开后续跟踪直接失效的现象。我在项目里把这两步包成一个原子操作谁也别想跳过。5. 避坑与排查现场最容易翻车的五个地方下面这五条都是我在实际点位上撞过的按现象、原因、解决排列不是理论问题。5.1 发送命令没反应串口助手也看不到应答现象程序发指令出去等满超时时间返回空换串口助手手动发也是一样。原因波特率或数据位不匹配或者 RS232 的收发线接反。仪器被上一套软件改过通信参数是最常见的尤其是二手机或者接手别人项目的时候。解决先用串口助手以出厂参数逐个波特率试探能收到回显的那个就是对的确认参数后在程序启动时固定执行一次COM_OpenConnection并立刻用COM_NullProc验证验证不过就报错退出别让程序带着错误的链路继续跑。5.2 搜索总是超时但人工看望远镜确实对准了现象AUT_LockOnTarget返回非 0现场肉眼判断望远镜指向没问题。原因定位公差设得太紧加上现场有风或仪器底座轻微震动望远镜在阈值附近反复摆动永远收敛不了最后撞超时。解决先用AUT_ReadTol读出出厂值作为基准按距离和稳定性分档设置——近距离固定墩可以收紧到角秒级长距离或震动环境放宽。同时把AUT_SetTimeout拉长到 20 秒以上给收敛留时间。另外检查棱镜是否被雨雾遮挡PowerSearch 在低能见度下确实会失灵这时切到 ATR 小窗口模式效果更好。5.3 测距数据整体偏移一个固定值现象换了新程序之后所有测点的距离比历史数据系统性多出几厘米方向一致角度正常。原因棱镜常数配置错了。用了自定义棱镜定义却沿用了默认的常数或者代码里读取的是BAP_GetPrismType2的默认分支而现场实际架的不是那种棱镜。解决上点之前先做一次已知基线检核拿两个已知坐标点反算距离和观测值比对。确认偏移量后用BAP_SetUserPrismDefinition写入正确的棱镜常数并把配置项外置成参数文件不同工区不同棱镜各配一套别写死在代码里。5.4 程序跑几个小时后假死重启就好现象长时间运行后不再响应串口还能打开但所有业务函数超时重启程序恢复。原因串口缓冲区堆积。仪器在某些异常状态下会多发报文而程序只按需读取越积越多最后解析全乱。另一个可能是事务号用尽后没有正确回绕导致应答错配。解决每次发送前清输入缓冲前面代码里那句reset_input_buffer事务号严格做 255 取模回绕再加一个定时心跳每分钟调一次COM_NullProc连续三次失败就自动重连端口并且把这一分钟内的数据标记为不可信。这套机制上线之后类似故障从每天一次降到一个月都不一定有一次。5.5 文件名带中文文件下载失败现象FTR_Download一直返回参数错误换成英文文件名就正常。原因GEOCOM 的 ASCII 报文对非 ASCII 字符没有做扩展编码约定中文文件名在传输层就损坏了。解决仪器内部的存储文件名统一用英文加日期编号下载回本地之后再映射成中文名。这个约定写进项目规范而不是靠每个人自觉。6. 二次开发改造思路把说明书变成自己的 SDK文档看到最后真正的产出不是一个能跑通的 demo而是一层稳定的封装。我现在的习惯是拿到任何一套类似 GEOCOM 的仪器接口都先搭三层结构再写业务。6.1 三层封装传输、协议、业务最底下是传输层只管字节进出负责串口/TCP 的打开关闭、超时、重连对外提供send(frame)和recv()。这一层不应该出现任何rcsid。中间是协议层把每个 GEOCOM 函数包成一个带类型签名的方法入参做单位转换返回值统一解析成(rc, ret_list)非 0 时自动调COM_GetErrorText补上可读文本。这层的每个方法对应文档里的一个函数一一映射不做额外逻辑将来固件升级要改也只改这里。最上面是业务层比如measure_point(point_id)、do_scan(area)、check_device()。业务层只调用协议层方法不碰任何字符串拼接。这么分的好处是测试可控。传输层可以用模拟器替代协议层可以做报文快照测试业务层才需要真机。6.2 验证方法三档回归改完之后怎么确认没改坏我固定跑三档。第一档是报文快照把协议层每个方法生成的帧字符串 dump 出来和基线逐字节比对。这一档不需要仪器跑得飞快任何拼帧逻辑的回归当场暴露。第二档是设备自检连真机跑一遍CSV_GetInstrumentName、CSV_GetSWVersion、COM_NullProc、CSV_CheckPower确认链路和状态。这一档每次上点位之前必跑两分钟的事。第三档是几何检核在已知基线上测三个点反算距离和角度和标准值比对误差在允许范围内才算通过。这一档能抓出棱镜常数、角度单位、双精度设置这三类程序没报错但数不对的问题。配套的配置项建议外置成一张表改参数不用重新编译配置项典型值说明portCOM3串口编号或 IP:端口baud115200必须与仪器端一致timeout_ms8000搜索类动作要拉长tol_hz / tol_v0.0003 rad按距离和稳定性分档prism_const依棱镜型上点前必须检核double_precision高精度精密监测场景开启6.3 一个具体技巧用心跳加状态机兜住长时运行长期无人值守的项目最怕的不是单次测量失败而是失败之后状态错乱——上一轮的望远镜还停在半路下一轮指令已经发出去两条动作叠在一起结果谁也说不清。我的做法是给设备加一个显式状态机状态只有四个IDLE、MOVING、LOCKED、MEASURING每次动作前后校验状态非法跃迁直接拒绝执行并触发复位。复位流程不是重启程序而是走一遍软恢复AUT_LockOnTarget用当前读数原地锁定一次AUS_SetUserLockState重置锁定模式再打一个COM_NullProc心跳确认链路还在。这套走完八成以上的卡死状态能自己恢复不用人跑现场。我从那以后每次接新的测量机器人项目都会在业务代码之前先把心跳和状态机写完宁可多花半天也不要半夜被一个程序还在跑但数据停了三天的电话叫起来。这套封装思路和上面那三档验证是我拆完这份中文说明书之后真正沉淀下来的东西希望帮到你。本文还有配套的精品资源点击获取
简介这份徕卡TS30、TS50系列测量机器人Geocom中文说明书面向从事徕卡测量机器人二次开发的工程师以及具备一定编程基础的学习者重点解决GEOCOM接口理解、通信协议掌握和应用程序搭建问题。压缩包仅含1个docx文件大小约1.49MB内容围绕GEOCOM使用背景、TPS1200系统软件、ASCII协议语法、C/C与VBA函数调用协议、数据类型定义及程序示例展开并涉及基本应用框架、仪器操作方式和常见通信错误。已有2426人学习说明其在测量机器人开发资料中具有一定参考价值。读者可据此梳理GEOCOM编程基础理解ASCII通信的数据格式与调用规则并结合C/C或VBA示例搭建二次开发框架为自动化数据采集、传输与后端处理等场景提供查证依据。1. 工地半夜那台自己会转的仪器靠的是什么凌晨两点桥面监测点位上没人一台测量机器人自己松开水平制动、转过一个角度、停住、微调、锁定棱镜、测距、把结果写进后台数据库——这套动作重复了几十次。很多第一次见的人会以为这是厂商自带的固定程序其实多数现场跑的是开发者自己写的上位机软件中间隔着一层叫 GEOCOM 的接口。这份《TS30、TS50 系列测量机器人 GEOCOM 中文说明书》讲的就是这层接口怎么用从 COM 端口握手、ASCII 报文拼装到 AUT 自动照准、BAP 测距测角、FTR 文件传输、IMG 图像抓取一整套函数族。测量机器人二次开发里最费时间的从来不是业务逻辑而是把这些 RPC 调用摸清楚、把返回码读懂、把现场偶发的超时和不锁定排掉。这份文档适合两类人手上已经有 TS30、TS50、TS60 或 TM30 这类仪器想用 C/C、VBA 或 Python 把它接进自己系统的开发者以及正在做自动化监测方案、需要判断这台设备到底能不能被外部程序控制的技术负责人。下面按我拆这类接口文档的习惯把结构、通信链路、核心模块和现场踩过的坑一层层铺开。2. 协议与子系统GEOCOM 到底暴露了哪些能力拿到一份接口文档第一件事不是翻函数列表而是先搞清它的分层。GEOCOM 的结构很清晰底下是 RPC远程过程调用模型中间是若干按业务划分的子系统上面才是你实际调用的函数。子系统的划分方式基本就等于仪器的功能模块划分看懂这张表后面翻到任何一章都不会迷路。2.1 九个子系统的职责边界按文档目录列出来的部分能整理出这样一张对照表。我在实际项目里通常会把这张表直接抄进自己的接口封装文档首页团队里谁要加功能先看该落在哪个子系统。子系统代号中文名负责的事情常用函数前缀COM通信服务端口开关、超时、双精度设置、错误文本COM_AUT自动化望远镜转向、搜索、锁定、微调、跟踪AUT_AUS用户/ATR 状态ATR 模式、锁定模式开关AUS_BAP基本应用EDM 类型、棱镜定义、测距测角BAP_BMM基本人机界面蜂鸣提示、报警音BMM_ / IOS_CSV中央服务仪器型号、序列号、时间、温度、电源CSV_EDM电子测距激光指示、发光强度EDM_FTR文件传输列表、下载、删除仪器内文件FTR_IMG图像处理望远镜相机配置、抓图IMG_COM 是最底层任何一条指令发出去之前端口必须由它打开CSV 是信息查询层我一般用它做设备自检——程序启动时先读一遍仪器型号、软件版本、当前电量和内部温度写进日志出问题时这份日志比什么都值钱AUT 和 BAP 是干活的主力一个负责看哪儿一个负责测什么FTR 和 IMG 属于锦上添花做巡检报告和远程可视化的时候才用得上。有一点容易忽略AUS 和 AUT 是两个不同的子系统前者管状态开关后者管动作执行。很多人写代码时把AUS_SetUserLockState和AUT_LockOnTarget混着用结果出现锁定了但状态还是关的这种诡异现象后面避坑那章会展开说。2.2 请求-应答模型事务号和返回码GEOCOM 不管底层走串口还是走网络上层都是严格的请求-应答一问一答没有推送。客户端发一条报文仪器回一条中间不允许插队。所以报文里必须有一个事务号Transaction ID让仪器的应答能和你的请求配对。ASCII 协议的报文形态大致是这样请求%R1P,0,0:rcsid[,param1,param2,...]\r\n应答%R1P,0,0:rcsid,RC[,ret1,ret2,...]\r\n逐段解释一下。%R是报文起始标记表示这是一个请求紧跟的数字1是事务号范围一般 1 到 255用完回绕P,0,0这三段是协议头和请求类型标识按说明书 2.3 节的 ASCII 协议语法固定填冒号后面第一个字段是rcsid也就是远程调用的函数编号这个编号必须去文档第 4 章 RPC 描述的结构 里查表不能猜再往后是入参用逗号分隔没有参数就不写。应答里的RC是返回码这是整个开发过程中你要盯得最紧的东西。RC 0表示成功非 0 就是各种错误——参数越界、设备忙、目标丢失、通信超时各有各的编号。文档 5.4.12 提供了COM_GetErrorText把返回码翻译成可读文本我在所有项目的日志函数里都强制调它一次宁可多一次往返也不要日志里出现一堆裸数字。提示事务号不是必须从 1 开始但一定要保证同一时刻未应答的报文事务号唯一。单线程同步收发的场景下简单的自增回绕就够用。2.3 ASCII、C/C 与 VBA三条调用路径怎么选文档第 2 章把函数调用协议拆成了三种形式纯 ASCII 字符串、C/C 调用、VBA 调用。这三者不是三套不同的接口而是同一套 RPC 函数的不同包装层次。纯 ASCII 是最原始的一层你自己拼字符串、自己解析返回。优点是跨语言、跨平台Python、C#、LabVIEW、甚至一个串口助手都能跑缺点是没有类型检查一个逗号写错仪器直接给你一个参数错误码排查全靠对照文档。C/C 那一层文档 3.3 节给了基本应用框架和数据类型说明。它本质上是厂商提供的一套头文件和库把 ASCII 拼装和解析封装成函数调用你写COM_Init()而不是拼%R1P,0,0:...。这套方式适合做长期维护的上位机编译期能拦住一部分错误。VBA 那一层主要面向 Excel 或仪器自带软件里的宏文档 3.4 节讲了 VBA 的数据类型派生规则和框架。实际项目里我很少用但如果甲方要求测量数据直接进 Excel 表格并现场出图VBA 反而是阻力最小的路径。我的选择习惯是原型验证和跨平台集成走 ASCII稳定交付的桌面端走 C/C办公场景走 VBA。三条路径共用一套rcsid表所以文档里那张函数编号表是核心资产值得单独抄出来做成一张配置表用代码生成常量定义别手打。2.4 类型系统双精度、角度制和字符串文档 5.3 节专门讲了COM_SetDoublePrecision和获取双精度设置。这个函数看着不起眼但它决定了浮点数在报文里保留几位小数直接影响测角测距的精度表现。默认精度下角度可能只保留到小数点后 4 位做精密监测时不够用需要在初始化阶段显式设置。角度单位是另一个高频翻车点。GEOCOM 内部的角度值通常以弧度或百分度gon表示具体取决于仪器配置而现场工程师脑子里想的是度分秒。我在封装层里固定做一次转换绝不让原始值直接流到业务代码里否则半年后接手的人一定会算错。字符串参数按 ASCII 传中文路径和中文文件名不要指望能透传FTR 下载文件时用纯英文文件名这是我吃过亏之后定下的规矩。3. 通信链路从打开端口到第一次握手协议看懂了接下来是让程序真的和仪器说上话。这一段看着简单实际上是新人卡住最多的地方——不是代码写错而是时序和参数没对上。3.1 端口参数与连接方式TS30、TS50 这类仪器对外一般提供几种物理通道串口RS232、USB、以及部分型号支持的 TCP。串口参数常见配置是 8 数据位、无校验、1 停止位波特率可配出厂常见 115200 或 9600。TCP 方式下仪器相当于一个服务端你连它的 IP 和端口报文内容完全一致只是传输层换了。初始化顺序是有讲究的不能乱1. COM_Init 初始化 GEOCOM 环境客户端侧 2. COM_OpenConnection 打开物理端口指定端口号和波特率 3. COM_SetTimeout 设置应答超时 4. COM_SetDoublePrecision 设置浮点精度 5. ...业务函数... 6. COM_CloseConnection 关闭端口 7. COM_End 释放 GEOCOM 环境COM_OpenConnection的参数里端口号在串口模式下是 COM1、COM2 这种逻辑编号波特率必须和仪器端设置完全一致。我遇到过现场仪器被上一家单位改成 19200而程序里写死 115200表现就是发什么都没反应用串口助手一看全是乱码改了波特率立刻正常。COM_SetTimeout设的是等待应答的毫秒数。默认值偏短做自动搜索这种耗时操作时容易提前超时我一般设到 5000 到 10000 毫秒具体看动作类型搜索类给足状态查询类可以短一些。3.2 一个能跑起来的最小客户端下面这段 Python 是我验证链路时常用的骨架用 pyserial 发 ASCII 帧。它不是生产代码但把报文拼装、发送、接收、返回码检查这条链路完整走了一遍改成 C 或 C# 只是换 API。import serial import time class GeoComClient: def __init__(self, port, baud115200, timeout_ms5000): # 串口八参数端口、波特率、字节位、校验、停止位、超时 self.ser serial.Serial( portport, baudratebaud, bytesizeserial.EIGHTBITS, parityserial.PARITY_NONE, stopbitsserial.STOPBITS_ONE, timeouttimeout_ms / 1000.0 ) self.trans_id 0 def _next_trans(self): # 事务号 1..255 回绕用来把应答和请求对上 self.trans_id self.trans_id % 255 1 return self.trans_id def call(self, rcsid, *params): tid self._next_trans() body ,.join(str(p) for p in params) # 协议头 %RtidP,0,0: 固定rcsid 后的逗号只在有参数时出现 frame f%R{tid}P,0,0:{rcsid} if body: frame , body frame \r\n self.ser.reset_input_buffer() # 丢掉上一次残留避免错位 self.ser.write(frame.encode(ascii)) # 应答以 \r\n 结尾读到超时或读到完整帧为止 raw self.ser.readline().decode(ascii, errorsignore).strip() if not raw: raise TimeoutError(fno reply for rcsid{rcsid}) # 形如 %R1P,0,0:rcsid,RC,ret1,ret2 payload raw.split(:, 1)[1] fields payload.split(,) rc int(fields[1]) return rc, fields[2:]核心逻辑就三段。第一段拼帧前缀固定事务号自增rcsid从文档第 4 章的 RPC 表里查参数按文档标注的顺序追加。第二段发送前先reset_input_buffer()这一步看着多余实际很关键仪器有时候会多吐一个换行或者残留上一帧的后半截不清缓冲就会解析错位。第三段解析按冒号切成两半取后半段按逗号切第二个字段固定是返回码。rcsid我特意没有写死数字。文档第 4 章给了完整的 RPC 结构描述但不同固件版本会有微小差异正确做法是照着你自己那台仪器的软件版本对应的表来填然后把它做成常量字典# 键名按子系统归类值从说明书第 4 章 RPC 描述表查得 RCSID { COM_NullProc: None, # 通信自检无参数 COM_GetSWVersion: None, # 查固件版本 CSV_GetInstrumentName: None, # 查仪器型号 AUT_LockOnTarget: None, # 锁定目标 BAP_MeasDistanceAngle: None, # 测距测角 }3.3 握手成功后先做四件事链路刚打通的时候别急着调业务函数先做一轮自检把设备状态摸清楚。我固定会跑这四个调用CSV_GetInstrumentName确认连的是不是预期那台仪器。现场多台设备同时在线接错串口的低级错误真实发生过。CSV_GetSWVersion记录固件版本。这份说明书是 2019 年前后的版本如果你的仪器固件比它新或者比它老个别函数的参数个数和行为可能有出入出问题时第一个要怀疑的就是版本不匹配。CSV_CheckPower查电源状态。自动监测点位往往没人值守电池耗尽导致程序假死的案例不少我一般把它做成定时轮询低于阈值就告警。COM_NullProc做通信自检。这个函数不带任何业务含义只验证一问一答的通路是否通畅用来区分通信断了和通信正常但业务函数报错这两种完全不同的故障。3.4 双精度设置和错误文本COM_SetDoublePrecision的入参是一个布尔或枚举控制浮点数的输出格式。做精密监测时我一般开高精度代价是报文变长、解析时要按完整长度取字段不能随便截断。反过来如果只是做目标搜索这类粗定位默认精度足够报文短了往返也快。COM_GetErrorText是把返回码翻译成文本的函数参数就是你要翻译的那个 RC 值。所有非 0 返回我都建议走一次这个调用然后把函数名 入参 RC 文本一起写进日志。现场排障的时候一句 目标未找到 比 error 1023 能省掉半小时。4. 核心模块拆解从搜索到测距这一条链路自动监测这类应用90% 的业务都落在同一条链路上望远镜转过去、找到棱镜、锁定、测距测角、把数据取回来。这条链路横跨 AUT、AUS、BAP 三个子系统下面按执行顺序拆。4.1 AUT定位公差、超时与转向AUT 子系统是自动化能力的核心。文档 7.4 节列了十几个函数真正高频用的就那么几个其余都是参数微调。动手之前先读两个设置AUT_ReadTol读当前的定位公差AUT_ReadTimeout读当前的定位超时。公差决定望远镜认为到位了的角度阈值超时决定它转多久还没到位就认输。这两个值出厂有默认但不同应用差别很大——近距固定点位可以放宽公差、缩短超时快速出结果远距或震动环境必须收紧公差、拉长超时否则会出现转到位了但其实偏了 20 角秒的隐性误差。设完参数就调AUT_LockOnTarget把望远镜转到指定的水平角Hz和垂直角V并尝试锁定。入参是目标角度返回码告诉你锁没锁上。这个函数内部其实包含粗转 精调两个阶段文档 7.4.7 的自动微调和 7.4.6 的自动转换面是它的可拆分版本需要更细粒度控制的时候用。锁定之后能不能搜到目标取决于搜索窗口。AUT_PS_SetRange设置 PowerSearch 的范围AUT_PS_SearchNext搜下一个目标。范围设太小目标稍微偏一点就搜不到设太大附近有别的棱镜容易被抓错。工地附近有反射面的时候这两行参数调起来是真的烦。4.2 BAPEDM 类型、棱镜常数与单次测量BAP 负责测什么、怎么测、按什么标准算。这里有几个参数如果不对测出来的数会系统性偏移而且偏移量看起来特别正常最难发现。BAP_GetTargetType和对应的设置函数管 EDM 测量类型——是无棱镜、是圆棱镜、还是反射片测距方式完全不同。BAP_GetPrismType2和设置函数管棱镜常数的取值来源可以取默认棱镜类型也可以取用户自定义的棱镜定义BAP_GetUserPrismDefinition/BAP_SetUserPrismDefinition。棱镜常数填错测距结果会整体差一个固定值三十米和三百米都一样差很容易被当成仪器故障其实是配置问题。BAP_MeasDistanceAngle是最常用的测量函数一次调用返回水平角、垂直角和距离。文档 8.3.12 标注了它的三个返回值顺序不能记错。4.3 一条完整的搜索-锁定-测量-取数流程把上面的函数按顺序串起来就是实际项目里最常写的那段def measure_once(client, hz, v): # 1) 设置定位公差与超时单位按说明书 7.4 节角度为弧度制 client.call(RCSID[AUT_SetTol], 0.0003, 0.0003, 0.0003) client.call(RCSID[AUT_SetTimeout], 20000, 20000) # 2) 望远镜转向目标角度并锁定 rc, _ client.call(RCSID[AUT_LockOnTarget], hz, v) if rc ! 0: # 锁定失败常见原因是遮挡或目标偏离搜索窗口 raise RuntimeError(flock failed: {rc}) # 3) 开一次精调把残余角度偏差压到公差内 rc, _ client.call(RCSID[AUT_FineAdjust], 1) if rc ! 0: raise RuntimeError(ffine adjust failed: {rc}) # 4) 单次测距测角返回 Hz、V、斜距 rc, ret client.call(RCSID[BAP_MeasDistanceAngle], 1) if rc ! 0: raise RuntimeError(fmeasure failed: {rc}) hz_out, v_out, dist float(ret[0]), float(ret[1]), float(ret[2]) return hz_out, v_out, dist逐段看。第一步设公差和超时三个公差参数分别对应水平、垂直和距离方向的收敛阈值单位是弧度或米具体看文档 7.4.1 的说明超时用毫秒。第二步AUT_LockOnTarget是动作主体失败就直接抛不要硬着头皮往下走——锁不上还去测距测出来的多半是天空或者挡板。第三步AUT_FineAdjust的入参通常是 1 表示单次精调0 表示连续连续模式会一直微调直到超时做动态跟踪时用得上静点测量用单次就够了。第四步BAP_MeasDistanceAngle的入参控制测量模式1 一般表示单次标准测量。整个流程里最关键的不是代码结构而是失败时不要吞掉返回码。我见过有人为了让程序跑得稳把返回值全用_接掉结果是程序确实不崩了但数据里混进了一堆上一次的残留值等发现的时候已经出了几十期报告。4.4 角度单位与状态一致性再强调一次单位。GEOCOM 的角度参数多数以弧度表示AUT_SetTol的公差也是弧度而国内工程习惯用度分秒或百分度。封装层里我固定提供两个函数dms_to_rad和rad_to_dms所有外部接口只接受度分秒内部转换一次杜绝混用。状态一致性是另一个隐蔽点。AUS_GetUserLockState读的是锁定模式的状态AUS_SetUserLockState设置它这是开关层面的东西AUT_LockOnTarget是动作层面的东西。逻辑上应该是先开锁定模式再执行锁定动作否则可能出现动作成功但模式未开后续跟踪直接失效的现象。我在项目里把这两步包成一个原子操作谁也别想跳过。5. 避坑与排查现场最容易翻车的五个地方下面这五条都是我在实际点位上撞过的按现象、原因、解决排列不是理论问题。5.1 发送命令没反应串口助手也看不到应答现象程序发指令出去等满超时时间返回空换串口助手手动发也是一样。原因波特率或数据位不匹配或者 RS232 的收发线接反。仪器被上一套软件改过通信参数是最常见的尤其是二手机或者接手别人项目的时候。解决先用串口助手以出厂参数逐个波特率试探能收到回显的那个就是对的确认参数后在程序启动时固定执行一次COM_OpenConnection并立刻用COM_NullProc验证验证不过就报错退出别让程序带着错误的链路继续跑。5.2 搜索总是超时但人工看望远镜确实对准了现象AUT_LockOnTarget返回非 0现场肉眼判断望远镜指向没问题。原因定位公差设得太紧加上现场有风或仪器底座轻微震动望远镜在阈值附近反复摆动永远收敛不了最后撞超时。解决先用AUT_ReadTol读出出厂值作为基准按距离和稳定性分档设置——近距离固定墩可以收紧到角秒级长距离或震动环境放宽。同时把AUT_SetTimeout拉长到 20 秒以上给收敛留时间。另外检查棱镜是否被雨雾遮挡PowerSearch 在低能见度下确实会失灵这时切到 ATR 小窗口模式效果更好。5.3 测距数据整体偏移一个固定值现象换了新程序之后所有测点的距离比历史数据系统性多出几厘米方向一致角度正常。原因棱镜常数配置错了。用了自定义棱镜定义却沿用了默认的常数或者代码里读取的是BAP_GetPrismType2的默认分支而现场实际架的不是那种棱镜。解决上点之前先做一次已知基线检核拿两个已知坐标点反算距离和观测值比对。确认偏移量后用BAP_SetUserPrismDefinition写入正确的棱镜常数并把配置项外置成参数文件不同工区不同棱镜各配一套别写死在代码里。5.4 程序跑几个小时后假死重启就好现象长时间运行后不再响应串口还能打开但所有业务函数超时重启程序恢复。原因串口缓冲区堆积。仪器在某些异常状态下会多发报文而程序只按需读取越积越多最后解析全乱。另一个可能是事务号用尽后没有正确回绕导致应答错配。解决每次发送前清输入缓冲前面代码里那句reset_input_buffer事务号严格做 255 取模回绕再加一个定时心跳每分钟调一次COM_NullProc连续三次失败就自动重连端口并且把这一分钟内的数据标记为不可信。这套机制上线之后类似故障从每天一次降到一个月都不一定有一次。5.5 文件名带中文文件下载失败现象FTR_Download一直返回参数错误换成英文文件名就正常。原因GEOCOM 的 ASCII 报文对非 ASCII 字符没有做扩展编码约定中文文件名在传输层就损坏了。解决仪器内部的存储文件名统一用英文加日期编号下载回本地之后再映射成中文名。这个约定写进项目规范而不是靠每个人自觉。6. 二次开发改造思路把说明书变成自己的 SDK文档看到最后真正的产出不是一个能跑通的 demo而是一层稳定的封装。我现在的习惯是拿到任何一套类似 GEOCOM 的仪器接口都先搭三层结构再写业务。6.1 三层封装传输、协议、业务最底下是传输层只管字节进出负责串口/TCP 的打开关闭、超时、重连对外提供send(frame)和recv()。这一层不应该出现任何rcsid。中间是协议层把每个 GEOCOM 函数包成一个带类型签名的方法入参做单位转换返回值统一解析成(rc, ret_list)非 0 时自动调COM_GetErrorText补上可读文本。这层的每个方法对应文档里的一个函数一一映射不做额外逻辑将来固件升级要改也只改这里。最上面是业务层比如measure_point(point_id)、do_scan(area)、check_device()。业务层只调用协议层方法不碰任何字符串拼接。这么分的好处是测试可控。传输层可以用模拟器替代协议层可以做报文快照测试业务层才需要真机。6.2 验证方法三档回归改完之后怎么确认没改坏我固定跑三档。第一档是报文快照把协议层每个方法生成的帧字符串 dump 出来和基线逐字节比对。这一档不需要仪器跑得飞快任何拼帧逻辑的回归当场暴露。第二档是设备自检连真机跑一遍CSV_GetInstrumentName、CSV_GetSWVersion、COM_NullProc、CSV_CheckPower确认链路和状态。这一档每次上点位之前必跑两分钟的事。第三档是几何检核在已知基线上测三个点反算距离和角度和标准值比对误差在允许范围内才算通过。这一档能抓出棱镜常数、角度单位、双精度设置这三类程序没报错但数不对的问题。配套的配置项建议外置成一张表改参数不用重新编译配置项典型值说明portCOM3串口编号或 IP:端口baud115200必须与仪器端一致timeout_ms8000搜索类动作要拉长tol_hz / tol_v0.0003 rad按距离和稳定性分档prism_const依棱镜型上点前必须检核double_precision高精度精密监测场景开启6.3 一个具体技巧用心跳加状态机兜住长时运行长期无人值守的项目最怕的不是单次测量失败而是失败之后状态错乱——上一轮的望远镜还停在半路下一轮指令已经发出去两条动作叠在一起结果谁也说不清。我的做法是给设备加一个显式状态机状态只有四个IDLE、MOVING、LOCKED、MEASURING每次动作前后校验状态非法跃迁直接拒绝执行并触发复位。复位流程不是重启程序而是走一遍软恢复AUT_LockOnTarget用当前读数原地锁定一次AUS_SetUserLockState重置锁定模式再打一个COM_NullProc心跳确认链路还在。这套走完八成以上的卡死状态能自己恢复不用人跑现场。我从那以后每次接新的测量机器人项目都会在业务代码之前先把心跳和状态机写完宁可多花半天也不要半夜被一个程序还在跑但数据停了三天的电话叫起来。这套封装思路和上面那三档验证是我拆完这份中文说明书之后真正沉淀下来的东西希望帮到你。本文还有配套的精品资源点击获取
