CLI 用于在 PowerShell、命令提示符或脚本中控制 ONSTEP。需要重复查询设备状态、编写自动化流程，或在不打开图形界面的情况下使用设备时，可以使用命令行工具。

CLI 与图形界面共用同一个后台服务和设备连接。在终端中连接、断开或修改设备状态，也会影响使用该服务的图形界面。

开始之前

命令行工具随 Windows 安装版提供。安装前确认电脑已具备 .NET Framework 4.8，安装方法参见下载与安装。单文件便携版不提供固定的命令行入口，请使用安装版。

安装或更新后，新开 PowerShell，查看命令帮助：

tritongoto --help

安装程序会将安装目录的 bin 加入当前用户的 PATH。提示找不到命令时，可以使用实际安装路径运行，例如：

& "$env:LOCALAPPDATA\Programs\TRITON GOTO\bin\tritongoto.exe" --help

以下示例均在 PowerShell 中执行。命令格式为 tritongoto <命令> [选项]，选项可写为 --名称 值 或 --名称=值。

TIP

示例中的 COM 端口、波特率、网络地址、坐标和设置值需要按实际设备修改。 执行移动、GOTO、返回零位或停放前，应先确认设备姿态、线缆和移动路径安全。图形界面或其他软件正在导星、拍摄时，不要同时发送冲突的控制命令。

连接设备并查询状态

使用 USB 或蓝牙串口

先列出可用串口：

tritongoto ports

找到设备对应的端口后建立连接。以下示例使用 COM5，波特率为 9600：

tritongoto connect --port COM5 --baud-rate 9600
tritongoto status

status 返回的 isConnected 为 true 时，表示设备已经连接。省略 --baud-rate 时使用默认值 9600，设备使用其他波特率时必须显式指定。

蓝牙设备需要先在 Windows 中配对，并提供虚拟串口，再按上述方法连接。串口驱动与端口检查参见快速开始。

使用 Wi-Fi

先将电脑接入设备所在网络，再填写实际 IP 与设备网络端口。例如，设备使用 192.168.0.1:9998 时：

tritongoto connect --ip 192.168.0.1 --port 9998
tritongoto status

网络连接省略 --port 时，CLI 使用的默认设备端口为 4030。它不一定与设备配置一致，建议明确填写。

使用 ASCOM

先完成ASCOM 平台与驱动安装，再检查组件：

tritongoto ascom-status
tritongoto ascom-tritongoto

使用 TRITON GOTO ASCOM 驱动连接串口设备：

tritongoto connect --ascom-driver tritongoto --port COM5 --baud-rate 9600

使用 OnStep ASCOM 驱动连接网络设备：

tritongoto connect --ascom-driver onstep --ip 192.168.0.1 --port 9998

--ascom-driver 只接受 tritongoto 或 onstep。需要多个天文软件共同使用设备时，参见ASCOM 连接与多软件协同。切换连接方式前，先运行 tritongoto disconnect 断开当前连接。

查询设备信息

连接后，可以分别读取设备信息、当前指向和设备状态：

tritongoto info
tritongoto position
tritongoto mount-status

其他查询命令按需要使用：

• connection-info：连接与设备信息；
• control-info：跟踪与手动控制信息；
• settings：当前设备设置；
• telemetry：设备轴遥测；
• search-info：寻星相关信息；
• goto-rate：当前 GOTO 速度挡位；
• alignment-status：星位校准进度；
• polar-deviation：极轴偏差。

例如，读取当前设置时运行 tritongoto settings。这些查询需要先连接设备，返回字段以当前设备实际支持的内容为准。

手动移动与跟踪

控制移动方向

先选择手动移动速率，再发送方向命令：

tritongoto set-manual-rate --rate 2X
tritongoto move --direction north

--direction 接受 north、south、east、west，分别表示北、南、东、西。

需要停止时运行：

tritongoto stop

TIP

move 会开始持续移动，命令结束或关闭终端不会自动停止设备。 请准备好停止命令，观察实际移动，并在需要时立即运行 tritongoto stop。

手动速率可使用 2X、4X、8X、20X、24X、48X、1/2MAX 和 MAX。速率含义参见开始控制。

设置跟踪与速率

开启跟踪，并选择恒星跟踪速率：

tritongoto tracking-on
tritongoto set-tracking-rate --rate sidereal

跟踪速率接受 sidereal（恒星速）、lunar（月球速）和 solar（太阳速）。关闭跟踪时运行 tritongoto tracking-off。

导星速率和 GOTO 速度分别设置：

tritongoto set-guide-rate --rate 0.5X
tritongoto set-goto-rate --gear 2

导星速率接受 0.25X、0.5X 和 1X。GOTO 速度使用 0～4 挡位编号。两者与手动移动速率不同，具体用途参见开始控制和转向与中天翻转。

按坐标寻星与同步

执行 GOTO

先确认设备的时间、位置、零位和校准状态正确，再输入已确认的目标坐标。以下仅演示坐标格式：

tritongoto goto --ra 12:30:00 --dec +45:30:00

--ra 使用时、分、秒，--dec 使用带正负号的度、分、秒。该输入方式也接受形如 +45*30:00 的赤纬。

需要指定坐标历元时，使用数值形式的赤经、赤纬：

tritongoto goto --mode radec --ra-hours 12.5 --dec-degrees 45 --epoch j2000

--epoch 接受 jnow 或 j2000，应与坐标来源一致。--ra-hours 为 0（含）至 24（不含），--dec-degrees 为 -90～90 度。

也可以使用地平坐标：

tritongoto goto --mode altaz --az-degrees 180 --alt-degrees 45

--az-degrees 为 0（含）至 360（不含），--alt-degrees 为 -90～90 度。坐标格式有效不代表设备一定允许移动到该位置，仍需满足地平线、限位和设备状态要求。

命令返回成功表示 GOTO 已被接受，不代表设备已经到达目标。随后查询 position、mount-status，并检查实际指向。坐标说明参见按坐标寻星与同步。

同步当前位置

望远镜实际指向的天体与所选目标一致，并且已经准确居中后，可以将命令中的 goto 改为 sync，使用相同格式同步坐标：

tritongoto sync --ra 12:30:00 --dec +45:30:00

同步会修改设备记录的指向坐标。不要为了消除 GOTO 偏差，直接将尚未对准的目标坐标写入设备。

查询或修改同步限制：

tritongoto sync-limit
tritongoto set-sync-limit --value 5

--value 接受 0、5、10、15、20，单位为度，0 表示不限制角距。修改前需要连接设备。使用 TRITON GOTO ASCOM 驱动连接时，查询会返回该驱动的同步限制；需要明确来源时可使用 sync-limit --source application 或 sync-limit --source driver。

零位、停放与校准

这些操作与图形界面中的功能对应。执行前应先阅读零位与停放，确认设备当前姿态和零位类型。

• tritongoto home：返回零位；
• tritongoto set-home：将当前位置重设为零位；
• tritongoto set-park：将当前位置设为停放位；
• tritongoto park：执行停放；
• tritongoto unpark：解除停放；
• tritongoto meridian-flip：立即请求中天翻转。

返回零位、停放和中天翻转可能使设备移动。返回零位与重设零位用途不同，不应互相替代。

三星校准使用 tritongoto align-three-star 开始。按三星校准的要求选择并对准每颗校准星，准确居中后运行 tritongoto align-add-star，通过 tritongoto alignment-status 查看进度。记录校准星的命令不会替代选星、GOTO 和居中操作。

tritongoto polar-deviation 用于读取极轴偏差。tritongoto polar-align-complete 仅在极轴校准流程要求的最后一步执行，不会自动完成底座的机械调整。

设置时间、位置与限位

同步电脑时间

先核对 Windows 的日期、时间与时区，再将电脑当前日期、时间写入设备。例如，观测地点使用 UTC+08:00 时：

tritongoto set-datetime --timezone +08:00

也可以明确指定日期和时间：

tritongoto set-datetime --date-time '2026-10-26 20:30:00' --timezone +08:00

--timezone 接受 +08:00、-05:30 或整数小时，范围为 UTC-12:00 至 UTC+14:00，参数值不带 UTC 前缀。省略时不写入时区。

另一种输入方式是 --date MM/DD/YY --time HH:MM:SS，不能与 --date-time 混用。--time 不能单独使用；只传 --date 时，时间使用电脑当前时间。

设置观测位置

按实际观测地点输入经纬度。例如，经度东经 120°30′、纬度北纬 30°15′：

tritongoto set-location --longitude-deg 120 --longitude-min 30 --longitude-dir E --latitude-deg 30 --latitude-min 15 --latitude-dir N --timezone +08:00

经度方向使用 E 或 W，纬度方向使用 N 或 S。经度为 0～180 度，纬度为 0～90 度，分为 0～59。可添加 --longitude-sec、--latitude-sec 指定 0～59 秒，省略时为 0；经度为 180 度或纬度为 90 度时，分和秒必须为 0。

设置后运行 tritongoto connection-info 检查时间与位置，详见时间与位置设置。

修改限位与自动中天翻转

先根据限位设置确认适合设备的范围。set-limits 必须同时填写以下七项，示例值不能直接作为所有设备的推荐值：

tritongoto set-limits --altitude-limit 90 --horizon-limit 10 --horizon-por-n - --meridian-east-limit 60 --meridian-east-por-n + --meridian-west-limit 60 --meridian-west-por-n +

• --altitude-limit：高度角上限，60～90 度；
• --horizon-limit：地平线限位的绝对值，0～30 度，正负由 --horizon-por-n 指定；
• --meridian-east-limit、--meridian-west-limit：中天东、西限位参数，0～360 且必须为 4 的倍数；正负分别由对应的 --*-por-n 指定。

三个符号参数均使用 + 或 -。CLI 的中天限位参数为时分值，4 对应 1°，例如 60 对应 15°。它与图形界面直接填写角度的方式不同；需要设置 15° 时，应填写 60，不要直接填写 15。限位含义参见中天东限位与中天西限位。

启用自动中天翻转时运行 tritongoto set-auto-flip --enabled true，关闭时将值改为 false。

TIP

时间、位置与限位可能分项写入设备。命令失败时，应检查返回结果中的 applied 字段，并重新查询当前设置，确认哪些项目已经生效。

下载固件后的刷写操作

先按固件下载与刷写确认文件与硬件匹配，结束控制、导星和拍摄，断开占用刷写串口的连接，并准备稳定供电。

以下示例使用本地已有的固件文件：

tritongoto firmware-flash --port COM5 --firmware-path 'C:\firmware\tritongoto.bin' --baud-rate 115200

--port 与 --firmware-path 必填，路径包含空格时应保留引号。刷写波特率默认 115200，与普通设备连接的波特率分别设置。

命令返回成功只表示任务已启动。随后重复查询进度：

tritongoto firmware-progress

返回的 status 为 writing 时仍在进行，completed 表示成功，error 表示失败，pending 表示尚无任务。结合 isRunning 判断刷写进程是否仍在运行，确认任务完成前不要断电、拔线或停止后台服务。

失败时运行 tritongoto firmware-output 查看原始输出。设备说明明确要求擦除时，可使用 tritongoto firmware-erase --port COM5 --baud-rate 115200；擦除会清除控制器固件内容，不要将其作为普通重试步骤。

刷写默认使用 --before-reset default_reset。设备要求不自动复位时可指定 --before-reset no_reset；仅在该模式下可添加 --chip esp8266。

打开界面与结束使用

首次执行查询或控制命令时，CLI 会在需要时自动启动后台服务，之后复用它，无需先运行图形界面。安装版运行 tritongoto open 可以打开图形界面。

需要单独启动后台服务时，运行 tritongoto service-start。该命令不会自动连接设备，仍需使用 connect 或图形界面建立连接。

结束使用前，先完成设备的停止、停放或关闭跟踪等操作，再断开连接：

tritongoto disconnect

不再使用图形界面和设备，且服务由 CLI 启动时，可以安全关闭它：

tritongoto service-stop

设备仍连接、存在固件任务或请求正在处理时，安全停止会被拒绝。先结束相应操作，等待完成后重试。service-stop --force 会强制关闭服务、断开设备并中断后台操作，使用前应确认相关任务已经结束。

TIP

tritongoto stop 用于停止设备移动，tritongoto service-stop 用于关闭后台服务。二者用途不同，不能用关闭服务替代设备停止命令。图形界面正在使用同一服务时，应先结束图形界面，再关闭 CLI 后台服务。

指定后台服务端口

存在多个匹配的后台服务时，CLI 会提示指定目标端口：

tritongoto status --api-port 38081

--api-port 是电脑本机的后台 API 端口，不是 connect --port 使用的设备串口或网络端口。显式指定后，只连接该端口，不会自动启动服务；端口范围为 1～65535。

该选项适用于查询、控制、service-start 和 service-stop，不用于 open 或帮助命令。

在 PowerShell 脚本中读取结果

命令成功及设备返回的业务错误使用 JSON 输出。帮助和参数错误使用纯文本，固定提示和错误消息使用英文。先检查退出码，再解析 JSON：

$json = tritongoto status
$exitCode = $LASTEXITCODE
if ($exitCode -ne 0) {
    throw "查询失败，退出码：$exitCode；详情：$json"
}
$result = $json | ConvertFrom-Json
if (-not $result.isConnected) {
    throw '设备未连接'
}
$result

退出码的含义：

• 0：命令成功；查询成功不等于设备已连接，仍应检查 isConnected；
• 1：操作失败，或安全停止服务被拒绝，详情在 JSON 的 error 字段；
• 2：命令或参数错误，说明写到标准错误；
• 3：服务启动、端口匹配或 HTTP 请求失败等，说明写到标准错误。

常见问题

提示找不到 tritongoto 命令

安装或更新后新开终端，检查实际安装目录的 bin 是否位于当前用户 PATH 中，也可以使用完整路径运行。单文件便携版请改用 Windows 安装版。

命令成功但设备没有连接

status 查询本身可以在未连接设备时成功。检查 isConnected，先使用 connect 或在图形界面中建立连接，再执行设备查询与控制。

提示串口被占用

检查其他直连程序是否仍在使用同一端口。多个软件需要共同使用设备时，按ASCOM 连接与多软件协同设置，不要重复打开同一个串口。

后台服务无法启动或无法确定目标实例

确认 Windows 安装版与 .NET Framework 4.8 已正确安装。存在多个运行实例时，按提示使用 --api-port 指定端口。服务仍在运行但暂时无响应时，等待当前操作结束后重试。

找不到高级配置命令

当前 CLI 不支持修改高级配置。需要修改轴参数、驱动器电流或其他高级项目时，请使用图形界面的高级配置。