r1-python-sdk 0.2.0__tar.gz

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.
Files changed (43) hide show
  1. r1_python_sdk-0.2.0/.gitignore +35 -0
  2. r1_python_sdk-0.2.0/LICENSE +202 -0
  3. r1_python_sdk-0.2.0/PKG-INFO +399 -0
  4. r1_python_sdk-0.2.0/README.md +370 -0
  5. r1_python_sdk-0.2.0/README_zh.md +347 -0
  6. r1_python_sdk-0.2.0/examples/01_connect_and_read.py +41 -0
  7. r1_python_sdk-0.2.0/examples/02_live_monitor.py +45 -0
  8. r1_python_sdk-0.2.0/examples/03_gripper.py +25 -0
  9. r1_python_sdk-0.2.0/examples/04_set_joint_zero.py +40 -0
  10. r1_python_sdk-0.2.0/examples/05_single_joint.py +60 -0
  11. r1_python_sdk-0.2.0/examples/06_move_joints.py +34 -0
  12. r1_python_sdk-0.2.0/examples/07_get_current_joints.py +32 -0
  13. r1_python_sdk-0.2.0/examples/08_interactive_joints.py +108 -0
  14. r1_python_sdk-0.2.0/examples/09_servo_stream.py +35 -0
  15. r1_python_sdk-0.2.0/examples/10_control_loop.py +43 -0
  16. r1_python_sdk-0.2.0/examples/11_cartesian.py +53 -0
  17. r1_python_sdk-0.2.0/pyproject.toml +56 -0
  18. r1_python_sdk-0.2.0/r1_python_sdk/__init__.py +22 -0
  19. r1_python_sdk-0.2.0/r1_python_sdk/api.py +40 -0
  20. r1_python_sdk-0.2.0/r1_python_sdk/base.py +1075 -0
  21. r1_python_sdk-0.2.0/r1_python_sdk/board.py +71 -0
  22. r1_python_sdk-0.2.0/r1_python_sdk/code.py +161 -0
  23. r1_python_sdk-0.2.0/r1_python_sdk/config.py +124 -0
  24. r1_python_sdk-0.2.0/r1_python_sdk/damiao.py +239 -0
  25. r1_python_sdk-0.2.0/r1_python_sdk/decorator.py +57 -0
  26. r1_python_sdk-0.2.0/r1_python_sdk/gripper.py +125 -0
  27. r1_python_sdk-0.2.0/r1_python_sdk/kin/__init__.py +19 -0
  28. r1_python_sdk-0.2.0/r1_python_sdk/kin/chain.py +149 -0
  29. r1_python_sdk-0.2.0/r1_python_sdk/kin/ik.py +180 -0
  30. r1_python_sdk-0.2.0/r1_python_sdk/kin/transform.py +133 -0
  31. r1_python_sdk-0.2.0/r1_python_sdk/kinematics.py +342 -0
  32. r1_python_sdk-0.2.0/r1_python_sdk/logport.py +105 -0
  33. r1_python_sdk-0.2.0/r1_python_sdk/protocol.py +354 -0
  34. r1_python_sdk-0.2.0/r1_python_sdk/servo.py +287 -0
  35. r1_python_sdk-0.2.0/r1_python_sdk/transport.py +246 -0
  36. r1_python_sdk-0.2.0/r1_python_sdk/utils.py +50 -0
  37. r1_python_sdk-0.2.0/r1_python_sdk/version.py +1 -0
  38. r1_python_sdk-0.2.0/tests/conftest.py +5 -0
  39. r1_python_sdk-0.2.0/tests/fake_board.py +432 -0
  40. r1_python_sdk-0.2.0/tests/test_api.py +623 -0
  41. r1_python_sdk-0.2.0/tests/test_damiao.py +68 -0
  42. r1_python_sdk-0.2.0/tests/test_kin.py +315 -0
  43. r1_python_sdk-0.2.0/tests/test_protocol.py +82 -0
@@ -0,0 +1,35 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+ *.egg-info/
6
+ *.egg
7
+ build/
8
+ dist/
9
+ .eggs/
10
+
11
+ # virtual environments / tool caches
12
+ .venv/
13
+ venv/
14
+ env/
15
+ .pytest_cache/
16
+ .mypy_cache/
17
+ .ruff_cache/
18
+ .coverage
19
+ .coverage.*
20
+ htmlcov/
21
+ .tox/
22
+
23
+ # editors / OS
24
+ .vscode/
25
+ .idea/
26
+ *.swp
27
+ *~
28
+ .DS_Store
29
+ Thumbs.db
30
+
31
+ # run-time output
32
+ *.log
33
+ *.csv
34
+ *.npz
35
+ *.traj
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
@@ -0,0 +1,399 @@
1
+ Metadata-Version: 2.5
2
+ Name: r1-python-sdk
3
+ Version: 0.2.0
4
+ Summary: Python SDK for the Richtech R1 six-axis robotic arm (Damiao motors + in-house bottom board / end-effector board)
5
+ Project-URL: Homepage, https://github.com/Richtech-Robotics/R1-Python-SDK
6
+ Project-URL: Repository, https://github.com/Richtech-Robotics/R1-Python-SDK
7
+ Project-URL: Issues, https://github.com/Richtech-Robotics/R1-Python-SDK/issues
8
+ Author: RRChaoW
9
+ License-Expression: Apache-2.0
10
+ License-File: LICENSE
11
+ Keywords: damiao,kinematics,manipulator,r1,richtech,robot arm,robotics
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Scientific/Engineering
19
+ Classifier: Topic :: System :: Hardware :: Hardware Drivers
20
+ Requires-Python: >=3.9
21
+ Requires-Dist: numpy>=1.22
22
+ Requires-Dist: pyserial>=3.5
23
+ Provides-Extra: dev
24
+ Requires-Dist: pytest>=7; extra == 'dev'
25
+ Requires-Dist: pyyaml>=6; extra == 'dev'
26
+ Provides-Extra: yaml
27
+ Requires-Dist: pyyaml>=6; extra == 'yaml'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # r1-python-sdk
31
+
32
+ [English](README.md) · [简体中文](README_zh.md)
33
+
34
+ Python SDK for the Richtech R1 six-axis robotic arm (Damiao motors + in-house bottom board / end-effector board).
35
+
36
+ ```python
37
+ from r1_python_sdk import R1API
38
+
39
+ with R1API(port="COM5") as arm: # omit port to auto-detect the bottom board (VID 0483 / PID 7154)
40
+ arm.motion_enable(True) # clear errors → enable → confirm mode → seed the hold target
41
+ arm.set_servo_angle([0, -30, 60, 0, 30, 0], speed=30, wait=True)
42
+ arm.close_gripper(wait=True)
43
+ code, q = arm.get_servo_angle() # degrees by default; R1API(is_radian=True) for radians
44
+ code, btn = arm.get_end_button_state() # end-effector blue/green buttons, E-stop mushroom (reported by the board over USB)
45
+ ```
46
+
47
+ ```
48
+ pip install -e . # dependencies: pyserial + numpy (numpy only for the Cartesian kinematics)
49
+ pip install -e .[yaml] # + YAML config
50
+ pip install -e .[dev] # + pytest; `pytest` runs the offline tests (fake board, no hardware)
51
+ ```
52
+
53
+ ---
54
+
55
+ ## 1. Core ideas
56
+
57
+ ### 1.1 For R1, the SDK *is* the controller
58
+
59
+ A conventional industrial arm ships with a controller box; the SDK just forwards commands and planning,
60
+ interpolation and the state machine live in the box. R1 has none of that: the PC talks **directly to the Damiao
61
+ motors** through the bottom board's USB-CAN bridge, and the board only runs the teach / replay / E-stop state
62
+ machine and blocking. So keep-alive, mode switching, state derivation, in-position checks, Cartesian
63
+ interpolation and kinematics all live in the SDK.
64
+
65
+ Interface conventions:
66
+
67
+ | Convention | Where it shows up |
68
+ |---|---|
69
+ | `set_*` returns `code`, `get_*` returns `(code, value)`, `wait=`, `is_radian=`, `register_*_callback`, mixins split by feature | every public method; one file per group: `servo.py / gripper.py / board.py …` |
70
+ | Per-joint zeroing | `set_joint_zero` |
71
+ | User control callback `start_control_loop(fn, rate)`; per-joint parameters live in the config | `start_control_loop`, `R1Config` |
72
+
73
+ Deliberately left out: PC-triggered teach / replay and trajectory read/write. On R1, teaching is done by a person
74
+ next to the arm pressing the end-effector buttons; the PC only "watches" (`get_state()` / `get_trajectory_info()` /
75
+ event callbacks).
76
+
77
+ Also left out: a C shared library + ctypes (an extra layer to maintain; R1 does not need cross-language support),
78
+ and anything unsafe for an arm carrying a gravity load, such as "motors lose torque if the user stops sending frames",
79
+ "`estop()` = disable", or "`get_positions()` hits the bus every call".
80
+
81
+ ### 1.2 Three safety rules (you will see them everywhere in the code)
82
+
83
+ 1. **The arm never goes limp.** Once connected the SDK runs a keep-alive thread that re-sends the last target to the
84
+ motors at `config.keepalive_hz`. `emergency_stop()` *pins* the arm at its current position; it does not disable.
85
+ An exception in the user control callback only stops the callback; keep-alive continues. To actually drop torque you
86
+ must call `motion_enable(False)` explicitly. The board's E-stop mushroom behaves the same way: if it is pressed while
87
+ the PC is in control, the board switches each motor to MIT and pins it (it waits for the mode-change acknowledgement
88
+ before sending any MIT frame); after reset it stays in HOLD, `get_state()` = PAUSED, and the PC must call
89
+ `motion_enable(True)` again to regain control.
90
+ 2. **Never steal control from the board by accident.** While the board is in HOLD, only enable / disable / clear-error /
91
+ set-zero control frames and `0x7FF` register **writes** count as "intent to take over" (see
92
+ `r1_usb_can.c: host_frame_is_arm_takeover`). The SDK only sends those inside `motion_enable(True)`; feedback is
93
+ requested with the `0x7FF 0xCC` refresh frame, which is not a write, so the board keeps control. `clean_error()`
94
+ refuses to run while blocked and not enabled, because after taking over nobody would be holding the arm.
95
+ 3. **Always know who is in control.** `get_state()` merges the board state machine (TEACH/HOLD/REPLAY/ESTOP),
96
+ motor feedback freshness and consecutive TX_FAILs into a single `ArmState`; when the board drops a PC command the
97
+ SDK returns `HOST_BLOCKED` instead of pretending it succeeded.
98
+
99
+ ### 1.3 Three kinds of "not available", reported separately
100
+
101
+ | Return code | Meaning | Example |
102
+ |---|---|---|
103
+ | `CMD_NOT_EXIST (-4)` | This machine simply does not have it | `set_gripper_enable` (the end board manages itself), `set_mode(2)` (teach is only entered with the blue button) |
104
+ | `NOT_IMPLEMENTED (-5)` | Not written in the SDK yet, planned | (nothing at the moment; Cartesian APIs landed in 0.2.0) |
105
+ | `FIRMWARE_PENDING (-6)` | SDK hook is ready, waiting for the firmware to expose the frame | firmware version in `get_version()` |
106
+
107
+ Placeholders are callable and have docstrings describing their future semantics; `last_error` tells you what to do now.
108
+
109
+ ### 1.4 v1 keeps one main path only
110
+
111
+ Connect → enable → move joints (three modes) → Cartesian straight-line moves → gripper → watch state / buttons /
112
+ events. About 45 usable public methods, plus one placeholder (firmware version) that returns `FIRMWARE_PENDING`.
113
+ Removed: `set_state(0/3/4)`, `reset`, `clean_warn`, `set_default_speed` (moved into config), `set_joint_maxacc/jerk`
114
+ (use `set_servo_register`), `get_servo_version`, four rarely used callback pairs, and the whole group of PC-triggered
115
+ teach / replay / trajectory read/write.
116
+ Added: `set_joint_zero`, `get_end_button_state`, `start_control_loop`, `R1Config`, `get_joint_states` (everything in one call).
117
+
118
+ ---
119
+
120
+ ## 2. API overview
121
+
122
+ ### Connection
123
+ | API | Notes |
124
+ |---|---|
125
+ | `R1API(port=None, log_port=None, is_radian=False, config=None, do_not_open=False)` | `log_port` is the board's USART2 log port, optional (board state already comes over USB; the log port only adds text logs); `config` see §4 |
126
+ | `connect(port=None, log_port=None) → code` | heartbeat handshake confirms the other side is the bottom board |
127
+ | `disconnect() → code` | stops callbacks and keep-alive; **does not disable** (see §1.2) |
128
+ | `connected` `ready` `motion_enabled` `version` `last_error` `config` | properties; `motion_enabled` = PC has enabled and is not blocked by the board (False during teach / HOLD / E-stop) |
129
+ | `with R1API(...) as arm:` | calls `disconnect()` on exit |
130
+
131
+ ### Enable / mode / state
132
+ | API | Notes |
133
+ |---|---|
134
+ | `motion_enable(enable=True, servo_id=None) → code` | enable = take over from the board's HOLD; `servo_id` for a single joint |
135
+ | `set_mode(mode) → code` / `get_mode()` / `mode` | 0 position · 1 servo (MIT) · 4 velocity; 2 teach is a board state and cannot be set → `CMD_NOT_EXIST` |
136
+ | `get_state() → (code, ArmState)` / `state` | READY MOVING PAUSED (board HOLD, including after E-stop reset) STOPPING TEACHING PLAYBACK ESTOP INITIALIZING BLOCKED |
137
+ | `get_err_warn_code() → (code, [err, warn])` / `error_code` `warn_code` `has_error` | `R1Error`: E-stop / feedback lost / board alarm / motor fault (with axis number + Damiao status); `R1Warn`: blocked / feedback stale / gripper |
138
+ | `error_text(err) → str` | |
139
+ | `clean_error() → code` | clears errors on all six axes; refused while blocked and not enabled |
140
+ | `emergency_stop() → code` | software E-stop, no torque drop. PC in control: pins for 0.5 s, rejects motion during that window, then back to READY. Board in control (teach / replay / HOLD / E-stop, PC blocked): sends the local command `0x7F4 PAUSE` instead; the board enters HOLD and pins the arm as if the green button were pressed; returns NORMAL only on TX_OK (state is then PAUSED; call `motion_enable(True)` to take it back); old firmware that does not recognise it returns RES_TIMEOUT. The hardware E-stop is the mushroom on the board, see §3 |
141
+ | `request_board_pause() → code` | only sends `0x7F4 PAUSE` without touching the PC-side target; in NORMAL state the board replies TX_FAIL (the PC is in control, use `emergency_stop`) |
142
+ | `get_board_version() → BoardVersion \| None` | sends `0x7F4 GET_VERSION`; the board answers with local report `0x25`: `board` (2 = bottom board), `version` (x, y, z), `min_tool` (minimum required R1-Board-Config version); works while blocked too. `connect()` already asks once and stores the result in the `board_version` property; old firmware ignores it and you get None |
143
+ | `get_is_moving() → bool` | |
144
+
145
+ ### Joints
146
+ | API | Notes |
147
+ |---|---|
148
+ | `set_servo_angle(angle, speed=None, wait=False, timeout=None, servo_id=None, relative=False) → code` | position mode. `speed` in °/s caps the velocity, default `config.speed_default`; `wait` waits until all six axes are within ±0.5° and stationary |
149
+ | `set_servo_angle_j(angles, kp=None, kd=None) → code` | servo mode; only the latest command is kept and the keep-alive thread sends it at `keepalive_hz` |
150
+ | `vc_set_joint_velocity(speeds, duration=-1) → code` | velocity mode; automatically zeroed when `duration` expires |
151
+ | `move_gohome(speed=None, wait=True) → code` | all six axes to 0 |
152
+ | `get_servo_angle(servo_id=None) → (code, [6] \| float)` | uses the feedback cache; when not enabled it automatically sends a `0xCC` refresh (rate-limited to 5 Hz); returns `FB_LOST` when stale but still gives the value |
153
+ | `get_joint_states() → (code, {pos, vel, tau, temp, status})` | everything in one call |
154
+ | `request_feedback() → code` | actively request one round of feedback (refresh frame, does not take over) |
155
+ | `set_joint_limits(limits) / get_joint_limits()` | soft limits, override `config.joint_limits`; `None` disables |
156
+ | `set_joint_zero(servo_id=None) → code` | set the current position as the motor zero (Damiao FE, stored in the motor). **You must call `motion_enable(False)` first** |
157
+ | `get_servo_register(servo_id, rid) / set_servo_register(servo_id, rid, value)` | advanced: tune ACC/DEC/PID etc., RIDs in `damiao.RID_*`. Writing a register counts as a takeover |
158
+ | `angles` `joints_torque` `temperatures` `joints` | properties |
159
+
160
+ ### Gripper (end board `0x7F1` / `0x7F2`)
161
+ | API | Notes |
162
+ |---|---|
163
+ | `set_gripper_position(pos, wait=False, timeout=None) → code` | 0 fully closed ~ 100 fully open |
164
+ | `open_gripper(wait) / close_gripper(wait)` | |
165
+ | `get_gripper_position() → (code, percent)` | `GRIPPER_NOT_INIT` if not homed |
166
+ | `get_gripper_status() → (code, 0 not homed / 1 homing / 2 ready / 3 fault)` / `gripper_status` | |
167
+ | `set_gripper_init() → code` | Damiao gripper: re-home; AgiBot RS-485 gripper: re-handshake. The only way to recover from FAULT |
168
+ | `stop_gripper() → code` | |
169
+ | `set_gripper_param(speed=None, acc=None, dec=None, current=None, save=False) → code` | 0x7F1 PARAM, each value 0~255, `None` leaves it unchanged; `save` writes to the end board's Flash. AgiBot gripper: acc/dec/current are written to the gripper immediately, speed is applied on the next `set_gripper_position`; Damiao gripper: stored only, not used yet |
170
+ | `set_gripper_speed(speed, save=False)` / `set_gripper_force(force, save=False)` | shorthands for the above; force = current limit |
171
+ | `set_gripper_enable` | `CMD_NOT_EXIST` |
172
+
173
+ ### Board / end-effector buttons / taught trajectory (local reports from the board over the USB-CAN bridge, one batch every 40 ms)
174
+ | API | Notes |
175
+ |---|---|
176
+ | `get_board_state() → (code, BoardStatus)` | state machine, flags, feedback bitmap, trajectory point count / progress, motor mode / status, positions, torques, gravity feed-forward |
177
+ | `get_end_button_state() → (code, {blue, green, alive, estop})` | blue button held / green button held / button heartbeat / E-stop mushroom |
178
+ | `get_trajectory_info() → (code, {points, duration, progress, direction, recording, playing})` | the taught trajectory stored in the board (read-only; record / play with the end-effector blue / green buttons) |
179
+ | `has_board_report` | property, a board report was received in the last 0.5 s; `False` = board firmware too old (no local reports) or board not up → the three calls above return `NO_BOARD_REPORT` |
180
+
181
+ ### Callbacks (4 pairs of `register_* / release_*`)
182
+ | Callback | Payload |
183
+ |---|---|
184
+ | `state_changed` | `{'state': ArmState}`; also fires when the user enters teach with the blue button or hits the E-stop |
185
+ | `error_warn_changed` | `{'error_code', 'warn_code'}` |
186
+ | `event` | board event `BoardEvent` (TRAJ_SAVED / REPLAY_DONE / ESTOP_ON / ESTOP_TAKEOVER / HOST_TAKEOVER …), `.text()` returns a readable description |
187
+ | `feedback` | one `JointState` per motor feedback frame, called on the receive thread; keep it fast |
188
+
189
+ ### User control callback
190
+ | API | Notes |
191
+ |---|---|
192
+ | `start_control_loop(fn, rate=None) → code` | a background thread calls `fn(arm, dt)` at `rate` Hz; inside, use `set_servo_angle_j` / `vc_set_joint_velocity`. Requires the arm to be enabled. If fn raises: the loop stops, `last_error` is set, the arm does not go limp |
193
+ | `stop_control_loop() → code` / `control_loop_active` | |
194
+
195
+ ### Cartesian (`kinematics.py` + `kin/`, PC-side, numpy only)
196
+ Pose = `[x, y, z, roll, pitch, yaw]`: **mm** in the `base_link` frame (+z up, +x forward), angles in degrees unless
197
+ `is_radian`, RPY = URDF fixed-axis XYZ (`R = Rz(yaw)·Ry(pitch)·Rx(roll)`). The pose is that of the TCP: `end_link`
198
+ (fingertip plane, +x along the gripper, fingers open along ±y) plus the optional tool offset.
199
+
200
+ | API | Notes |
201
+ |---|---|
202
+ | `get_position(is_radian=None) → (code, pose)` | FK of the latest joint feedback; stale feedback gives `FB_LOST` but still returns the value |
203
+ | `set_position(x, y, z, roll, pitch, yaw, speed=None, wait=False, timeout=None, relative=False, is_radian=None, rot_speed=None) → code` | **straight-line** TCP move (position lerp + SO(3) geodesic, minimum-jerk time scaling). `None` components keep their current value; `relative=True` adds to the current pose. `speed` in mm/s (default 50, max 500), `rot_speed` in °/s or rad/s (default 60 °/s); duration = max(dist/speed, angle/rot_speed). Needs `set_mode(0)` or `set_mode(1)`. The **whole path is solved with IK before anything is sent**: if a waypoint is unreachable, crosses a joint limit (chain limits ∩ `set_joint_limits`) or flips IK branch, nothing moves and `IK_NO_SOLUTION` / `JOINT_LIMIT` is returned with details in `last_error`. Waypoints are then streamed to the joint targets at `config.keepalive_hz` on the control-loop thread (so it cannot run together with your own `start_control_loop`). `wait=True` blocks until settled at the end point |
204
+ | `stop_position() → code` / `position_moving` | abort an in-flight `set_position` (the arm holds the last streamed waypoint) / `True` while streaming |
205
+ | `get_forward_kinematics(angles, input_is_radian=None, return_is_radian=None) → (code, pose)` | pure computation, works without a connection |
206
+ | `get_inverse_kinematics(pose, ref_angles=None, input_is_radian=None, return_is_radian=None) → (code, angles)` | damped-least-squares IK; `ref_angles` seeds the solver and picks the branch (default: current joint targets, else zero). Respects the soft limits. `IK_NO_SOLUTION (-12)` when it does not converge; `last_error` carries the residual and which joints sat on a limit |
207
+ | `set_tcp_offset(offset, is_radian=None) → code` / `get_tcp_offset(is_radian=None)` | tool offset `[x, y, z, roll, pitch, yaw]` relative to `end_link` (mm + angles); `None` resets |
208
+ | `kin_chain` | the underlying `r1_python_sdk.kin.Chain` (FK / Jacobian / limits) for your own planners |
209
+
210
+ The arm geometry is embedded in `r1_python_sdk/kin/chain.py` (transcribed from `R1_Arm_description/urdf/R1.urdf`:
211
+ joint1…joint6 + the fixed `end_joint`), so neither the URDF nor a simulator is needed at run time;
212
+ `Chain.from_urdf(path)` rebuilds it from a URDF if the hardware description changes. FK and the geometric Jacobian are
213
+ checked against MuJoCo's `mj_kinematics` / `mj_jacSite` to 1e-15 (`tests/test_kin.py` carries the reference values).
214
+ `kin.IKSolver` also offers `position_only` and `free_axis` (e.g. leave the rotation about world z free so the gripper
215
+ keeps its tilt but follows the base yaw — a much larger lateral workspace) for custom use.
216
+
217
+ Workspace notes for R1: joint5 is limited to ±90°, so a gripper pointing straight down (pitch = 90°) is only reachable
218
+ close to the base and low; joint4's range is asymmetric (−107° … +90°), so with a fixed orientation the arm reaches
219
+ further towards −y than +y. Prefer moderate pitch (45–60°) poses; when a move is rejected, `last_error` names the
220
+ joints that were on their limits.
221
+
222
+ ---
223
+
224
+ ## 3. Control-ownership model (firmware `r1_arm.c` / `r1_usb_can.c`)
225
+
226
+ ```
227
+ Board NORMAL ──PC motion frames pass straight through to CAN────────────► motors
228
+ │ ▲
229
+ blue│ │ motion_enable(True): enable/clear-error control frame or 0x7FF register write = "intent to take over"
230
+ ▼ │
231
+ TEACH ──release blue──► HOLD ──green──► REPLAY ──reaches end──► HOLD
232
+ PC blocked: all motion frames are dropped and answered with TX_FAIL (exception: HOLD lets gripper command 0x7F1 through, and it does not count as a takeover)
233
+ Mushroom at any time → ESTOP ──release──► HOLD
234
+ Pressed while the PC is in control: per axis the board does clear error → write CTRL_MODE=MIT → wait for ack → MIT pin + enable
235
+ (an axis that has not acknowledged gets no MIT frame at all: the motor only compares the low 8 bits of the ID, so an MIT frame sent before the mode switch would be decoded as another mode)
236
+ ```
237
+
238
+ - Every 40 ms the board sends a batch of **local reports** over the USB-CAN bridge (`transport.REP_LOCAL_*`: 0x20 state /
239
+ 0x22 positions / 0x23 torques / 0x24 gravity feed-forward, events 0x21, firmware version 0x25). The SDK uses them to tell
240
+ HOLD / TEACH / REPLAY / ESTOP apart, read the buttons and receive events; the blocked bit directly drives `HOST_BLOCKED`
241
+ without waiting for TX_FAILs to pile up. With old firmware that lacks these frames the SDK falls back to "6 consecutive
242
+ TX_FAILs = blocked", `get_state()` can only report `BLOCKED`, and the board APIs return `NO_BOARD_REPORT`.
243
+ - `$S/$E` lines from the USART2 log port are parsed into the same `BoardStatus/BoardEvent`; connecting it is optional.
244
+ - Motor register replies were measured to arrive on MST_ID (`0x10+id`) rather than `0x7FF`, with the same length as
245
+ feedback frames. The SDK recognises them by content (`damiao.looks_like_reg_reply`); otherwise a reply would be
246
+ mistaken for a feedback frame with pos = -12.49 rad.
247
+ - The gripper motor (CAN ID 7) belongs to the end board; frames sent directly by the PC are dropped by the bottom board.
248
+ The SDK uses the `0x7F1` command frame instead. While the board is in HOLD (after releasing the blue button or after an
249
+ E-stop reset) gripper commands still go through, so there is no need to `motion_enable` the arm first; during
250
+ ESTOP / TEACH / REPLAY they still return `HOST_BLOCKED`.
251
+
252
+ ---
253
+
254
+ ## 4. Configuration `R1Config`
255
+
256
+ ```python
257
+ from r1_python_sdk import R1API, R1Config
258
+
259
+ arm = R1API() # defaults
260
+ arm = R1API(config=R1Config(kd=[3]*6, speed_default=60)) # override in code
261
+ arm = R1API(config="my_r1.yaml") # YAML (pip install .[yaml])
262
+ ```
263
+
264
+ | Field | Default | Notes |
265
+ |---|---|---|
266
+ | `kp` / `kd` | `(120,120,120,18,18,18)` / `(5,5,5,2,2,2)` | MIT gains (kd encoding caps at 5) |
267
+ | `speed_default` | `30` °/s | used when `set_servo_angle` is called without `speed` |
268
+ | `joint_limits` | `None` | soft limits in degrees, 6 pairs `(lo, hi)` |
269
+ | `keepalive_hz` | `50` | keep-alive / servo send rate, 5~500 |
270
+ | `timeout` | `1.0` s | waiting for register replies / enable feedback |
271
+ | `feedback_stale_s` | `0.5` s | feedback staleness threshold |
272
+ | `esc_ids` | `1..6` | joint → CAN ID |
273
+
274
+ Angles in config files are always in degrees; `is_radian` only affects API arguments and return values.
275
+
276
+ ---
277
+
278
+ ## 5. Layout
279
+
280
+ ```
281
+ r1_python_sdk/
282
+ api.py R1API = Servo + Gripper + Board + Kinematics (facade; the only thing to import)
283
+ base.py connection, threads, TX/RX, state derivation, enable/mode, callbacks, start_control_loop (parent of the other mixins)
284
+ servo.py joint APIs, zeroing, registers
285
+ gripper.py gripper
286
+ board.py board state, end-effector buttons, taught-trajectory info (read-only)
287
+ kinematics.py Cartesian APIs: get_position / set_position (straight line) / FK / IK / TCP offset
288
+ kin/ numpy kinematics: transform.py (SO(3)/SE(3), RPY, min-jerk) · chain.py (R1 chain, FK, Jacobian, from_urdf) · ik.py (DLS IK)
289
+ config.py R1Config
290
+ code.py R1State / ArmState / ArmMode / R1Error / R1Warn
291
+ damiao.py Damiao frame encode/decode (pure functions)
292
+ protocol.py bottom/end board custom protocol constants, local-report decode_local_* and $S/$E parsing (mirrors firmware r1_arm.h / r1_usb_can.h / r1_grip_can.h)
293
+ transport.py DmUsbCan: USB-CAN bridge 29/16-byte serial protocol + receive thread (including local reports 0x20~0x2F)
294
+ logport.py USART2 log-port reader thread (optional)
295
+ decorator.py r1_connected / r1_ready / r1_catch
296
+ tests/ fake_board.py fake board (protocol + ideal motors + gripper heartbeat + state-machine local reports), fully offline
297
+ examples/ numbered in bring-up order: 01 read state · 02 live monitor · 03 gripper │ 04 set zero · 05 single joint
298
+ │ 06 move joints · 07 read current joints · 08 interactive joints │ 09 servo stream · 10 control loop │ 11 Cartesian (see §6)
299
+ ```
300
+
301
+ ---
302
+
303
+ ## 6. Examples `examples/`
304
+
305
+ All are single-file scripts: `python examples/<file> [COM port]`; without a COM port the bottom board is auto-detected.
306
+ The numbers are the order in which you bring up a new arm; get each stage working before moving to the next:
307
+
308
+ | Stage | Script | What it does | Enables | Arm moves | APIs used |
309
+ |---|---|---|:-:|:-:|---|
310
+ | **① Read-only, no enable** | `01_connect_and_read.py` | connect, read state / six joint angles / torques & temperatures / error codes / gripper / end-effector buttons / taught-trajectory info, then disconnect. Optional second argument is the log port. Confirms the serial port, board reports and all six feedbacks are there | no | no | `find_bottom_board_ports` `connect` `get_state` `get_servo_angle` `get_joint_states` `get_err_warn_code` `get_gripper_status` `get_end_button_state` `get_trajectory_info` `bus_stats` |
311
+ | | `02_live_monitor.py` | live monitor: refreshes one line at 10 Hz with state / six joint angles / end-effector buttons; state changes and board events print on their own lines. Press the blue button, hit the E-stop, move each axis by hand — check the state machine, buttons and angle directions | no | no | `get_state` `get_servo_angle` `get_end_button_state` `register_state_changed_callback` `register_event_callback` |
312
+ | | `03_gripper.py` | gripper: read status → fully open → fully closed → 50% → fully closed. The gripper belongs to the end board and needs no arm enable, so verify it on its own first | no | gripper only | `get_gripper_status` `open_gripper` `close_gripper` `set_gripper_position` `get_gripper_position` |
313
+ | **② Zero, one axis at a time** | `04_set_joint_zero.py` | zero calibration: disable → hold the arm at its mechanical zero → type `yes` → set zero → read back, should be near 0. Second argument limits it to one joint. First thing after assembly / motor replacement | no (disables first) | no | `motion_enable(False)` `set_joint_zero` `get_servo_angle` |
314
+ | | `05_single_joint.py` | single-joint test: dump one motor's register table (version / mode / ACC / DEC / PMAX…), enable all six and move only that joint +δ → −δ → back, print its feedback. Confirm direction and range axis by axis | yes | **yes** (one axis) | `get_servo_register` `damiao.RID_*` `set_servo_angle(servo_id=, relative=True)` `get_joint_states` |
315
+ | **③ Position mode** | `06_move_joints.py` | enable → zero → ±10° on every axis → `move_gohome` → disable; also registers state / error callbacks so you can watch them print. First time all six axes move together | yes | **yes** | `motion_enable` `set_servo_angle(wait=True)` `move_gohome` `register_state_changed_callback` `register_error_warn_changed_callback` |
316
+ | | `07_get_current_joints.py` | enable, read the current six joint angles once and print them. Handy for writing down a pose right after teaching; unlike 01 the feedback comes through the keep-alive thread rather than a 0xCC refresh | yes | no | `motion_enable` `get_servo_angle` |
317
+ | | `08_interactive_joints.py` | interactive REPL: type 6 angles to move there, `g` gripper, `mode pos\|mit` switches mode, `speed` cap, `home`, `state`, `stop` software E-stop; asks whether to disable on exit. For tuning poses and trying speed caps | yes | **yes** | `set_servo_angle` `set_servo_angle_j` `set_mode` `move_gohome` `emergency_stop` `set_gripper_position` |
318
+ | **④ Servo / streaming** | `09_servo_stream.py` | servo (MIT) mode streaming with your own `while` loop: joint1 follows a 5 s, ±10° sine; radians | yes | **yes** | `R1API(is_radian=True)` `set_mode(ArmMode.SERVO)` `set_servo_angle_j` |
319
+ | | `10_control_loop.py` | same sine as 09 (joint1 + joint2) but via `start_control_loop`: the SDK's background thread calls your callback at 100 Hz; if the callback raises, the loop stops and the arm stays up | yes | **yes** | `start_control_loop` `stop_control_loop` `set_servo_angle_j` `last_error` |
320
+ | **⑤ Cartesian** | `11_cartesian.py` | FK / IK offline first (also shows an unreachable target being rejected), then: joint move to a known pose, six 30 mm straight-line steps (−z, +x, −y, +y, −x, +z) at 30 mm/s, one absolute target with pitch 60°, back to the pose, disable | yes | **yes** | `get_forward_kinematics` `get_inverse_kinematics` `get_position` `set_position(relative=True, wait=True)` `set_position(x,y,z,roll,pitch,yaw, rot_speed=)` |
321
+
322
+ 05 / 06 / 08 / 09 / 10 / 11 really move the arm: make sure nobody is nearby and the workspace is clear before running them.
323
+ The defaults are kept slow and small (10 °/s, ±10°). 04 disables the arm, so it will drop: hold it first.
324
+
325
+ ### Mapping to the upstream reBotArm_control_py examples
326
+
327
+ R1's hardware baseline is the Seeed reBot Arm; the upstream software repository
328
+ [reBotArm_control_py](https://github.com/Seeed-Projects/reBotArm_control_py) has an `example/` folder that maps onto this SDK
329
+ as follows. Upstream drives the motors directly and ships pinocchio kinematics / dynamics; on R1 the motors sit behind the
330
+ bottom board and teaching / gravity feed-forward are done by the board, so some examples change shape; the kinematics
331
+ ones map onto the numpy `kin` module instead of pinocchio.
332
+
333
+ | Upstream | What it does | R1 SDK | Notes |
334
+ |---|---|---|---|
335
+ | `0x01damiao_test.py` | one Damiao motor: MIT / POS_VEL / VEL, enable, set zero, read state, write PID registers | `05_single_joint.py` | R1 never enables a single axis on its own (the others would drop); all six are enabled and only one is moved. Registers via `get/set_servo_register` |
336
+ | `0x01rs06_test.py` | RobStride motor | — | R1 uses Damiao only |
337
+ | `2_zero_and_read.py` | zero all joints + MIT zero-stiffness free-drive with live angle printout | `04_set_joint_zero.py` + `02_live_monitor.py` | R1 does not do "kp=kd=0 free-drive" (a loaded arm would drop); free-drive = blue button → teach mode, the board does gravity feed-forward, the PC only watches |
338
+ | `3_mit_control.py` | type angles in the terminal, MIT mode tracks them | `08_interactive_joints.py` (`mode mit`) | |
339
+ | `4_pos_vel_control.py` | type angles in the terminal, POS_VEL mode tracks them | `08_interactive_joints.py` (`mode pos`, default) | R1's `set_mode(0)` is Damiao POS_VEL |
340
+ | `5_fk_test.py` | joint angles → end-effector pose via pinocchio | `11_cartesian.py` (`get_forward_kinematics`) | numpy chain embedded in the SDK, no URDF / pinocchio needed |
341
+ | `6_ik_test.py` | end-effector pose → joint angles | `11_cartesian.py` (`get_inverse_kinematics`) | DLS IK with joint limits; `ref_angles` picks the branch |
342
+ | `7_arm_ik_control.py` | type x y z rpy, move via IK | `11_cartesian.py` (`set_position`) | R1 moves along a straight line, not a joint-space jump |
343
+ | `8_arm_traj_control.py` | Cartesian target + duration, planned trajectory | `set_position(speed=, rot_speed=)` | minimum-jerk time scaling, the path is IK-checked before it is sent |
344
+ | `9_gravity_compensation.py` | pinocchio g(q) as MIT feed-forward torque | built into the board | in teach mode the board computes gravity feed-forward itself and reports it (`BoardStatus` gravity field); `set_servo_angle_j` does not expose a tau feed-forward |
345
+ | `10_gravity_compensation_lock.py` | gravity compensation + end-effector velocity lock | built into the board | same as above; releasing the blue button = HOLD, pinned |
346
+ | `sim/fk_sim.py` `ik_sim.py` `traj_sim.py` | MeshCat visualisation of FK / IK / trajectories | — | the URDF / MJCF model lives in the R1-Arm repository (`R1_Arm_description/`); `kin.Chain` can be used offline with any viewer |
347
+
348
+ ---
349
+
350
+ ## 7. Roadmap
351
+
352
+ | Version | Scope | Depends on |
353
+ |---|---|---|
354
+ | **v1 (package version 0.1.0)** | three joint modes, gripper, state / buttons / events (USB local reports, no log cable needed), callbacks, control loop, zeroing, config; hardware E-stop → board switches to MIT and pins → HOLD semantics | bottom-board firmware with local reports + new E-stop flow |
355
+ | **v1.1 (this release, package version 0.2.0)** | Cartesian: FK/IK, straight-line `set_position` with minimum-jerk time scaling, tool offset (`kin/` numpy module, MuJoCo-verified) | numpy |
356
+ | v1.2 | joint-space synchronised interpolation for `set_servo_angle` (all axes arrive together); PC-side record / replay (record with the `feedback` callback, play with `set_servo_angle_j`) | — |
357
+ | v1.x | `get_version` firmware version, SN; gripper speed / force | firmware: query frames; end-board protocol extension |
358
+
359
+ ---
360
+
361
+ ## 8. Release notes
362
+
363
+ The version number lives in one place, `r1_python_sdk/version.py` (`__version__`); the build reads it from there
364
+ and the `arm.version` property returns it. Add a section here for every release with the user-visible changes and
365
+ the firmware it pairs with.
366
+
367
+ To release: change `version.py`, add the section below, commit, then push a tag with the same number
368
+ (`git tag v0.2.1 && git push github v0.2.1`). The tag starts `.github/workflows/publish.yml`, which runs the
369
+ offline tests, builds the wheel and the source archive, and uploads them to PyPI. Starting the same workflow by
370
+ hand from the Actions tab uploads to TestPyPI instead, as a rehearsal. A version number can be
371
+ uploaded once only, so a second try needs a new number.
372
+
373
+ ### 0.2.0 — 2026-11
374
+
375
+ - Cartesian kinematics (`kinematics.py`, new `kin/` package, numpy only): `get_position`, straight-line `set_position`
376
+ (`speed` mm/s, `rot_speed`, `relative`, `wait`, path IK-checked before sending, streamed at `keepalive_hz` in
377
+ position or servo mode), `stop_position` / `position_moving`, `get_forward_kinematics`, `get_inverse_kinematics`,
378
+ `set_tcp_offset` / `get_tcp_offset`, `kin_chain`
379
+ - New return code `IK_NO_SOLUTION (-12)`
380
+ - New dependency `numpy>=1.22`; example `11_cartesian.py`; `tests/test_kin.py` (FK / Jacobian against MuJoCo
381
+ reference values, IK round trips, `set_position` on the fake board)
382
+
383
+ ### 0.1.0 — 2026-11
384
+
385
+ First release.
386
+
387
+ - `R1API`: connection (heartbeat handshake, auto-detect VID 0483 / PID 7154), `motion_enable`, three modes, `get_state` derivation, `emergency_stop` (pins the arm, no torque drop)
388
+ - Joints: `set_servo_angle` / `set_servo_angle_j` / `vc_set_joint_velocity` / `move_gohome` / `get_servo_angle` / `get_joint_states` / soft limits / `set_joint_zero` / register read-write
389
+ - Gripper: position / open / close / status / homing / stop / `set_gripper_param` (requires end-board firmware with 0x7F1 PARAM)
390
+ - Board read-only: `get_board_state` / `get_end_button_state` / `get_trajectory_info` / `get_board_version`
391
+ - Four callback pairs; `start_control_loop`; `R1Config` (Python / dict / YAML)
392
+ - 42 offline tests (`tests/fake_board.py`); examples 01–10 numbered in bring-up order (§6)
393
+ - Firmware pairing: the bottom board must send USB local reports 0x20–0x25 and implement the new E-stop flow. With older firmware (e.g. `934f767`) that has no local reports, `get_board_state / get_end_button_state / get_trajectory_info` return `NO_BOARD_REPORT` (the log port can fill in), and `get_state()` can only report `BLOCKED` from consecutive TX_FAILs
394
+
395
+ ---
396
+
397
+ ## 9. License
398
+
399
+ Apache License 2.0. The full text is in [LICENSE](LICENSE).