[Release v1.2.0] linearbot

[nu-jliu]

Summary

Release v1.2.0 — mirror of the dev/linear-bot branch (dev/JH_i2rt-linear-bot/) into the public repo. Adds flow_base configurability + 3-D odometry, meter-calibrated linear rail, two new flow_base teleop examples, Pi GPIO dependency, gamepad raw-data API + Y/yaw axis fix, a dm_driver auto-start fix, a CLI-flag flip on flow_base_controller.py so gamepad and linear-rail are now opt-in, and gamepad desktop launcher variants with all launcher flags aligned to the new opt-in CLI.

Note on version pin: pyproject.toml ships with version = "1.1.2" (matching dev) rather than 1.2.0. The PR title reflects the intended release name; bump the pin before merge if you want the package metadata to match.

BREAKING API CHANGE — 3-D odometry. FlowBase odometry translation vectors widen from 2-D [x, y] to 3-D [x, y, z]. Callers that unpack odo["position"]["translation"] or odo["velocity"]["{world,body}"]["translation"] as a 2-tuple must accept a third component. z is 0.0 on a bare Vehicle and the linear-rail height (m) on LinearRailVehicle; vz is in m/s and is identical in world and body frames (the rail axis is vertical).

Changes

• pyproject.toml: add rpi-lgpio>=0.6 as a runtime dependency, PEP-508-gated to Pi-like Linux (sys_platform == 'linux' and platform_machine in {aarch64, armv7l, armv6l}) so it only installs on Raspberry Pi targets that need it for linear-rail GPIO (brake + limit switches). rpi-lgpio is a drop-in for from RPi import GPIO that works on Pi 5 (BCM2712); legacy RPi.GPIO fails with cannot determine peripheral soc base addr on Pi 5. Version pin stays at 1.1.2.
• i2rt/flow_base/flow_base_controller.py: make control-loop frequency configurable per instance; fix inverted Y/yaw axes; expose per-motor wheel speeds; pretty-print get_observation output; widen Vehicle.get_odometry() translations to 3-D (z=0); LinearRailVehicle.get_odometry() substitutes the calibrated rail height/rate for z/vz; add total_stroke_m kwarg (default 1.0 m). CLI break: --no-linear-rail (opt-out, default on) is replaced by --linear-rail (opt-in, default off); new --gamepad flag (opt-in, default off) gates pygame/joystick init. Existing invocations that relied on the prior defaults must add --linear-rail and/or --gamepad explicitly.
• i2rt/flow_base/linear_rail_controller.py: rewrite startup calibration to drive top → bottom, capture motor angle at each limit, derive meters_per_rad = total_stroke_m / (theta_upper - theta_lower), then zero the encoder at the lower limit so encoder 0 corresponds to bottom of travel. get_linear_rail_state() now exposes calibrated linear position/velocity in meters alongside motor radians.
• i2rt/flow_base/flow_base_client.py: switch CLI to tyro; add _format_rail_state() helper; CLI output now formats 3-D translations ([px, py, pz]) and the new rail-state dict layout (motor rad + linear m).
• i2rt/flow_base/README.md: document 3-D translation semantics (z from rail height) and the expanded get_linear_rail_state() output (motor + linear position/velocity, limit-switch flags).
• i2rt/motor_drivers/dm_driver.py: start the control-loop thread on the auto-start path so newly constructed drivers actually run.
• i2rt/utils/gamepad_utils.py: add Gamepad.get_raw_data() (used by the debug __main__); negate teleop Y/yaw axes.
• devices/FlowBase.desktop, devices/LinearRailVehicle.desktop: point desktop launchers at the venv python instead of the system one; align Exec flags with the new opt-in CLI (FlowBase drops the removed --no-linear-rail, LinearRailVehicle now passes --linear-rail explicitly).
• devices/FlowBaseGamepad.desktop, devices/LinearRailVehicleGamepad.desktop: NEW — gamepad-teleop variants of the two launchers, passing --gamepad (plus --linear-rail on the rail variant).
• devices/setup_flow_desktop.sh: install the two new gamepad launchers alongside the existing ones (copy to ~/Desktop, mark trusted, chmod +x); add colored [INFO]/[SUCCESS]/[WARNING] progress output and auto-install lxterminal (required by all launchers) when missing, continuing gracefully if the install fails.
• examples/drive_flow_base_viser/: NEW — keyboard- and viser-GUI-slider-driven flow_base teleop with odometry visualization (now also renders base_frame at the actual rail z), gated behind an enable checkbox.
• examples/plot_flow_base_rerun/: NEW — rerun-based observation monitor for flow_base (logs pose/z, vel_world/vz, vel_body/vz, and a 3-D trajectory).

Test Plan

• In a fresh checkout of release/v1.2.0, run uv sync --all-packages and confirm the lockfile resolves cleanly on x86_64 (rpi-lgpio must be skipped via the PEP 508 marker).
• On a Raspberry Pi (aarch64, including Pi 5 BCM2712), repeat uv sync --all-packages and confirm rpi-lgpio is installed and from RPi import GPIO imports without raising.
• python -c "import i2rt; print(i2rt.__file__)" imports without error.
• Call FlowBaseClient.get_odometry() against a base-only flow_base and confirm position.translation is a length-3 array with z == 0.0, and velocity.world.translation / velocity.body.translation are also length-3. (Verifies the 3-D odometry break.)
• On a station with a flow_base + linear rail, restart flow_base_controller with --linear-rail, wait for the top-then-bottom calibration to finish, then call get_linear_rail_state() and confirm both position.motor (rad) and position.linear (m) are populated. Confirm get_odometry() reports a non-zero z matching the rail height after driving the rail.
• On a station with a flow_base, run python examples/drive_flow_base_viser/drive_flow_base_viser.py, open the viser URL, tick the enable checkbox, drag the sliders, and confirm the base drives in the expected direction (Y and yaw are no longer inverted). With a linear rail enabled, confirm base_frame lifts vertically in the 3-D view as the rail moves.
• On the same station, run python examples/plot_flow_base_rerun/plot_flow_base_rerun.py and confirm rerun renders pose/z, vel_world/vz, and the 3-D trajectory in addition to per-motor wheel speeds.
• On a station with a linear rail, run the linear-rail home routine and verify the encoder reads 0 at the lower-limit position; verify the upper-limit motor angle and meters_per_rad are logged at startup.
• On a station with a YAM/DM motor chain, instantiate a DMDriver with auto-start enabled and confirm motor messages flow without manually calling start().
• Plug in a gamepad on any station, run python -m i2rt.utils.gamepad_utils, and confirm get_raw_data() output appears alongside the standard button readings.
• On a flow_base station, run python -m i2rt.flow_base.flow_base_controller with no flags and confirm the linear rail stays disabled and no joystick init is attempted; then re-run with --linear-rail --gamepad and confirm both subsystems come up. (Verifies the CLI-flag flip.)
• On a flow_base station, run bash devices/setup_flow_desktop.sh and confirm all four launchers land on the desktop (FlowBase, FlowBaseGamepad, LinearRailVehicle, LinearRailVehicleGamepad); double-click each and confirm the controller starts with the matching subsystems (rail only on the LinearRail variants, joystick init only on the Gamepad variants).
• Skim the diff for any secret/local file that should not be public (.env, credentials, station-specific config) — confirm none made it in.

🤖 Generated with Claude Code