Skip to content

armgit / moss

Public Imported from GitHub
0

MOSS: a small, mostly 3D-printed litter-picking rover. Cleaner streets, one maker at a time.

Python

Unify dual-shoulder CAD assembly and controller setup guide (#11)

metr0x14a67fcc5311
diff --git a/README.md b/README.md
index 1181825..82f9da5 100644
--- a/README.md
+++ b/README.md
@@ -40,7 +40,7 @@ I pick up litter by hand on my walks. MOSS is the robot I want next to me doing
## News
-- 27 October 2026: **[SO-101 dual-servo shoulder R2](hardware/mechanical/dual-shoulder-r2/)** — common housing and wider upper arm, with editable STEP files, two printable STLs and assembly instructions.
+- 27 October 2026: **[SO-101 dual-servo shoulder R2: complete upgrade guide](hardware/mechanical/dual-shoulder-r2/)** — editable CAD, two printable parts, screws, assembly, paired-servo setup and testing in one place.
- 24 October 2026: **BOM and print plates updated.** Hoco HB1 four-port hub, GameSir Nova 2 Lite controller, all 38 spacers on one plate, and one tensioner-slider reference (print four). [Updated package](https://github.com/metrox-eth/moss/releases/download/v0.6-r92/MOSS_R92_Mechanical_20261024.zip) · [Print plates](https://www.showrobotics.ai/moss/build/print-plates.html).
- 18 October 2026: **Ready-to-print plates are available.** [H2S: one-piece hull and cover](https://github.com/metrox-eth/moss/releases/download/v0.6-r92/MOSS_V06_R92_H2S_Print_Plates.3mf) or [P1 / P2: split hull and cover](https://github.com/metrox-eth/moss/releases/download/v0.6-r92/MOSS_V06_R92_256mm_Split_Print_Plates.3mf). The [updated package](https://github.com/metrox-eth/moss/releases/download/v0.6-r92/MOSS_R92_Mechanical_20261018.zip) includes both Jetson retaining tabs, grouped STLs with quantities, and both 3MF projects. [Choose your plates](https://www.showrobotics.ai/moss/build/print-plates.html).
diff --git a/docs/arm.md b/docs/arm.md
index 60d6bae..6f3524c 100644
--- a/docs/arm.md
+++ b/docs/arm.md
@@ -1,6 +1,6 @@
# The arm
-**Dual-servo shoulder upgrade:** [R2 CAD, printable parts and assembly guide](../hardware/mechanical/dual-shoulder-r2/). The six-servo table below describes the original arm; the additional shoulder servo needs paired-servo control.
+**Dual-servo shoulder upgrade:** [Complete guide: R2 CAD, printing, assembly, paired-servo setup and testing](../hardware/mechanical/dual-shoulder-r2/). The six-servo table below describes the original arm; the upgrade adds a seventh servo.
MOSS carries an SO-101 arm: five joints and a gripper, six Feetech servos
on one bus (protocol 0, 1 Mbps, the port in `MOSS_ARM_PORT`).
diff --git a/hardware/mechanical/dual-shoulder-r2/README.md b/hardware/mechanical/dual-shoulder-r2/README.md
index 45e7609..1bc0535 100644
--- a/hardware/mechanical/dual-shoulder-r2/README.md
+++ b/hardware/mechanical/dual-shoulder-r2/README.md
@@ -2,6 +2,8 @@
Two shoulder servos sit back to back in one printed housing. A wider upper-arm fork connects their two outward-facing horns in direct drive. The original base pivot, shoulder height and elbow interface are retained.
+**Start here for the complete upgrade: print the two parts, assemble the shoulder, then set up and test the paired servos below.**
+
**[Open the assembled CAD](CAD/MOSS_Dual_Shoulder_R2_Z_Up.step) · [Printable STLs](STL/) · [Individual STEP files](CAD/)**
![The R2 dual shoulder fitted to MOSS, rendered from CAD](images/moss-dual-shoulder-r2.png)
@@ -37,13 +39,79 @@ Reuse the base-pivot and elbow fixings from the original arm. The CAD was dimens
![Exploded view of the common housing, two reference servos and upper arm](images/exploded.png)
-## Paired-servo control
+## Set up the two servos
+
+**Use the MOSS [`dimos-standalone` branch](https://github.com/metrox-eth/moss/tree/dimos-standalone).** It contains the paired-servo controller and setup tools published on 27 October 2026 (`d65dd6d`), together with this CAD package. The pairing runs on the rover's computer; there is no separate servo firmware image to download for this upgrade. For a new software installation, follow [Install on the robot](https://github.com/metrox-eth/moss/blob/dimos-standalone/Software.md#install-on-the-robot) first.
+
+The existing shoulder keeps **ID 2**. The added servo uses **ID 7**. Because their shafts face opposite ways, the controller mirrors the second servo's movement automatically.
+
+1. **Give the added servo its own ID.** Connect only that servo to the bus while changing its ID to 7. Power off before reconnecting the complete arm; otherwise a new servo with the factory ID can share an ID with an existing one.
+2. **Set the shared zero.** With torque off, rest the assembled arm at the shoulder's rear mechanical stop. Use this arm's measured shoulder limits and calibration file. The setup tool aligns the two readings, mirrors the limits and saves the pair's calibration. Do not copy another robot's homing offsets.
+3. **Check the pair at rest.** Run the stationary test below, without a payload. It enables holding torque and shows both loads. Persistent opposing effort through the fork means the alignment needs correcting before trying a lift.
+4. **Try an unloaded movement, then a load.** Use poses checked for your assembled arm and return to its supported, folded position after the test.
+
+<details>
+<summary><strong>Setup commands</strong></summary>
+
+Run these from the root of the configured MOSS checkout, using its `.venv`. Stop other arm-control processes first. Load the robot's settings into this shell so `MOSS_ARM_PORT` points to its servo adapter and `MOSS_ARM_CALIB`, if used, points to its calibration file. Without `MOSS_ARM_CALIB`, the tools use `config/arm_calibration.json`; back that file up before zeroing.
+
+With only the new servo connected, find its current ID:
+
+```sh
+.venv/bin/python tools/moss_bus_scan.py
+```
+
+If the scan reports ID 1, change it to 7. If it reports another ID, replace `1` with that ID:
+
+```sh
+.venv/bin/python tools/moss_arm_twin_setup.py rename 1 7
+```
+
+Reconnect the complete arm with power off. After restoring bus power, leave torque off and put the shoulder at its rear stop. With the existing shoulder's measured `range_min` and `range_max` already recorded in this arm's calibration file:
+
+```sh
+.venv/bin/python tools/moss_arm_twin_setup.py zero --joint-id 2 --twin-id 7
+```
+
+This writes servo settings and the calibration file. It uses the shoulder's existing minimum as the stop reading; if that calibration is missing, complete the [arm calibration](https://github.com/metrox-eth/moss/blob/dimos-standalone/docs/arm.md#calibration) first. Do not run `zero` with guessed limits.
+
+Then check the pair without commanding a new pose:
+
+```sh
+.venv/bin/python tools/moss_arm_twin_setup.py rest --seconds 30
+```
+
+Opposite-signed load readings are expected because the servos count in opposite directions. Sustained substantial loads with the same sign indicate that they are fighting. The test leaves torque on if the arm is not folded; support and fold it before switching power off.
+
+</details>
+
+<details>
+<summary><strong>Optional load test and technical references</strong></summary>
+
+The load-test tool moves out through a pose sequence, holds, then returns. First inspect the supplied sequence without opening the servo bus:
+
+```sh
+.venv/bin/python tools/moss_arm_load_test.py --poses config/arm_load_cantilever.json --dry-run
+```
+
+The supplied poses describe the development rover. Check the positions and clearances against your own calibration before using them on hardware. Once checked, start from the recorded folded pose and run without a payload first:
+
+```sh
+.venv/bin/python tools/moss_arm_load_test.py --poses config/arm_load_cantilever.json --hold 30 --label no_load
+```
+
+It records the shoulder, added servo, elbow and wrist loads, current, voltage and temperature in `~/.local/state/moss/arm_load/`. Keep any payload test results with the mass used. A failed clearance check needs investigation before running the sequence.
-The two output shafts face opposite directions. Their relative movements must be mirrored, with a calibrated zero for each servo, so the pair does not fight through the fork.
+The implementation stays in separate files so it can be maintained and reused. You can follow this guide without reading them:
-The [arm software documentation](../../../docs/arm.md) describes the existing MOSS arm stack. Its six-servo configuration is the original single-shoulder arrangement; the second shoulder servo requires paired-servo control. This folder supplies the mechanical design, not a replacement firmware image.
+| File | Purpose |
+|---|---|
+| [Arm documentation](https://github.com/metrox-eth/moss/blob/dimos-standalone/docs/arm.md#a-joint-with-two-servos) | Calibration and how mirrored movement works |
+| [Setup tool](https://github.com/metrox-eth/moss/blob/dimos-standalone/tools/moss_arm_twin_setup.py) | Servo ID, shared zero and stationary test |
+| [Load-test tool](https://github.com/metrox-eth/moss/blob/dimos-standalone/tools/moss_arm_load_test.py) | Unloaded and loaded measurements |
+| [Feetech adapter](https://github.com/metrox-eth/moss/blob/dimos-standalone/moss_dimos/arm_feetech.py) | Drives the pair together during normal operation |
-For the load and synchronization study, see the separate [dual-shoulder simulation proposal](https://github.com/metrox-eth/moss/pull/9).
+</details>
## Size and status
diff --git a/hardware/mechanical/dual-shoulder-r2/manifest.json b/hardware/mechanical/dual-shoulder-r2/manifest.json
index 07b10b7..56c8768 100644
--- a/hardware/mechanical/dual-shoulder-r2/manifest.json
+++ b/hardware/mechanical/dual-shoulder-r2/manifest.json
@@ -46,8 +46,8 @@
},
{
"path": "README.md",
- "bytes": 5137,
- "sha256": "0fc431b99a5d538cf2d763f5ac1867d2bbc43dbfb11fb12ac6c5f218a521f4b6"
+ "bytes": 9741,
+ "sha256": "dc9f1c38de1fcfc5bc0ca729d3acbcb5ff19a01e47c758c7ab7829ab338ef500"
},
{
"path": "STL/01_Shoulder_Monobloc_R2.stl",