企业官网建设流程全解析

简介：这份徕卡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 是最底层，任何一条指令发出去之前，端口必须由它打开；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, baud=115200, timeout_ms=5000): # 串口八参数：端口、波特率、字节位、校验、停止位、超时 self.ser = serial.Serial( port=port, baudrate=baud, bytesize=serial.EIGHTBITS, parity=serial.PARITY_NONE, stopbits=serial.STOPBITS_ONE, timeout=timeout_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) # 协议头 %R<tid>P,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", errors="ignore").strip() if not raw: raise TimeoutError(f"no 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 BAP：EDM 类型、棱镜常数与单次测量

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(f"lock failed: {rc}") # 3) 开一次精调，把残余角度偏差压到公差内 rc, _ = client.call(RCSID["AUT_FineAdjust"], "1") if rc != 0: raise RuntimeError(f"fine adjust failed: {rc}") # 4) 单次测距测角，返回 Hz、V、斜距 rc, ret = client.call(RCSID["BAP_MeasDistanceAngle"], "1") if rc != 0: raise RuntimeError(f"measure 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，确认链路和状态。这一档每次上点位之前必跑，两分钟的事。

第三档是几何检核：在已知基线上测三个点，反算距离和角度，和标准值比对，误差在允许范围内才算通过。这一档能抓出棱镜常数、角度单位、双精度设置这三类"程序没报错但数不对"的问题。

配套的配置项建议外置成一张表，改参数不用重新编译：

6.3 一个具体技巧：用心跳加状态机兜住长时运行

长期无人值守的项目，最怕的不是单次测量失败，而是失败之后状态错乱——上一轮的望远镜还停在半路，下一轮指令已经发出去，两条动作叠在一起，结果谁也说不清。我的做法是给设备加一个显式状态机，状态只有四个：IDLE、MOVING、LOCKED、MEASURING，每次动作前后校验状态，非法跃迁直接拒绝执行并触发复位。

复位流程不是重启程序，而是走一遍软恢复：AUT_LockOnTarget用当前读数原地锁定一次，AUS_SetUserLockState重置锁定模式，再打一个COM_NullProc心跳确认链路还在。这套走完，八成以上的卡死状态能自己恢复，不用人跑现场。

我从那以后每次接新的测量机器人项目，都会在业务代码之前先把心跳和状态机写完，宁可多花半天，也不要半夜被一个"程序还在跑但数据停了三天"的电话叫起来。这套封装思路和上面那三档验证，是我拆完这份中文说明书之后真正沉淀下来的东西，希望帮到你。

本文还有配套的精品资源，点击获取