r1-python-sdk 0.2.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.
- r1_python_sdk/__init__.py +22 -0
- r1_python_sdk/api.py +40 -0
- r1_python_sdk/base.py +1075 -0
- r1_python_sdk/board.py +71 -0
- r1_python_sdk/code.py +161 -0
- r1_python_sdk/config.py +124 -0
- r1_python_sdk/damiao.py +239 -0
- r1_python_sdk/decorator.py +57 -0
- r1_python_sdk/gripper.py +125 -0
- r1_python_sdk/kin/__init__.py +19 -0
- r1_python_sdk/kin/chain.py +149 -0
- r1_python_sdk/kin/ik.py +180 -0
- r1_python_sdk/kin/transform.py +133 -0
- r1_python_sdk/kinematics.py +342 -0
- r1_python_sdk/logport.py +105 -0
- r1_python_sdk/protocol.py +354 -0
- r1_python_sdk/servo.py +287 -0
- r1_python_sdk/transport.py +246 -0
- r1_python_sdk/utils.py +50 -0
- r1_python_sdk/version.py +1 -0
- r1_python_sdk-0.2.0.dist-info/METADATA +399 -0
- r1_python_sdk-0.2.0.dist-info/RECORD +24 -0
- r1_python_sdk-0.2.0.dist-info/WHEEL +4 -0
- r1_python_sdk-0.2.0.dist-info/licenses/LICENSE +202 -0
|
@@ -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).
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
r1_python_sdk/__init__.py,sha256=Cq4qUGWLuyt5XgMXk_RzAICxhx56q_E8JEjbFok8_xA,709
|
|
2
|
+
r1_python_sdk/api.py,sha256=UlH0zldubI2xMZ0cZx5RNqROdK7EhAObXrAPprP6uao,1719
|
|
3
|
+
r1_python_sdk/base.py,sha256=CgeiVN6uZxLMgJDsfrWcQT0-osWsHEFwC_i9do6gCP4,45368
|
|
4
|
+
r1_python_sdk/board.py,sha256=i-hOmUxNIdDpeOoR31LXI62CsRibb7A5aDDjVT--fo4,3261
|
|
5
|
+
r1_python_sdk/code.py,sha256=Ei2ZGlXBjrKjgb3vfd2aIdKD373u16-6sKHFUhrTj7Y,6312
|
|
6
|
+
r1_python_sdk/config.py,sha256=a82mBU4vYqD4t2PzGcWu4Qr6Ei3-CNIsxVq28Qqjeb4,5260
|
|
7
|
+
r1_python_sdk/damiao.py,sha256=zI2z-7U58X5HKZdTjhKCmIBvTsFBWRqHWGN7wHYdWSI,7377
|
|
8
|
+
r1_python_sdk/decorator.py,sha256=8XFWWWQQK2iZtbzW_-JwzpuDfQ-Z1WdmyEsj2NH1Mts,1932
|
|
9
|
+
r1_python_sdk/gripper.py,sha256=DoTWMfOPZ2KK7tYslLm5zGHag4AQW3NLWeRbN7jVibU,5997
|
|
10
|
+
r1_python_sdk/kinematics.py,sha256=GKiigqh9FLwqUDWFLv0ZW68NCRCGd4v7Y0fgOyhgXyQ,16657
|
|
11
|
+
r1_python_sdk/logport.py,sha256=kQsByBZg_sJ21M28vftvteNL8SyJdOd_QerST8ZJb8s,3544
|
|
12
|
+
r1_python_sdk/protocol.py,sha256=FQbx702NFAYMsqwMPWeEXGKLfFw_MPLYJiZmr3oV2UA,13050
|
|
13
|
+
r1_python_sdk/servo.py,sha256=DKwmefIzRGb-6dEZn905WVuNWu5zxeocENrUkXyLGB0,13831
|
|
14
|
+
r1_python_sdk/transport.py,sha256=eynSdRVpuSTPtmcKaiaKEGb3Ak52ZdmewRukJhLxkZI,8154
|
|
15
|
+
r1_python_sdk/utils.py,sha256=F9fS6MtVat0orZ_kiCL6Bng7jBtVs_xnIhMtUPAZj74,1614
|
|
16
|
+
r1_python_sdk/version.py,sha256=Zn1KFblwuFHiDRdRAiRnDBRkbPttWh44jKa5zG2ov0E,22
|
|
17
|
+
r1_python_sdk/kin/__init__.py,sha256=h_h5hnwp4IPAhPsT92wCHKibWUqfpYtuQXdyH8JGdJE,929
|
|
18
|
+
r1_python_sdk/kin/chain.py,sha256=7JIv9ymb7aM8NGgceewXNvznU-V5TF7oD8qUiOI0rHM,7244
|
|
19
|
+
r1_python_sdk/kin/ik.py,sha256=PVqa0wvy47Wp0DcpksbPa5gDQ23CjXihlZJz3W-1VqU,8202
|
|
20
|
+
r1_python_sdk/kin/transform.py,sha256=FXFZbtRzOht6K4zJy60pjoULgOqX9fYTuvT8yzUE3p0,3971
|
|
21
|
+
r1_python_sdk-0.2.0.dist-info/METADATA,sha256=P4sq6du2PKFThy2dIjIzws8O5jVFAWGiNaS5nRJ6bAQ,33906
|
|
22
|
+
r1_python_sdk-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
23
|
+
r1_python_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
24
|
+
r1_python_sdk-0.2.0.dist-info/RECORD,,
|
|
@@ -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.
|