feetech-cli 0.1.0__tar.gz → 0.1.2__tar.gz

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feetech-cli
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -31,14 +31,17 @@ or watch a live status screen.
 
 ## Install
 
+With [uv](https://docs.astral.sh/uv/), which installs the `feetech` command in its
+own environment and on your path:
+
 ```console
-$ pip install feetech-cli
+$ uv tool install feetech-cli
 ```
 
-or, to keep it in its own environment with the `feetech` command on your path:
+or with pip:
 
 ```console
-$ uv tool install feetech-cli
+$ pip install feetech-cli
 ```
 
 The package is also a Python library: `from feetech_cli import FeetechServoController`.
@@ -71,13 +74,64 @@ 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:
+New STS3215 servos all leave the factory as **id 1 at 1 Mbps**. Every servo on
+a bus needs its own id, so a robot with several servos starts with giving each
+one a different id — **one servo at a time**.
 
-```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.
-```
+### Walkthrough: numbering a batch of new servos
+
+1. **Connect exactly one servo** to the USB adapter, and power the adapter
+   from its own supply. USB alone does not power a servo.
+
+2. Check that it answers, and at which id:
+
+   ```console
+   $ feetech scan
+   Found 1 servo(s) on /dev/ttyUSB0 at 1.00Mbps:
+     id   1  model   777  position  2048 (+0.0 deg)  12.1V  35C
+   ```
+
+3. Give it its new id. Numbering three servos 1, 2 and 3, the first one can
+   keep id 1; the second becomes 2:
+
+   ```console
+   $ feetech set-id 1 2
+   Change servo 1 to id 2? This writes the servo EEPROM. [y/N] y
+   Servo 1 is now id 2.
+   ```
+
+   The id is stored in EEPROM, so it survives a power cycle.
+
+4. **Label the servo** with its new id (a piece of masking tape is enough).
+   Once they are mixed up, the only way to tell them apart again is to connect
+   them one by one.
+
+5. Unplug it, connect the next new servo, and repeat from step 2 with the
+   next id (`feetech set-id 1 3` for the third).
+
+6. With every servo numbered, daisy-chain them all and check the whole set
+   answers:
+
+   ```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  2048 (+0.0 deg)  12.1V  35C
+     id   3  model   777  position  2048 (+0.0 deg)  12.1V  35C
+   ```
+
+**Why one at a time.** Two new servos on the same bus both answer to id 1.
+Their replies collide, and a write addressed to id 1 reaches both of them:
+`set-id 1 2` would renumber both servos to 2, and the check that follows
+would find "a servo at id 2" and report success. `set-id` cannot tell one
+servo at an id from two, so keeping a single unnumbered servo on the bus is
+up to you.
+
+If `scan` finds nothing, the servo may have been set to another bus speed
+before. `feetech scan --all-baudrates` tries every speed. Servos with an id
+above 16 need `--max-id 253`.
+
+### What set-id does
 
 `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
@@ -404,6 +458,8 @@ Sources:
 - 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
+- Factory default id 1: https://www.waveshare.com/wiki/ST3215_Servo ; id 1 and 1 Mbps: the STS3215 register reference above
+- LeRobot SO-101 assembly, numbering the motors one at a time: https://huggingface.co/docs/lerobot/main/en/assemble_so101
 
 [lerobot]: https://github.com/huggingface/lerobot/blob/main/src/lerobot/motors/feetech/tables.py
 

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/README.md

@@ -6,14 +6,17 @@ or watch a live status screen.
 
 ## Install
 
+With [uv](https://docs.astral.sh/uv/), which installs the `feetech` command in its
+own environment and on your path:
+
 ```console
-$ pip install feetech-cli
+$ uv tool install feetech-cli
 ```
 
-or, to keep it in its own environment with the `feetech` command on your path:
+or with pip:
 
 ```console
-$ uv tool install feetech-cli
+$ pip install feetech-cli
 ```
 
 The package is also a Python library: `from feetech_cli import FeetechServoController`.
@@ -46,13 +49,64 @@ 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:
+New STS3215 servos all leave the factory as **id 1 at 1 Mbps**. Every servo on
+a bus needs its own id, so a robot with several servos starts with giving each
+one a different id — **one servo at a time**.
 
-```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.
-```
+### Walkthrough: numbering a batch of new servos
+
+1. **Connect exactly one servo** to the USB adapter, and power the adapter
+   from its own supply. USB alone does not power a servo.
+
+2. Check that it answers, and at which id:
+
+   ```console
+   $ feetech scan
+   Found 1 servo(s) on /dev/ttyUSB0 at 1.00Mbps:
+     id   1  model   777  position  2048 (+0.0 deg)  12.1V  35C
+   ```
+
+3. Give it its new id. Numbering three servos 1, 2 and 3, the first one can
+   keep id 1; the second becomes 2:
+
+   ```console
+   $ feetech set-id 1 2
+   Change servo 1 to id 2? This writes the servo EEPROM. [y/N] y
+   Servo 1 is now id 2.
+   ```
+
+   The id is stored in EEPROM, so it survives a power cycle.
+
+4. **Label the servo** with its new id (a piece of masking tape is enough).
+   Once they are mixed up, the only way to tell them apart again is to connect
+   them one by one.
+
+5. Unplug it, connect the next new servo, and repeat from step 2 with the
+   next id (`feetech set-id 1 3` for the third).
+
+6. With every servo numbered, daisy-chain them all and check the whole set
+   answers:
+
+   ```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  2048 (+0.0 deg)  12.1V  35C
+     id   3  model   777  position  2048 (+0.0 deg)  12.1V  35C
+   ```
+
+**Why one at a time.** Two new servos on the same bus both answer to id 1.
+Their replies collide, and a write addressed to id 1 reaches both of them:
+`set-id 1 2` would renumber both servos to 2, and the check that follows
+would find "a servo at id 2" and report success. `set-id` cannot tell one
+servo at an id from two, so keeping a single unnumbered servo on the bus is
+up to you.
+
+If `scan` finds nothing, the servo may have been set to another bus speed
+before. `feetech scan --all-baudrates` tries every speed. Servos with an id
+above 16 need `--max-id 253`.
+
+### What set-id does
 
 `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
@@ -379,6 +433,8 @@ Sources:
 - 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
+- Factory default id 1: https://www.waveshare.com/wiki/ST3215_Servo ; id 1 and 1 Mbps: the STS3215 register reference above
+- LeRobot SO-101 assembly, numbering the motors one at a time: https://huggingface.co/docs/lerobot/main/en/assemble_so101
 
 [lerobot]: https://github.com/huggingface/lerobot/blob/main/src/lerobot/motors/feetech/tables.py
 

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/feetech_cli/__init__.py

@@ -7,7 +7,7 @@ from feetech_cli.protocol import FeetechStatusError
 from feetech_cli.protocol import FeetechTimeoutError
 from feetech_cli.protocol import PacketHandler
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
     "FeetechServoController",

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/feetech_cli/cli.py

@@ -20,6 +20,7 @@ from feetech_cli.registers import INFO_REGISTERS
 from feetech_cli.registers import OPERATING_MODES
 from feetech_cli.registers import degree_to_position
 from feetech_cli.registers import format_baud
+from feetech_cli.registers import format_current
 from feetech_cli.registers import position_to_degree
 from feetech_cli.tui import ServoTui
 
@@ -411,13 +412,16 @@ def command_info(args, controller):
         value = values[name]
         print(
             "  {:<{width}}  addr {:>3}  {}".format(
-                name, register.address, _annotate(name, value), width=width
+                name,
+                register.address,
+                _annotate(name, value, values),
+                width=width,
             )
         )
     return 0
 
 
-def _annotate(name, value):
+def _annotate(name, value, context=None):
     """Render a register value with a unit or label where one applies.
 
     Parameters
@@ -426,6 +430,9 @@ def _annotate(name, value):
         Register name.
     value : int or None
         Register value.
+    context : dict or None, optional
+        Other register values of the same servo. ``present_current`` uses
+        ``model_number`` and ``present_load`` from it.
 
     Returns
     -------
@@ -450,7 +457,10 @@ def _annotate(name, value):
     if name == "present_load":
         return f"{value} ({value / 10.0:+.1f} %)"
     if name == "present_current":
-        return f"{value} ({value * 6.5:.0f} mA)"
+        context = context or {}
+        return format_current(
+            value, context.get("model_number"), context.get("present_load")
+        )
     if name == "torque_enable":
         return "{} ({})".format(value, "on" if value else "off")
     if name == "lock":
@@ -532,7 +542,10 @@ def command_read(args, controller):
         Process exit status.
     """
     value = controller.read_register(args.id, args.register)
-    print(f"{args.register} = {_annotate(args.register, value)}")
+    context = None
+    if args.register == "present_current":
+        context = controller.dump(args.id, ["model_number", "present_load"])
+    print(f"{args.register} = {_annotate(args.register, value, context)}")
     return 0
 
 

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/feetech_cli/registers.py

@@ -126,7 +126,9 @@ CONTROL_TABLE = {
     "async_write_flag": _sram(64, 1, writable=False),
     "status": _sram(65, 1, writable=False),
     "moving": _sram(66, 1, writable=False),
-    "present_current": _sram(69, 2, writable=False),
+    # Bit 15 carries the sign, as in FEETECH's SMS_STS::ReadCurrent:
+    # https://github.com/adityakamath/SCServo_Linux/blob/main/src/SMS_STS.cpp
+    "present_current": _sram(69, 2, writable=False, sign_bit=15),
 }
 
 #: Register value 0-7 written to ``baud_rate`` and the bus speed it selects.
@@ -161,6 +163,26 @@ OPERATING_MODES = {
     3: "step",
 }
 
+#: ``(milliamps per count, what is measured)`` of ``present_current``, by
+#: ``model_number``. Only models whose scale is backed by a document are
+#: listed; for any other model the count is shown without a conversion rather
+#: than with a guessed one.
+#:
+#: - 777 (STS3215): 6.5 mA,
+#:   https://www.mantech.co.za/datasheets/products/sts3215-200620a-1.pdf
+#: - 4618 (HLS series, seen on an HLS3960M): 6.5 mA of motor *phase* current,
+#:   not supply current. At a low PWM duty the phase current is far larger
+#:   than what the power supply delivers. Source is a third party transcript
+#:   of the HLS memory table, not a FEETECH document:
+#:   https://wiki.aifitlab.com/feetech-servo-motor-docs/feetech-hls-servo-memory-table-analysis
+CURRENT_MA_PER_COUNT = {
+    777: (6.5, "supply"),
+    4618: (6.5, "phase"),
+}
+
+#: ``present_load`` count that means 100 % PWM duty (the unit is 0.1 %).
+LOAD_FULL_SCALE = 1000
+
 #: Encoder counts per full turn for the STS/SMS series.
 RESOLUTION = 4096
 
@@ -265,3 +287,41 @@ def format_baud(baud):
     if baud >= 1000:
         return f"{baud / 1000:.0f}k"
     return str(baud)
+
+
+def format_current(current, model, load=None):
+    """Render a ``present_current`` reading, in mA when the scale is known.
+
+    For a model that reports motor phase current, the current drawn from the
+    power supply is also estimated as ``|phase current| * |PWM duty|``, the
+    duty being ``present_load`` in 0.1 % steps. The estimate ignores driver
+    losses and the servo's own idle draw, so it is a rough figure only.
+
+    Parameters
+    ----------
+    current : int
+        Signed ``present_current`` count.
+    model : int or None
+        ``model_number`` of the servo, ``None`` if it could not be read.
+    load : int or None, optional
+        Signed ``present_load`` count, needed for the supply estimate.
+
+    Returns
+    -------
+    str
+        For example ``"-147 (-956 mA)"``, ``"-506 (-3289 mA phase, ~987 mA
+        supply est.)"`` for a model that reports motor phase current, or
+        ``"-147 (mA scale unknown for model 1234)"`` when
+        :data:`CURRENT_MA_PER_COUNT` has no entry.
+    """
+    entry = CURRENT_MA_PER_COUNT.get(model)
+    if entry is None:
+        return f"{current} (mA scale unknown for model {model})"
+    scale, kind = entry
+    milliamps = current * scale
+    if kind != "phase":
+        return f"{current} ({milliamps:.0f} mA)"
+    if load is None:
+        return f"{current} ({milliamps:.0f} mA phase)"
+    supply = abs(milliamps) * abs(load) / LOAD_FULL_SCALE
+    return f"{current} ({milliamps:.0f} mA phase, ~{supply:.0f} mA supply est.)"

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/feetech_cli/tui.py

@@ -16,6 +16,7 @@ from feetech_cli.registers import CENTER_POSITION
 from feetech_cli.registers import OPERATING_MODES
 from feetech_cli.registers import RESOLUTION
 from feetech_cli.registers import format_baud
+from feetech_cli.registers import format_current
 from feetech_cli.registers import position_to_degree
 
 #: Encoder counts moved per arrow key press, about five degrees.
@@ -69,6 +70,8 @@ STATUS_REGISTERS = [
     "present_voltage",
     "present_temperature",
     "present_current",
+    # Only needed to pick the mA scale for present_current.
+    "model_number",
     "torque_enable",
     "operating_mode",
     "moving",
@@ -603,7 +606,9 @@ class ServoTui:
             current = values.get("present_current")
             if current is None:
                 return "no data"
-            return f"{current} ({current * 6.5:.0f} mA)"
+            return format_current(
+                current, values.get("model_number"), values.get("present_load")
+            )
         if row == "Torque":
             torque = values.get("torque_enable")
             if torque is None:

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/feetech_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: feetech-cli
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -31,14 +31,17 @@ or watch a live status screen.
 
 ## Install
 
+With [uv](https://docs.astral.sh/uv/), which installs the `feetech` command in its
+own environment and on your path:
+
 ```console
-$ pip install feetech-cli
+$ uv tool install feetech-cli
 ```
 
-or, to keep it in its own environment with the `feetech` command on your path:
+or with pip:
 
 ```console
-$ uv tool install feetech-cli
+$ pip install feetech-cli
 ```
 
 The package is also a Python library: `from feetech_cli import FeetechServoController`.
@@ -71,13 +74,64 @@ 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:
+New STS3215 servos all leave the factory as **id 1 at 1 Mbps**. Every servo on
+a bus needs its own id, so a robot with several servos starts with giving each
+one a different id — **one servo at a time**.
 
-```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.
-```
+### Walkthrough: numbering a batch of new servos
+
+1. **Connect exactly one servo** to the USB adapter, and power the adapter
+   from its own supply. USB alone does not power a servo.
+
+2. Check that it answers, and at which id:
+
+   ```console
+   $ feetech scan
+   Found 1 servo(s) on /dev/ttyUSB0 at 1.00Mbps:
+     id   1  model   777  position  2048 (+0.0 deg)  12.1V  35C
+   ```
+
+3. Give it its new id. Numbering three servos 1, 2 and 3, the first one can
+   keep id 1; the second becomes 2:
+
+   ```console
+   $ feetech set-id 1 2
+   Change servo 1 to id 2? This writes the servo EEPROM. [y/N] y
+   Servo 1 is now id 2.
+   ```
+
+   The id is stored in EEPROM, so it survives a power cycle.
+
+4. **Label the servo** with its new id (a piece of masking tape is enough).
+   Once they are mixed up, the only way to tell them apart again is to connect
+   them one by one.
+
+5. Unplug it, connect the next new servo, and repeat from step 2 with the
+   next id (`feetech set-id 1 3` for the third).
+
+6. With every servo numbered, daisy-chain them all and check the whole set
+   answers:
+
+   ```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  2048 (+0.0 deg)  12.1V  35C
+     id   3  model   777  position  2048 (+0.0 deg)  12.1V  35C
+   ```
+
+**Why one at a time.** Two new servos on the same bus both answer to id 1.
+Their replies collide, and a write addressed to id 1 reaches both of them:
+`set-id 1 2` would renumber both servos to 2, and the check that follows
+would find "a servo at id 2" and report success. `set-id` cannot tell one
+servo at an id from two, so keeping a single unnumbered servo on the bus is
+up to you.
+
+If `scan` finds nothing, the servo may have been set to another bus speed
+before. `feetech scan --all-baudrates` tries every speed. Servos with an id
+above 16 need `--max-id 253`.
+
+### What set-id does
 
 `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
@@ -404,6 +458,8 @@ Sources:
 - 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
+- Factory default id 1: https://www.waveshare.com/wiki/ST3215_Servo ; id 1 and 1 Mbps: the STS3215 register reference above
+- LeRobot SO-101 assembly, numbering the motors one at a time: https://huggingface.co/docs/lerobot/main/en/assemble_so101
 
 [lerobot]: https://github.com/huggingface/lerobot/blob/main/src/lerobot/motors/feetech/tables.py
 

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/feetech_cli.egg-info/SOURCES.txt

@@ -17,5 +17,6 @@ feetech_cli.egg-info/top_level.txt
 tests/test_cli.py
 tests/test_controller.py
 tests/test_protocol.py
+tests/test_registers.py
 tests/test_terminal.py
 tests/test_tui.py

{feetech_cli-0.1.0 → feetech_cli-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "feetech-cli"
-version = "0.1.0"
+version = "0.1.2"
 description = "Command line tool to inspect and configure FEETECH STS/SMS/SCS serial bus servos"
 readme = "README.md"
 requires-python = ">=3.9"

feetech_cli-0.1.2/tests/test_registers.py

@@ -0,0 +1,29 @@
+"""Tests for register decoding and rendering."""
+
+from feetech_cli.protocol import from_sign_magnitude
+from feetech_cli.registers import CONTROL_TABLE
+from feetech_cli.registers import format_current
+
+
+def test_present_current_decodes_bit_15_as_sign():
+    # Raw 0x8164 read from a holding servo: magnitude 356, negative.
+    sign_bit = CONTROL_TABLE["present_current"].sign_bit
+    assert from_sign_magnitude(0x8164, sign_bit) == -356
+
+
+def test_format_current_converts_known_model():
+    assert format_current(-147, 777) == "-147 (-956 mA)"
+
+
+def test_format_current_labels_phase_current():
+    assert format_current(-147, 4618) == "-147 (-956 mA phase)"
+
+
+def test_format_current_estimates_supply_from_pwm_duty():
+    # 3289 mA phase at 30 % duty draws roughly 987 mA from the supply.
+    expected = "-506 (-3289 mA phase, ~987 mA supply est.)"
+    assert format_current(-506, 4618, load=-300) == expected
+
+
+def test_format_current_leaves_unknown_model_unconverted():
+    assert format_current(-147, 1234) == "-147 (mA scale unknown for model 1234)"