robotmc 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
rmc/__init__.py ADDED
@@ -0,0 +1,18 @@
1
+ """rmc — robot_mc endpoint 工具与 Python 库(CYBERBEAST CAN 优先)。
2
+
3
+ 库用法:
4
+ from rmc import connect
5
+ with connect(channel="COM3") as dev:
6
+ print(dev.config.i_max)
7
+ dev.config.i_max = 3.5
8
+ dev.action.save()
9
+
10
+ 命令行:`rmc --help`
11
+ """
12
+
13
+ from .device import Device, connect
14
+ from .errors import EpError, NoDescriptorReply, TransportError
15
+ from .version import __version__
16
+
17
+ __all__ = ["connect", "Device", "EpError", "NoDescriptorReply", "TransportError",
18
+ "__version__"]
rmc/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ sys.exit(main())
rmc/cli.py ADDED
@@ -0,0 +1,426 @@
1
+ """rmc 命令行入口。
2
+
3
+ 用法(连接选项可以写在子命令前面或后面):
4
+ rmc # 交互 shell
5
+ rmc tree | dump | descriptor
6
+ rmc get config.i_max
7
+ rmc set config.i_max 3.5
8
+ rmc call action.save
9
+ rmc monitor telemetry.i_q telemetry.position --rate 100
10
+ rmc scan | probe
11
+ rmc backup cfg.json | restore cfg.json [--yes] [--save]
12
+ rmc liveplotter telemetry.position --window 10
13
+
14
+ 连接选项:
15
+ CAN(默认,出货板):--interface slcan|pcan|socketcan|gs_usb|… --channel COM3
16
+ 开发板:--port COM7(CDC)或 --usb(vendor interface)
17
+ """
18
+
19
+ import argparse
20
+ import json
21
+ import sys
22
+
23
+ from . import ops
24
+ from .device import connect
25
+ from .discovery import discover_devices
26
+ from .errors import EpError
27
+ from .format import format_value, print_restore, print_tree
28
+ from .protocol import (
29
+ DEFAULT_CAN_BITRATE, DEFAULT_CAN_DATA_BITRATE, DEFAULT_CAN_INTERFACE,
30
+ DEFAULT_CAN_MASTER_ID, DEFAULT_CAN_NODE_ID, DEFAULT_EP_IN, DEFAULT_EP_OUT,
31
+ DEFAULT_PID, DEFAULT_USB_INTERFACE, DEFAULT_VID, PROTOCOL_VERSION,
32
+ )
33
+ from .version import __version__
34
+ from .transport.can import CanBusManager
35
+
36
+
37
+ def _add_connection_args(parser, suppress=False):
38
+ """suppress=True 给 subparser 用:没写的选项不要覆盖主 parser 的值。"""
39
+ default = argparse.SUPPRESS if suppress else None
40
+ parser.add_argument("--can", action="store_true", default=argparse.SUPPRESS
41
+ if suppress else False,
42
+ help="走 CAN 的 CYBERBEAST SDO(默认;仅为兼容 mc_ep.py)")
43
+ parser.add_argument("--port", default=default,
44
+ help="CDC 串口(开发/台架板),例如 COM7 或 /dev/ttyACM0")
45
+ parser.add_argument("--usb", action="store_true",
46
+ default=argparse.SUPPRESS if suppress else False,
47
+ help="vendor interface 的 bulk 端点(开发/台架板)")
48
+ parser.add_argument("--vid", type=lambda s: int(s, 0),
49
+ default=DEFAULT_VID if not suppress else argparse.SUPPRESS,
50
+ help="USB VID(默认 0x%04X)" % DEFAULT_VID)
51
+ parser.add_argument("--pid", type=lambda s: int(s, 0),
52
+ default=DEFAULT_PID if not suppress else argparse.SUPPRESS,
53
+ help="USB PID(默认 0x%04X)" % DEFAULT_PID)
54
+ parser.add_argument("--usb-interface", type=int,
55
+ default=DEFAULT_USB_INTERFACE if not suppress else argparse.SUPPRESS,
56
+ help="vendor interface 号(默认 2)")
57
+ parser.add_argument("--ep-out", type=lambda s: int(s, 0),
58
+ default=DEFAULT_EP_OUT if not suppress else argparse.SUPPRESS)
59
+ parser.add_argument("--ep-in", type=lambda s: int(s, 0),
60
+ default=DEFAULT_EP_IN if not suppress else argparse.SUPPRESS)
61
+ parser.add_argument("--baud", type=int,
62
+ default=115200 if not suppress else argparse.SUPPRESS,
63
+ help="CDC 串口速率(默认 115200)")
64
+ parser.add_argument("--timeout", type=float,
65
+ default=1.0 if not suppress else argparse.SUPPRESS,
66
+ help="单次请求超时秒数(默认 1.0)")
67
+ parser.add_argument("--interface", default=default,
68
+ help="CAN 后端:slcan(CANable,默认)/pcan/socketcan/"
69
+ "gs_usb/kvaser/vector/…(python-can 的名字)")
70
+ parser.add_argument("--channel", default=default,
71
+ help="CAN 通道:slcan=COMx / pcan=PCAN_USBBUS1 / "
72
+ "socketcan=can0;不给时按后端猜")
73
+ parser.add_argument("--bitrate", type=int,
74
+ default=DEFAULT_CAN_BITRATE if not suppress else argparse.SUPPRESS,
75
+ help="仲裁域速率:Classic 下等于 config.can_baud(默认 1 Mbit/s)")
76
+ parser.add_argument("--fd", action="store_true",
77
+ default=argparse.SUPPRESS if suppress else False,
78
+ help="CAN FD(config.can_baud > 1M)")
79
+ parser.add_argument("--data-bitrate", type=int,
80
+ default=DEFAULT_CAN_DATA_BITRATE if not suppress else argparse.SUPPRESS,
81
+ help="FD 数据域速率,等于 config.can_baud(默认 5 Mbit/s)")
82
+ parser.add_argument("--can-id", type=int,
83
+ default=DEFAULT_CAN_NODE_ID if not suppress else argparse.SUPPRESS,
84
+ help="设备节点 ID,等于 config.can_id(默认 1)")
85
+ parser.add_argument("--master-id", type=lambda s: int(s, 0),
86
+ default=DEFAULT_CAN_MASTER_ID if not suppress else argparse.SUPPRESS,
87
+ help="本机主站 ID(默认 0xFE)")
88
+ parser.add_argument("--tty-baudrate", type=int,
89
+ default=115200 if not suppress else argparse.SUPPRESS,
90
+ help="slcan 串口速率(默认 115200,适配器固件固定值)")
91
+ parser.add_argument("-v", "--verbose", action="count",
92
+ default=argparse.SUPPRESS if suppress else 0)
93
+
94
+
95
+ def build_parser():
96
+ common = argparse.ArgumentParser(add_help=False)
97
+ _add_connection_args(common, suppress=True)
98
+
99
+ parser = argparse.ArgumentParser(
100
+ prog="rmc",
101
+ description="robot_mc endpoint 上位机(CAN 优先;兼容 mc_ep.py 的开发板 USB 入口)\n"
102
+ "不带子命令时进入交互 shell。",
103
+ formatter_class=argparse.RawDescriptionHelpFormatter,
104
+ epilog=__doc__,
105
+ parents=[common])
106
+ parser.add_argument("--version", action="version",
107
+ version="rmc %s (protocol %d)" % (__version__, PROTOCOL_VERSION))
108
+
109
+ sub = parser.add_subparsers(dest="cmd")
110
+
111
+ def add(name, help_text):
112
+ return sub.add_parser(name, help=help_text, parents=[common])
113
+
114
+ add("shell", "交互 shell(默认)")
115
+ add("tree", "打印设备自带的参数树")
116
+
117
+ p = add("dump", "读取所有可读参数")
118
+ p.add_argument("--persist", action="store_true", help="只导出 persist 参数")
119
+ p.add_argument("--json", default=None, help="另存为 JSON 文件")
120
+
121
+ p = add("descriptor", "打印原始 JSON 描述符")
122
+ p.add_argument("--raw", action="store_true", help="输出紧凑 JSON")
123
+
124
+ p = add("scan", "只听 CAN 总线,列出节点与消息(不发帧)")
125
+ p.add_argument("--seconds", type=float, default=2.0)
126
+
127
+ p = add("probe", "链路诊断:监听总线并试读描述符")
128
+ p.add_argument("--seconds", type=float, default=2.0)
129
+
130
+ p = add("get", "读一个或多个参数")
131
+ p.add_argument("names", nargs="+")
132
+
133
+ p = add("set", "写一个参数(打印读回的实际值)")
134
+ p.add_argument("name")
135
+ p.add_argument("value")
136
+ p.add_argument("--no-verify", action="store_true",
137
+ help="只发写请求,不读回(CAN ACK 无状态,不推荐)")
138
+
139
+ p = add("call", "执行一个 action.* 端点")
140
+ p.add_argument("names", nargs="+")
141
+ p.add_argument("--read", action="store_true",
142
+ help="用“读”请求触发(ODrive/JointSDK 的做法;固件两种都接受)")
143
+
144
+ p = add("monitor", "周期读取若干参数")
145
+ p.add_argument("names", nargs="+")
146
+ p.add_argument("--rate", type=float, default=10.0, help="刷新率 Hz(默认 10)")
147
+ p.add_argument("--count", type=int, default=None, help="采多少行后退出(默认一直跑)")
148
+
149
+ p = add("backup", "把 persist 参数导出为 JSON")
150
+ p.add_argument("file")
151
+
152
+ p = add("restore", "把 JSON 里的 persist 参数写回设备(默认 dry-run)")
153
+ p.add_argument("file")
154
+ p.add_argument("--yes", action="store_true", help="真的写入(默认只显示 diff)")
155
+ p.add_argument("--save", action="store_true", help="写完后调用 action.save")
156
+
157
+ def add_liveplotter(name, help_text):
158
+ p = sub.add_parser(name, parents=[common], help=help_text)
159
+ p.add_argument("names", nargs="+")
160
+ p.add_argument("--rate", type=float, default=20.0)
161
+ p.add_argument("--window", type=float, default=10.0, help="显示窗口秒数")
162
+ p.add_argument("--duration", type=float, default=None, help="运行多少秒后退出")
163
+ return p
164
+
165
+ add_liveplotter("liveplotter", "实时曲线(需要 matplotlib)")
166
+ add_liveplotter("plot", argparse.SUPPRESS).set_defaults(cmd="liveplotter")
167
+
168
+ add("version", "打印版本")
169
+ return parser
170
+
171
+
172
+ def _get(args, name, default):
173
+ value = getattr(args, name, None)
174
+ return default if value is None else value
175
+
176
+
177
+ def connection_kwargs(args):
178
+ """CLI 选项 -> rmc.connect() 的关键字参数。"""
179
+ port = _get(args, "port", None)
180
+ use_usb = bool(_get(args, "usb", False))
181
+ timeout = _get(args, "timeout", 1.0)
182
+ if port and use_usb:
183
+ raise EpError("--port 和 --usb 只能选一个")
184
+ if bool(_get(args, "can", False)) and (port or use_usb):
185
+ raise EpError("--can 与 --port/--usb 互斥")
186
+ if port:
187
+ return {"port": port, "timeout": timeout, "baud": _get(args, "baud", 115200)}
188
+ if use_usb:
189
+ return {
190
+ "usb": True,
191
+ "timeout": timeout,
192
+ "vid": _get(args, "vid", DEFAULT_VID),
193
+ "pid": _get(args, "pid", DEFAULT_PID),
194
+ "usb_interface": _get(args, "usb_interface", DEFAULT_USB_INTERFACE),
195
+ "ep_out": _get(args, "ep_out", DEFAULT_EP_OUT),
196
+ "ep_in": _get(args, "ep_in", DEFAULT_EP_IN),
197
+ }
198
+ return {
199
+ "interface": _get(args, "interface", DEFAULT_CAN_INTERFACE),
200
+ "channel": _get(args, "channel", None),
201
+ "bitrate": _get(args, "bitrate", DEFAULT_CAN_BITRATE),
202
+ "fd": bool(_get(args, "fd", False)),
203
+ "data_bitrate": _get(args, "data_bitrate", DEFAULT_CAN_DATA_BITRATE),
204
+ "node_id": _get(args, "can_id", DEFAULT_CAN_NODE_ID),
205
+ "master_id": _get(args, "master_id", DEFAULT_CAN_MASTER_ID),
206
+ "timeout": timeout,
207
+ "tty_baudrate": _get(args, "tty_baudrate", 115200),
208
+ }
209
+
210
+
211
+ def _open_device(args, fetch=True):
212
+ return connect(fetch=fetch, **connection_kwargs(args))
213
+
214
+
215
+ # --------------------------------------------------------------------------
216
+ # 子命令
217
+ # --------------------------------------------------------------------------
218
+
219
+
220
+ def cmd_tree(dev, args):
221
+ print_tree(dev)
222
+ return 0
223
+
224
+
225
+ def cmd_dump(dev, args):
226
+ rows = {}
227
+ for ep in dev.endpoints:
228
+ if ep["type"] in ("void", "function") or ep["access"] not in ("r", "rw"):
229
+ continue
230
+ if getattr(args, "persist", False) and not ep.get("persist"):
231
+ continue
232
+ try:
233
+ value = dev.read(ep["name"])
234
+ rows[ep["name"]] = value
235
+ print("%-36s %s" % (ep["name"], format_value(value)))
236
+ except EpError as e:
237
+ print("%-36s <错误: %s>" % (ep["name"], e))
238
+ if getattr(args, "json", None):
239
+ with open(args.json, "w", encoding="utf-8") as handle:
240
+ json.dump(rows, handle, indent=2, ensure_ascii=False)
241
+ print("已写入 %s(%d 项)" % (args.json, len(rows)), file=sys.stderr)
242
+ return 0
243
+
244
+
245
+ def cmd_get(dev, args):
246
+ values = []
247
+ for name in args.names:
248
+ value = dev.read(name)
249
+ values.append((name, value))
250
+ if len(values) == 1:
251
+ print(format_value(values[0][1]))
252
+ else:
253
+ for name, value in values:
254
+ print("%-36s %s" % (name, format_value(value)))
255
+ return 0
256
+
257
+
258
+ def cmd_set(dev, args):
259
+ ep = dev._entry(args.name)
260
+ from .protocol import parse_value
261
+ try:
262
+ requested = parse_value(args.value, ep["type"])
263
+ except (TypeError, ValueError) as e:
264
+ raise EpError(str(e))
265
+ actual = dev.write(args.name, requested, verify=not args.no_verify)
266
+ print(format_value(actual) if actual is not None else "OK")
267
+ if actual is not None and actual != requested:
268
+ print("注意: 请求 %s,设备读回 %s(被限幅或被拒绝)"
269
+ % (format_value(requested), format_value(actual)), file=sys.stderr)
270
+ return 0
271
+
272
+
273
+ def cmd_call(dev, args):
274
+ for name in args.names:
275
+ dev.call(name, via_read=args.read)
276
+ print("OK")
277
+ return 0
278
+
279
+
280
+ def cmd_monitor(dev, args):
281
+ ops.monitor(dev, args.names, rate=args.rate, count=args.count)
282
+ return 0
283
+
284
+
285
+ def cmd_descriptor(dev, args):
286
+ if args.raw:
287
+ print(json.dumps(dev.endpoints, separators=(",", ":")))
288
+ else:
289
+ print(json.dumps(dev.endpoints, indent=2, ensure_ascii=False))
290
+ print("// %d endpoints, CRC16=0x%04X" % (len(dev.endpoints), dev.json_crc),
291
+ file=sys.stderr)
292
+ return 0
293
+
294
+
295
+ def cmd_scan(args):
296
+ kwargs = connection_kwargs(args)
297
+ if kwargs.get("port") or kwargs.get("usb"):
298
+ raise EpError("scan 只在 --can 下可用")
299
+ kwargs.pop("timeout", None)
300
+ by_source = ops.scan(args.seconds, **kwargs)
301
+ ops.print_scan(by_source, kwargs.get("node_id"))
302
+ return 0
303
+
304
+
305
+ def cmd_probe(dev, args):
306
+ return 0 if ops.probe(dev, seconds=args.seconds) else 3
307
+
308
+
309
+ def cmd_backup(dev, args):
310
+ data = dev.backup()
311
+ with open(args.file, "w", encoding="utf-8") as handle:
312
+ json.dump(data, handle, indent=2, ensure_ascii=False)
313
+ print("已写入 %s(%d 项,描述符 CRC %s)"
314
+ % (args.file, len(data["values"]), data["descriptor_crc"]))
315
+ if data.get("errors"):
316
+ print("有 %d 项读取失败(已记录在 errors 里)" % len(data["errors"]),
317
+ file=sys.stderr)
318
+ return 0
319
+
320
+
321
+ def cmd_restore(dev, args):
322
+ with open(args.file, "r", encoding="utf-8") as handle:
323
+ data = json.load(handle)
324
+ results = dev.restore(data, dry_run=not args.yes)
325
+ changed = print_restore(results)
326
+ if not args.yes:
327
+ print("dry-run:加 --yes 才会写入;再加 --save 写 flash。")
328
+ return 0
329
+ if args.save and changed:
330
+ if dev.save():
331
+ print("已调用 action.save。")
332
+ else:
333
+ print("固件没有 action.save。", file=sys.stderr)
334
+ return 0
335
+
336
+
337
+ def cmd_liveplotter(dev, args):
338
+ from . import liveplot
339
+ liveplot.run(dev, args.names, rate=args.rate, window=args.window,
340
+ duration=args.duration)
341
+ return 0
342
+
343
+
344
+ def cmd_shell(args):
345
+ from .shell import ShellSession, launch_shell
346
+
347
+ kwargs = connection_kwargs(args)
348
+ can_manager = CanBusManager()
349
+ explicit_port = bool(_get(args, "port", None))
350
+ explicit_usb = bool(_get(args, "usb", False))
351
+ devices, errors = discover_devices(
352
+ kwargs, include_can=not (explicit_port or explicit_usb),
353
+ include_usb=True, port=_get(args, "port", None),
354
+ cdc=not explicit_usb, vendor=not explicit_port,
355
+ seconds=1.0, can_manager=can_manager)
356
+ session = ShellSession(connect_kwargs=kwargs, can_manager=can_manager)
357
+ session.discovery_errors = errors
358
+ for device in devices:
359
+ session.register(device)
360
+ launch_shell(session)
361
+ return 0
362
+
363
+
364
+ def cmd_version():
365
+ print("rmc %s (protocol %d)" % (__version__, PROTOCOL_VERSION))
366
+ return 0
367
+
368
+
369
+ # --------------------------------------------------------------------------
370
+ # main
371
+ # --------------------------------------------------------------------------
372
+
373
+
374
+ def main(argv=None):
375
+ parser = build_parser()
376
+ args = parser.parse_args(argv)
377
+ cmd = getattr(args, "cmd", None) or "shell"
378
+
379
+ if cmd == "version":
380
+ return cmd_version()
381
+ if cmd == "shell":
382
+ return cmd_shell(args)
383
+ if cmd == "scan":
384
+ try:
385
+ return cmd_scan(args)
386
+ except EpError as e:
387
+ print("错误: %s" % e, file=sys.stderr)
388
+ return 2
389
+
390
+ dev = None
391
+ try:
392
+ # probe 必须先能监听/诊断,不能被“描述符读取失败”挡在门外
393
+ dev = _open_device(args, fetch=(cmd != "probe"))
394
+ handlers = {
395
+ "tree": cmd_tree,
396
+ "dump": cmd_dump,
397
+ "descriptor": cmd_descriptor,
398
+ "get": cmd_get,
399
+ "set": cmd_set,
400
+ "call": cmd_call,
401
+ "monitor": cmd_monitor,
402
+ "probe": cmd_probe,
403
+ "backup": cmd_backup,
404
+ "restore": cmd_restore,
405
+ "liveplotter": cmd_liveplotter,
406
+ }
407
+ handler = handlers.get(cmd)
408
+ if handler is None:
409
+ print("未知子命令: %s" % cmd, file=sys.stderr)
410
+ return 2
411
+ return handler(dev, args)
412
+ except EpError as e:
413
+ print("错误: %s" % e, file=sys.stderr)
414
+ return 2
415
+ except KeyboardInterrupt:
416
+ return 0
417
+ finally:
418
+ if dev is not None:
419
+ try:
420
+ dev.close()
421
+ except Exception:
422
+ pass
423
+
424
+
425
+ if __name__ == "__main__":
426
+ sys.exit(main())