ComXim 可编程转盘二次开发指南
1 引言
2 ComXim 可编程转盘以开发者和系统集成者为设计出发点。与只提供遥控或 App 控制的消费级转盘不同，ComXim 转盘公开了一套统一的、基于文本的命令接口，让你能以编程方式控制设备的方方面面。
3 无论你是在构建定制的 360° 摄影自动化系统、把转盘集成到工业检测线，还是为某个垂直市场开发移动 App，CT（ComXim Turntable）命令系统都能让你完全掌控旋转、定位、快门触发、照明等更多功能。
4 本指南涵盖二次开发入门所需的一切——从理解命令结构到编写你的第一个控制程序。
5 是什么让 ComXim 转盘对开发者如此友好？
6 ComXim 转盘在市场上以对开放可编程性的坚持而脱颖而出。关键特性包括：
| 7 特性 | 8 优势 |
|---|---|
| 9 统一的 CT 指令集 | 10 相同指令在 USB、Wi-Fi 和蓝牙下通用——无需针对不同连接方式重写代码 |
| 11 纯文本指令 | 12 无需专有二进制、DLL 或 SDK——只需简单的 ASCII 字符串 |
| 13 实时反馈 | 14 确认（ACK）、事件通知和错误码让你对转盘状态有完全的可见性 |
| 15 心跳机制 | 16 内置连接监测，确保通信可靠 |
| 17 跨平台兼容 | 18 适用于 Windows、Linux、macOS、Android，以及任何支持串口或套接字通信的平台 |
| 19 多种接口 | 20 USB（虚拟 COM 端口）、Wi-Fi（TCP/IP）和蓝牙（BLE）——选择适合你架构的方式 |
21 二次开发的两条路径
22 根据你的熟练程度和需求，你可以用两种方式展开二次开发：
23 路径 1：从 TurntableX（Windows 软件）学起
24 学习 CT 指令最简单的方式是使用 TurntableX——ComXim 的 Windows 控制软件。你在软件中执行的每一个动作——点击按钮、拖动滑块、启动旋转——都会生成一条 CT 指令并显示在调试窗口中。
25 如何使用这个方法：
- 26 通过 USB 或 Wi-Fi 连接你的转盘
- 27 打开 TurntableX 并建立连接
- 28 执行动作（例如设置角度、启动步进旋转、开启快门）
- 29 观察指令显示窗口，查看对应的 CT 指令
- 30 把这些指令复制粘贴到你自己的代码中
31 这是无需翻阅大量文档就能学习指令集的最直观方式。
32 路径 2：直接进行 CT 指令编程
33 对于偏好直接使用指令集的开发者，ComXim 提供了一份完整的 CT 指令列表，记录了每一条可用指令、其参数和预期响应。
34 典型工作流程：
- 35 从 ComXim 网站下载 CT 指令列表
- 36 使用串口终端工具（例如 SSCOM、PuTTY、SecureCRT）测试指令
- 37 把指令集成到你的应用代码中
38 CT 指令基础
39 指令格式
40 所有 CT 指令都遵循严格一致的格式：
CT+COMMAND(parameter1, parameter2, ...);
41 组成部分：
- 42
CT- —— 命令前缀（标识该字符串为一条转盘命令）
- 43
+
—— 前缀与命令名之间的分隔符
CT+START(0,1,1,15,2,24);
44
COMMAND
—— 具体的命令名（例如 START、SETMODE、TURNSINGLE） |
45 | (parameter1, parameter2, ...) |
|---|---|---|
| —— 括在圆括号内的参数 | 46 | ; |
| —— 终止分号（标记命令结束） | 47 示例： | 48 响应类型 |
| 49 当转盘收到一条指令时，它会通过三种响应机制提供反馈： | 50 响应类型 | 51 格式 |
52 说明
53 确认（ACK）
- 54
CR+OK; - 55 命令已收到并被接受
- 56 事件通知
- 57
CR+EVENT=TB_END;
Note: Heartbeat can be enabled or disabled using the
CT+HEARTBEAT(onOff);command.
58 某个动作已完成（例如旋转结束）
59 错误码
60 CR+ERR=XX; |
61 发生了错误（见错误码表） | 62 心跳机制 |
|---|---|---|
| 63 转盘与控制设备维持心跳以监测连接状态： | 64 连接时，转盘每 1 秒发送一个 # 字符 |
65 如果 3 秒内未收到 # 或指令，转盘进入心跳丢失状态 |
66 在心跳丢失状态下，转盘每 1 秒发送 ##，直到通信恢复 |
67 控制设备应实现类似的监测机制 | 68 核心 CT 指令分类 |
| 69 1. 系统指令 | 70 指令 | 71 参数 |
| 72 说明 | 73 CT+ACK(onOff) |
74 0=关，1=开 |
75 启用/禁用命令确认
76 CT+EVENT(onOff) |
77 0=关，1=开 | 78 启用/禁用事件通知 |
|---|---|---|
79 CT+HEARTBEAT(onOff) |
80 0=关，1=开 | 81 启用/禁用心跳 |
82 CT+SAVECONF() |
83 无 | 84 把当前设置保存到闪存 |
| 85 2. 查询指令 | 86 指令 | 87 参数 |
| 88 说明 | 89 CT+GETPN() |
90 无 |
| 91 获取产品型号名 | 92 CT+GETEBC() |
93 无 |
94 获取唯一的电子出生码（用于软件授权）
95 CT+GETFWV() |
96 无 | 97 获取固件版本 |
|---|---|---|
98 CT+GETOFFSETANGLE() |
99 无 | 100 获取当前位置相对原点的角度 |
101 CT+GETTBCONFIG() |
102 无 | 103 获取所有已保存的配置参数 |
| 104 3. 运动控制指令 | 105 指令 | 106 参数 |
| 107 说明 | 108 CT+START(dir,mode,shutter,angle,pause,times) |
109 6 个参数 |
| 110 启动一个多步旋转序列 | 111 CT+TURNSINGLE(dir,angle) |
112 2 个参数 |
| 113 按单个指定角度旋转 | 114 CT+SETMODE(mode) |
115 0=连续，1=步进，2=摆动 |
| 116 设置旋转模式 | 117 CT+SETDIR(direction) |
118 0=顺时针，1=逆时针 |
| 119 设置旋转方向 | 120 CT+SETANGLE(angle) |
121 正浮点数（度） |
| 122 设置步进角度 | 123 CT+SETPAUSETIME(seconds) |
124 正整数 |
125 设置步与步之间的暂停时间
126 CT+SETREPEATTIMES(times) |
127 正整数 | 128 设置重复次数 |
|---|---|---|
129 CT+SETSTOP() |
130 无 | 131 立即停止旋转 |
132 CT+RUN() |
133 无 | 134 以当前设置启动旋转 |
| 135 4. 位置管理指令 | 136 指令 | 137 参数 |
138 说明
139 CT+SETZERO() |
140 无 | 141 把当前位置设为原点 |
|---|---|---|
142 CT+TOZERO() |
143 无 | 144 以最短路径回到原点 |
145 CT+TOZEROBYDIR(direction) |
146 0=顺时针，1=逆时针 | 147 按指定方向回到原点 |
| 148 5. 快门控制指令（支持快门的型号） | 149 指令 | 150 参数 |
151 说明
152 CT+SETAUTOSHUTTER(onOff) |
153 0=关，1=开 | 154 启用/禁用自动快门 |
|---|---|---|
155 CT+CAMERACTRL(focus,capture) |
156 0=关，1=开 | 157 手动相机控制（对焦 + 快门） |
158 CT+PHONECAMCTRL(time) |
159 毫秒（250-500） | 160 触发智能手机蓝牙快门 |
| 161 6. 照明控制指令（支持 LED 的型号） | 162 指令 | 163 参数 |
164 说明
165 CT+SETRGBCOLOR(R,G,B)
| 166 各为 0-255 | 167 设置 RGB LED 颜色 | 168 CT+POWERLED(ledNum,grade) |
|---|---|---|
| 169 LED 编号，亮度等级 | 170 设置电源 LED 亮度 | 171 CT+COLORLED(led1,led2,led3) |
| 172 0=关，1=开 | 173 控制单个彩色 LED | 174 入门：分步指南 |
| 175 第 1 步：选择你的连接方式 | 176 接口 | 177 如何连接 |
178 开发方式
179 USB
// Create and configure serial port
SerialPort serialPort1 = new SerialPort();
serialPort1.PortName = "COM3"; // Your COM port
serialPort1.BaudRate = 115200; // Fixed baud rate
serialPort1.Open();
// Send a command
string cmd = "CT+TURNSINGLE(0,45.0);";
serialPort1.Write(cmd);
180 通过 CH340 驱动的虚拟 COM 端口
import socket
# Connect to turntable
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect(("192.168.181.181", 8181))
# Send a command
cmd = "CT+TURNSINGLE(0,45.0);"
sock.send(cmd.encode())
181 串口编程
182 Wi-Fi
CT+GETPN(); // Should return product name
CT+GETEBC(); // Should return unique device ID
CT+TURNSINGLE(0,45.0); // Rotate 45° clockwise
183 TCP/IP 套接字（IP：192.168.181.181，端口：8181）
184 套接字编程
// 360° product photography: 24 shots, 15° per step, 2-second pause
CT+START(0,1,1,15,2,24);
185 蓝牙
186 BLE GATT 连接（BLE 4.0）
187 BLE 编程
188 第 2 步：搭建你的开发环境
CT+TURNSINGLE(0,90.0);
189 用于 USB（Windows/C# 示例）：
CR+OK;
CR+EVENT=TB_END;
190 用于 Wi-Fi（Python 示例）：
191 第 3 步：用基础指令测试
192 从简单的指令开始，验证连通性：
CT+START(0,1,1,15,2,24);
193 第 4 步：构建你的应用
- 194 基础指令跑通后，你可以构建更复杂的序列：
- 195 实用示例
- 196 示例 1：单步定位
- 197 需求：顺时针旋转 90° 并停止。
- 198 指令：
- 199 预期响应：
200 示例 2：自动化 360° 摄影
- 201 需求：围绕一整圈拍摄 24 张图像，每张之间暂停 2 秒，留给相机处理。
- 202 指令：
- 203 参数拆解：
- 204
0= 顺时针方向 - 205
1= 步进模式
206 1 = 启用自动快门
207 15 = 每步 15°（360° ÷ 24）
208 2 = 暂停 2 秒
CT+START(0,2,1,45,4,0);
209 24 = 重复 24 次
- 210 预期行为：
- 211 转盘为第一张照片触发快门
- 212 顺时针旋转 15°
- 213 暂停 2 秒
- 214 在暂停中点（约 1 秒）触发快门
- 215 重复第 2-4 步，共 24 步
216 示例 3：摆动模式
217 需求：来回摆动 45°，并在每个端点自动触发快门。
218 指令：
CT+GETOFFSETANGLE();
219 参数拆解：
OffsetAngle=+16.12° // 16.12° clockwise from origin
220 0 = 顺时针（起始方向）
221 2 = 摆动模式
222 1 = 启用自动快门
CT+CAMERACTRL(1,1);
223 45 = 45° 摆动范围
CR+OK;
224 4 = 在每个端点暂停 4 秒
225 0 = 无限重复（直到停止）
| 226 示例 4：查询当前位置 | 227 需求：检查相对原点的当前角度。 |
|---|---|
| 228 指令： | 229 预期响应： |
| 230 示例 5：手动触发相机 | 231 需求：手动触发相机对焦和快门。 |
| 232 指令： | 233 预期响应： |
| 234 错误处理 | 235 当转盘收到无效指令时，它会返回一个错误码： |
| 236 错误码 | 237 含义 |
238 CR+ERR=31 |
239 命令接收超时 |
240 CR+ERR=40 |
241 设备不支持此功能 |
242 CR+ERR=41 |
243 命令太短（< 5 个字符） |
244 CR+ERR=42 |
245 无效的命令前缀（不是“CT”） |
246 CR+ERR=43 |
247 无效的分隔符（不是“+”） |
248 CR+ERR=45 |
249 无效的参数起始（不是“(“） |
250 CR+ERR=46 |
251 无效的参数结束（不是“)”） |
252 CR+ERR=48 |
253 无效的命令终止符（不是“;”） |
254 CR+ERR=51 |
255 命令名太长 |
256 CR+ERR=52 |
257 无效的命令名 |
258 CR+ERR=61 |
259 空参数 |
260 CR+ERR=62
261 参数太长
262 CR+ERR=63
263 参数太多
264 CR+ERR=64
265 参数数量不匹配
266 CR+ERR=70
267 参数不是数值
268 CR+ERR=80
269 参数值超出有效范围
270 二次开发最佳实践
271 1. 实现心跳监测
272 务必在你的应用中实现心跳监测。如果转盘停止接收心跳，它可能进入未知状态。
273 2. 使用确认和事件
274 启用 CT+ACK(1) 和 CT+EVENT(1)，以接收确认和完成通知。这能确保你的应用知道指令何时被执行。
275 3. 保存配置
276 使用 CT+SAVECONF() 把设置保存到闪存。转盘在重新上电后将使用这些设置。 |
277 4. 优雅地处理错误 | 278 为所有指令实现错误处理。转盘可能因参数无效或功能不支持而拒绝指令。 |
|---|---|---|
| 279 5. 先用 TurntableX 测试 | 280 在编写代码之前，用 TurntableX 交互式地测试指令。该软件会显示它发送的每一条指令——把它作为你自己实现的参考。 | 281 6. 考虑连接优先级 |
| 282 当 USB 和其他控制方式同时启用时，USB 指令优先。这可防止多控制环境中的冲突。 | 283 7. 使用唯一的 EBC 进行授权 | 284 CT+GETEBC() 指令为每台转盘返回一个唯一的电子出生码。用它来在你的应用中实现软件授权或设备认证。 |
| 285 指令快速参考 | 286 分类 | 287 指令 |
| 288 示例 | 289 系统 | 290 CT+HEARTBEAT(1); |
| 291 启用心跳 | 292 系统 | 293 CT+SAVECONF(); |
| 294 保存设置到闪存 | 295 查询 | 296 CT+GETPN(); |
| 297 获取产品名 | 298 查询 | 299 CT+GETOFFSETANGLE(); |
| 300 获取当前位置 | 301 运动 | 302 CT+TURNSINGLE(0,45.0); |
| 303 顺时针旋转 45° | 304 运动 | 305 CT+START(0,1,1,15,2,24); |
| 306 24 步 360° 旋转 | 307 运动 | 308 CT+SETSTOP(); |
| 309 停止旋转 | 310 位置 | 311 CT+SETZERO(); |
| 312 把当前位置设为原点 | 313 位置 | 314 CT+TOZERO(); |
315 回到原点
316 快门
317 CT+SETAUTOSHUTTER(1);
- 318 启用自动快门
- 319 快门
- 320
CT+CAMERACTRL(1,1); - 321 触发对焦 + 快门
- 322 照明
- 323
CT+SETRGBCOLOR(255,0,0);
324 把 LED 设为红色
325 结论
| 326 ComXim 可编程转盘提供了电动转盘市场中最易上手、最灵活的二次开发平台之一。统一的 CT 指令系统在 USB、Wi-Fi 和蓝牙连接下运行方式相同，而纯文本的指令格式意味着你几乎可以把转盘控制集成到任何编程环境中。 | 327 给开发者的关键要点： |
|---|---|
| 328 从简单开始 —— 用 TurntableX 交互式学习指令 | 329 使用 CT 指令列表 —— 完整文档就是你的参考指南 |
| 330 实现心跳监测 —— 确保通信可靠 | 331 处理错误 —— 转盘提供详细的错误码 |
| 332 保存配置 —— 设置可跨断电保留 | 333 充分测试 —— 在部署到生产环境前，先与转盘一起验证指令 |
| 334 无论你是在构建定制的摄影自动化系统、把转盘集成到工业工作流程，还是开发商业应用，ComXim CT 指令系统都能提供你所需的控制力、灵活性和可靠性。 | 335 附加资源 |
| 336 资源 | 337 链接 |
| 338 官方网站 | 339 comxim.com |
| 340 用户手册与文档 | 341 comxim.com/user-guide |
| 342 软件与应用下载 | 343 comxim.com/softwareapps-demo |
344 USB 驱动