cristhian
8a7bfb02e0
The axis and button indices in mapping.py are SDL's documented layout rather than an observed one, and until now the only way to find a pad that numbers things differently was to watch a real arm move the wrong way. `dora-teleop-probe` prints the raw axes, the buttons it sees and the velocity that would be sent, live, with no dataflow and no arm — it cannot move anything. It goes through the same Gamepad and velocity() the node runs, so what it prints is what the arm would get; that is the whole reason it is worth having, and the reason it must not grow its own copy of the mapping. Every axis is listed, including ones the layout does not use, because an axis marked unused that moves when a stick is pushed is exactly the finding this is for. The centred bar makes a worn stick that does not return to zero obvious.
193 lines
8.9 KiB
Markdown
193 lines
8.9 KiB
Markdown
# dora-teleop
|
|
|
|
A dora-rs node that hands a robot arm to a human. Pick up a gamepad and move the arm, or
|
|
open a browser and move it from there — one of the two at a time, decided here.
|
|
|
|
It drives [`dora-ulite6`](https://gitea.liria.cl/liria/dora-ulite6) through that node's
|
|
ordinary `jog` and `request` ports, and talks to the browser through
|
|
[`dora-websocket-transceiver`](https://gitea.liria.cl/liria/dora-websocket-transceiver).
|
|
It contains no web server and no robot driver: it is the piece in the middle that decides
|
|
what the arm should be doing, and that decision is the only thing it owns.
|
|
|
|
## The gamepad
|
|
|
|
Analog and blended — several axes at once, and how fast depends on how far you push. That
|
|
is the whole reason a pad beats the web console's four-sector dial pad, which can only ask
|
|
for one axis at a time at one fixed speed.
|
|
|
|
| Control | Does | Units |
|
|
|-------------|-------------------------------------------|-------|
|
|
| Left stick | Move along X (up/down) and Y (left/right) | mm/s |
|
|
| Triggers | Lift on the right, lower on the left | mm/s |
|
|
| Right stick | Roll (left/right) and pitch (up/down) | deg/s |
|
|
| Bumpers | Yaw, left and right | deg/s |
|
|
| A | Close the tool | — |
|
|
| B | Open the tool | — |
|
|
| X | Clear a controller error | — |
|
|
| Y | Toggle freedrive | — |
|
|
| Back | **E-STOP** | — |
|
|
|
|
Up on the stick sends the arm away from you, along **+X** in the robot's base frame —
|
|
the same convention the web console's dial uses, so the two agree.
|
|
|
|
Indices are SDL's, which is what most Xbox- and PlayStation-style pads report. A pad that
|
|
disagrees is a change to `Layout` in `dora_teleop/mapping.py` rather than a new
|
|
environment variable: an index nobody can verify from outside is worse than a line of code
|
|
somebody can read.
|
|
|
|
`home` is deliberately **not** on the pad. It is a large unattended motion and belongs
|
|
behind a deliberate click, not a thumb resting on a face button.
|
|
|
|
### Checking your pad
|
|
|
|
```bash
|
|
uv run dora-teleop-probe
|
|
```
|
|
|
|
Prints the raw axes, the buttons it sees, and the velocity this node would send — live,
|
|
with no dataflow and no arm. **It cannot move anything.** There is no dora node and no
|
|
connection to the robot; it only reads.
|
|
|
|
```text
|
|
axes (6 reported)
|
|
0 left stick X +0.600 ----------|-----#----
|
|
1 left stick Y -0.800 --#-------|----------
|
|
2 left trigger -1.000 #---------|----------
|
|
...
|
|
buttons (6 reported)
|
|
5:yaw right
|
|
|
|
velocity this would send to the arm
|
|
vx +38.89 mm/s forward / back <--
|
|
vy +23.53 mm/s left / right <--
|
|
vz +20.39 mm/s up / down <--
|
|
wz +30.00 deg/s yaw <--
|
|
|
|
moving: yes
|
|
```
|
|
|
|
Run this before trusting the table above. The indices are SDL's documented layout, not
|
|
observed ones, and a pad that numbers its axes differently is much better found here than
|
|
by watching an arm move the wrong way. Two things to look for:
|
|
|
|
- **Every axis is listed, including ones the layout does not use** — an axis marked
|
|
`unused` that moves when you push a stick means the layout needs changing.
|
|
- **A bar that does not sit centred with the stick released** is a worn pad announcing
|
|
itself, and a reason to raise `DEADZONE`.
|
|
|
|
It goes through the same `Gamepad` and `velocity()` the node runs, so what it prints is
|
|
what the arm would be sent.
|
|
|
|
## The lease
|
|
|
|
Two sources, one arm. Whoever holds the lease drives; the other is ignored.
|
|
|
|
- The **gamepad takes it implicitly**, the first time a stick moves, if nobody holds it.
|
|
Nobody should have to reach for a browser to use the thing in their hands.
|
|
- It **gives it back** after `GAMEPAD_IDLE_RELEASE_S` untouched, so a pad left on the
|
|
bench does not lock the browser out forever.
|
|
- The **browser takes it explicitly**, with the console's TAKE CONTROL button, and gives
|
|
it back with RELEASE. It can preempt a held arm, because an operator who can see the arm
|
|
is better placed than this code to decide they should have it.
|
|
- **E-STOP is never gated.** From either source, held lease or not. Somebody reaching for
|
|
the stop is the one moment when asking who owns the arm is the wrong question.
|
|
|
|
**The lease binds only what goes through this node.** `dora-ulite6` has no idea it exists.
|
|
Another node publishing `request` will preempt an operator mid-motion and nothing here can
|
|
stop it — if that matters for your dataflow, do not wire one.
|
|
|
|
## The deadman
|
|
|
|
An arm under a velocity command keeps moving until told otherwise, so the question is
|
|
never whether to start but whether anything has happened that means it must stop. Three
|
|
layers, outermost last:
|
|
|
|
1. **Re-send every tick** (50 ms) while a source is driving.
|
|
2. **This node's watchdog** (`JOG_TTL_S`, 0.4 s) stops the arm when the owner goes quiet —
|
|
and stops it *immediately*, without waiting out the timer, when the gamepad is unplugged
|
|
or the last browser disconnects. An unplugged pad is not a centred pad.
|
|
3. **The arm's own expiry** (`VELOCITY_COMMAND_TTL_S` in `dora-ulite6`, 0.5 s), enforced by
|
|
the controller whether or not this process is alive.
|
|
|
|
Keep them in that order. If this node's timer is longer than the controller's, the backstop
|
|
fires before the thing it is backing up.
|
|
|
|
On shutdown the node sends one all-zero velocity before exiting. A motion lives in the
|
|
controller, not in this process.
|
|
|
|
The stop is sent **once**, not every tick. A stream of zeroes would keep `dora-ulite6`
|
|
believing a jog is live and hold `robot_state` at `moving` forever.
|
|
|
|
## Ports
|
|
|
|
| Direction | Name | Description |
|
|
|-----------|----------------|------------------------------------------------------|
|
|
| in | `tick` | 50 ms — re-send, deadman, telemetry |
|
|
| in | `ui_command` | One console message, from the bridge's `data_out` |
|
|
| in | `clients` | Connect/disconnect from the bridge — the web deadman |
|
|
| in | `response` | An answer from the arm |
|
|
| in | `motion_state` | How a motion ended |
|
|
| in | `robot_state` | The arm's own state |
|
|
| in | `tcp_pose` | Tool-tip pose, six float32, mm and degrees |
|
|
| in | `joint_pose` | Joint angles, six float32, degrees |
|
|
| out | `jog` | `{velocity: [vx, vy, vz, wx, wy, wz]}`, mm/s + deg/s |
|
|
| out | `request` | A service call, `request_id` in the metadata |
|
|
| out | `ui_state` | The console's telemetry snapshot, as JSON |
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|--------------------------|---------|--------------------------------------------------------|
|
|
| `SPEED_MM_S` | `60.0` | Translation speed at full deflection |
|
|
| `SPEED_DEG_S` | `30.0` | Rotation speed at full deflection |
|
|
| `DEADZONE` | `0.12` | Stick travel near centre to ignore |
|
|
| `EXPO` | `0.4` | How much of the curve is cubic; 0 is linear |
|
|
| `JOYSTICK_INDEX` | `0` | Which pad to open |
|
|
| `JOG_TTL_S` | `0.4` | Owner silence before the arm is stopped |
|
|
| `GAMEPAD_IDLE_RELEASE_S` | `2.0` | Untouched pad before it hands the arm back |
|
|
| `STATE_POLL_S` | `0.5` | How often to ask the arm what telemetry does not carry |
|
|
|
|
A value that cannot be read, a `DEADZONE` outside the stick or an `EXPO` off the curve
|
|
stops the node at startup rather than the first time somebody picks up the pad.
|
|
|
|
## Usage
|
|
|
|
See `dataflow.yml` for the whole stack wired together. The short version:
|
|
|
|
```yaml
|
|
- id: teleop
|
|
git: ssh://git@gitea.liria.cl:5001/liria/dora-teleop.git
|
|
tag: v0.1.0
|
|
build: pip install .
|
|
path: dora-teleop
|
|
inputs:
|
|
tick: dora/timer/millis/50
|
|
ui_command: ws-transceiver/data_out
|
|
clients: ws-transceiver/clients
|
|
response: ulite6/response
|
|
motion_state: ulite6/motion_state
|
|
robot_state: ulite6/robot_state
|
|
tcp_pose: ulite6/tcp_pose
|
|
joint_pose: ulite6/joint_pose
|
|
outputs: [jog, request, ui_state]
|
|
```
|
|
|
|
```bash
|
|
dora run dataflow.yml --uv
|
|
```
|
|
|
|
**Requirements:** dora 1.0+ (verified with `dora-cli 1.0.1`), Python 3.11+, `uv`, and a
|
|
gamepad if you want one — the node starts without and says so.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
uv sync --group dev
|
|
uv run pytest # 76 tests, no gamepad, arm, browser or daemon needed
|
|
uv run ruff check .
|
|
uv run ruff format --check .
|
|
```
|
|
|
|
`dora_teleop/gamepad.py` is the only file that touches pygame, and the only one that
|
|
cannot be tested without hardware. Everything else sees a plain `Sample`.
|