feetech-cli 0.1.0__tar.gz

feetech_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iori Yanokura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

feetech_cli-0.1.0/PKG-INFO

@@ -0,0 +1,412 @@
+Metadata-Version: 2.4
+Name: feetech-cli
+Version: 0.1.0
+Summary: Command line tool to inspect and configure FEETECH STS/SMS/SCS serial bus servos
+Author-email: Iori Yanokura <ab.ioryz@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/iory/feetech-cli
+Project-URL: Issues, https://github.com/iory/feetech-cli/issues
+Keywords: feetech,sts3215,servo,robotics,serial
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyserial>=3.5
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: readchar>=4.0.5
+Dynamic: license-file
+
+# feetech-cli
+
+Command line tool to inspect and configure FEETECH STS/SMS/SCS serial bus
+servos (STS3215 and friends) — change servo ids, bus speeds, modes and limits,
+or watch a live status screen.
+
+## Install
+
+```console
+$ pip install feetech-cli
+```
+
+or, to keep it in its own environment with the `feetech` command on your path:
+
+```console
+$ uv tool install feetech-cli
+```
+
+The package is also a Python library: `from feetech_cli import FeetechServoController`.
+
+## Quick start
+
+Plug in a USB servo adapter, give the servo its own power supply, then:
+
+```console
+$ feetech ports                    # which serial ports look like a servo bus
+$ feetech scan                     # which servos answer (ids 1-16 by default)
+$ feetech scan --all-baudrates     # ...when you do not know the bus speed
+$ feetech                          # interactive status screen
+```
+
+The port and the bus speed are auto detected. Pass `--port` and `--baudrate`
+to pin them.
+
+No hardware handy? `--simulate` runs the whole interface against an in-process
+servo bus (ids 1, 2 and 3), which is useful for trying the key bindings out:
+
+```console
+$ feetech --simulate
+```
+
+It only ever engages when you ask for it. A missing adapter or a silent bus
+reports itself as such; it never quietly falls back to the simulator. The
+screen header reads `--- SIMULATED SERVOS, NO HARDWARE ---` for as long as it
+is running, so a simulation is never mistaken for a real bus.
+
+## Changing a servo id
+
+The usual case — one servo on the bus, currently id 1, that should become id 5:
+
+```console
+$ feetech set-id 1 5
+Change servo 1 to id 5? This writes the servo EEPROM. [y/N] y
+Servo 1 is now id 5.
+```
+
+`set-id` refuses an id that another servo on the bus already answers to,
+switches torque off first, unlocks the EEPROM, writes, locks it again, and
+then pings the new id to confirm the change actually took. Add `-y` to skip
+the prompt in scripts.
+
+The same thing in the interactive screen: put the cursor on `Servo ID`, pick
+the new id with the left/right arrows, press Enter. The chosen id is the one
+shown in green.
+
+| key | action |
+|---|---|
+| Up / Down | move between `Servo ID`, `Goal Position`, `Goal Velocity`, `Acceleration` |
+| Left / Right | change **the selected row only** — see below |
+| Enter | on `Servo ID`, write the highlighted id to the servo |
+| `n` / `p` | switch to the next / previous servo on the bus |
+| `r` | rescan the bus |
+| `t` | toggle torque |
+| `z` | move to 0 degrees |
+| `0` | call the pose the servo is in **right now** 0 degrees (asks first, writes EEPROM) |
+| `m` | cycle position / wheel / PWM / step mode |
+| `q` | quit |
+
+```
+--- FEETECH Servo Status ---
+Bus: /dev/ttyUSB0 @ 1.00Mbps   Servos: 1 4
+
+>> Servo ID: 1  ->  new id: [1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16]
+   Goal Position: 2048 (+0.0 deg)
+   Goal Velocity: 0
+   Acceleration: 0
+
+    Present Position: 2048 (+0.0 deg)
+    Voltage: 12.1 V
+    Temperature: 35 C
+    Torque: Disabled
+    Operating Mode: position (0)
+    Baud Rate: 1.00Mbps
+    EEPROM: locked
+```
+
+The arrows do something different on every row, so the screen names the
+selected row and what they will do to it:
+
+```
+>> Servo ID: 1  ->  new id: [1 2 3 4 5 ...]
+   Goal Position: 614 (-126.0 deg)
+   ...
+Now on Servo ID: Left/Right pick the id, Enter writes it to the servo
+```
+
+The cursor starts on `Servo ID`, where the arrows pick an id rather than move
+the horn. Press Down to reach `Goal Position` before expecting the servo to
+move.
+
+## Swapping servos while it runs
+
+The interactive screen does not need restarting when you change servos. When
+the bus goes quiet it switches to a waiting screen and keeps looking:
+
+```
+--- FEETECH Servo Status ---
+
+No servo is answering.
+
+Plug a servo in and it will be picked up automatically.
+Retrying once a second. Also worth checking:
+  - the USB adapter is still connected
+  - the servo has its own power supply, USB alone is not enough
+  - the servo id is between 1 and 16 (widen with --min-id / --max-id)
+
+'r' retry now, 'q' quit
+```
+
+The id range is rescanned each time, so the replacement is found even when it
+answers to a different id. Unplugging the USB adapter itself is handled too:
+the port is closed and reopened rather than just rescanned.
+
+It also starts this way. `feetech` with nothing on the bus opens the waiting
+screen instead of exiting, so you can start the tool first and connect a servo
+afterwards. The one shot commands (`scan`, `info`, `set-id`, ...) still fail
+straight away, since they have nothing to wait for.
+
+## Torque
+
+**A position command energises the servo by itself.** Measured on an STS3215:
+with `torque_enable` explicitly set to 0, writing `goal_position` took it back
+to 1 and the horn moved. Writes to `lock`, `homing_offset` and `acceleration`
+did not do this, so it is specific to the position command.
+
+So the arrow keys and `feetech move` always move the servo, even from a limp
+standstill, and the joint stops being back drivable at that moment:
+
+```
+>> Goal Position: 2216 (+14.8 deg)  (arrows will energise the servo)
+   Present Position: 2216 (+14.8 deg)
+   Torque: Enabled
+```
+
+To make a joint free to move by hand, switch torque **off** and leave it off:
+press `t`, or run `feetech torque 1 off`. While it is off, `Present Position`
+tracks the joint as you move it. Send any position command and it stiffens
+again.
+
+Pressing `t` to energise holds the position the horn is actually in, not the
+goal last commanded. Otherwise the servo would snap to a stale goal the moment
+it came on, which on an assembled robot can break something.
+
+## When a servo will not move
+
+`selftest` is the check to run first. It verifies the settings that keep a
+servo still, then commands a short series of moves with torque on and reads
+back where the horn actually ended up, so "the tool is not sending anything"
+is separated from "the servo is not acting on it":
+
+```console
+$ feetech selftest 1
+Settings that would stop it moving:
+  [ok  ] operating mode is position: 0 (position)
+  [ok  ] torque limit above zero: 1000
+  ...
+Moves, starting from 996:
+   target   before  reached   error   secs  result
+     1046      996     1044      -2   0.44  moved and reached the target
+     ...
+PASS: 5 of 5 commanded moves reached their target.
+```
+
+Moves stay within `--span` counts of where the servo started (100 by default,
+about 9 degrees) and the servo is put back where it was found, with torque
+restored to whatever it was.
+
+## Zeroing a joint
+
+Two different things, both available:
+
+**Move the joint to 0 degrees** — the servo travels to encoder count 2048:
+
+```console
+$ feetech move 1 --degree 0
+```
+
+or press `z` in the interactive screen.
+
+**Call the joint's current pose 0 degrees** — nothing moves, the servo just
+starts reporting the pose it is already in as 0. This is how a joint is zeroed
+after assembly:
+
+```console
+$ feetech set-zero 1
+Servo 1 currently reports 311 (-152.7 deg).
+Call this pose 2048 (+0.0 deg)? This writes homing_offset to the servo EEPROM.
+The servo will not move. [y/N] y
+Servo 1 now reports 2048 (+0.0 deg) in the same pose.
+homing_offset = -1652
+```
+
+It writes the `homing_offset` register, where
+`present_position = (raw_encoder - homing_offset) mod 4096` (verified on an
+STS3215). Torque is left as it was found, and the goal is re-pointed at the
+new reading so re-energising does not make the joint jump.
+
+The wrap matters the second time a joint is zeroed. A servo that already
+carries an offset reports a position that has crossed the 0/4095 boundary —
+raw 628 with an offset of 904 reads 3820, not -276 — so the reading is
+brought back into range before the new offset is worked out. Skipping that
+asks the servo for an offset the register cannot hold and refuses a zeroing
+that would have fitted.
+
+In the interactive screen this is the `0` key. It asks before writing:
+
+```
+Call this pose (2134, +7.6 deg) 0 degrees? This writes homing_offset to the
+servo EEPROM. The servo will not move. Press 'y' to confirm, any other key
+to cancel.
+```
+
+To name the current pose something other than zero:
+
+```console
+$ feetech set-zero 1 --degree 90
+$ feetech set-zero 1 --position 1024
+```
+
+The offset register holds ±2047 counts, so the pose has to be within about
+180 degrees of the target; `set-zero` refuses rather than writing a wrapped
+value.
+
+## Other commands
+
+```console
+$ feetech info 1                   # dump the control table
+$ feetech info 1 --all             # ...every register, not just the useful ones
+$ feetech set-baud 1 115200        # change the bus speed and reconnect
+$ feetech move 1 --degree 90       # command a position
+$ feetech move 1 --position 3072   # ...in encoder counts
+$ feetech torque 1 off             # let the horn move freely
+$ feetech mode 1 wheel             # continuous rotation
+$ feetech read 1 present_load
+$ feetech write 1 acceleration 20
+$ feetech registers                # names and addresses of the control table
+$ feetech factory-reset 1
+```
+
+## More than one servo on the bus
+
+Everything acts on one servo at a time. `scan` lists them all; every other
+command works on the id it is given.
+
+```console
+$ feetech scan
+Found 3 servo(s) on /dev/ttyUSB0 at 1.00Mbps:
+  id   1  model   777  position  2048 (+0.0 deg)  12.1V  35C
+  id   2  model   777  position  1024 (-90.0 deg)  12.1V  36C
+  id   3  model   777  position  3072 (+90.0 deg)  12.0V  35C
+```
+
+`info`, `set-zero` and `selftest` allow the id to be left out, but only when
+exactly one servo answers. With several on the bus they name them and stop
+rather than picking one:
+
+```console
+$ feetech info
+several servos answered (1, 2, 3), name the one to use
+```
+
+The rest — `move`, `torque`, `mode`, `read`, `write`, `set-baud`,
+`factory-reset` — always want the id. `set-id` additionally refuses to create
+a collision:
+
+```console
+$ feetech set-id 1 2
+id 2 is already used by another servo on this bus
+```
+
+There is no `--all` flag and no broadcast command. An EEPROM write that lands
+on every joint of an assembled robot is not something a mistyped command
+should be able to do. `FeetechServoController.sync_write_positions()` does
+exist, and commands several servos in one packet, but it is a Python API
+rather than a subcommand.
+
+The interactive screen lists every servo found, with the selected one in
+cyan:
+
+```
+Bus: /dev/ttyUSB0 @ 1.00Mbps   Servos: 1 2 3
+```
+
+`n` and `p` move to the next and previous servo, `r` rescans. It opens on the
+lowest id. Only the selected servo is read each frame, so the refresh rate
+does not drop as servos are added to the bus, and every key — the arrows,
+`t`, `z`, `m`, `0` — applies to that servo alone. A rescan keeps you on the
+servo you were watching when it is still there, and falls back to the lowest
+id when it is not.
+
+## Servo id range
+
+Ids 1-16 are scanned by default, which covers a typical arm or hand. FEETECH
+servos accept ids up to 253; widen the range when you need to:
+
+```console
+$ feetech --max-id 253 scan
+```
+
+`--min-id` and `--max-id` also set the ids offered by the interactive screen.
+
+## SCS series
+
+The older SCS servos store 16 bit registers big endian. Pass `--scs` to talk
+to them.
+
+## Safety notes
+
+- Writing the EEPROM (`set-id`, `set-baud`, `mode`, `factory-reset`) asks for
+  confirmation unless `-y` is given, and refuses to run unattended without it.
+- `set-id` and `set-baud` verify the change by re-addressing the servo
+  afterwards; they raise instead of reporting success if the servo does not
+  answer at its new identity.
+- If a servo goes missing after a speed change, find it again with
+  `feetech scan --all-baudrates`.
+
+## Development
+
+```console
+$ uv sync --all-groups
+$ uv run pytest
+$ uv run ruff check .
+```
+
+The test suite runs against the simulated servo bus in
+`feetech_cli/simulator.py`, so it needs no hardware. It covers the packet
+layer, the EEPROM lock dance, id and baud rate changes, and the CLI.
+
+`tests/test_terminal.py` additionally drives the interactive screen through a
+real pty, sending real arrow key and Enter sequences, which is the only way to
+cover `readchar` and the escape handling for real.
+
+## Protocol reference
+
+FEETECH servos speak a Dynamixel-1.0 style protocol:
+
+```
+instruction : 0xFF 0xFF ID LENGTH INSTRUCTION PARAM... CHECKSUM
+status      : 0xFF 0xFF ID LENGTH ERROR       PARAM... CHECKSUM
+```
+
+`LENGTH` is `len(params) + 2` and `CHECKSUM` is
+`~(ID + LENGTH + INSTRUCTION + sum(params)) & 0xFF`.
+
+Baud rate register values:
+
+| value | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
+|---|---|---|---|---|---|---|---|---|
+| bps | 1000000 | 500000 | 250000 | 128000 | 115200 | 76800 | 57600 | 38400 |
+
+Note that [LeRobot's table][lerobot] lists values 5-7 as 57600/38400/19200
+instead. The table above is the one used here, and matches three independent
+implementations.
+
+Sources:
+
+- STS3215 register reference: https://github.com/commanderfun/STS3215/blob/main/REGISTER_REFERENCE.md
+- Hello Robot Stretch driver (baud table): https://github.com/hello-robot/stretch4_body/blob/master/stretch4_body/core/feetech/feetech_SM_servo.py
+- AkariGroup feetech_setup (baud table): https://github.com/AkariGroup/feetech_setup/blob/main/set_baudrate.py
+- LeRobot control table and sign-magnitude encodings: https://github.com/huggingface/lerobot/blob/main/src/lerobot/motors/feetech/tables.py
+- FEETECH start tutorial: https://www.feetechrc.com/Data/feetechrc/upload/file/20201127/start%20%20tutorial201015.pdf
+
+[lerobot]: https://github.com/huggingface/lerobot/blob/main/src/lerobot/motors/feetech/tables.py
+
+## License
+
+MIT