Package Guide

This section is a narrative, developer-oriented reference for every package in the software/src/ colcon workspace. It explains what each package does, how its nodes and modules interact, and where to look in the source.

For machine-generated launch/parameter tables (always in sync with the repo), see Package Reference. For the Python API, see Python API Reference.

Packages

• bringup — Launch Orchestration
  • Role in the stack
  • Launch arguments
  • Sim vs hardware branching
  • Configuration files
  • Interactions with other packages
  • Typical launch commands
• control — Tension Controllers
  • Architecture
  • Executables
  • ROS 2 interfaces
  • Control loop timing
  • State machine
  • Admittance controller (Julie)
  • Force-feedback controller (Chaoyi)
  • Configuration loading
  • Interactions
  • Future: 2-DOF control
  • Related
• sensors — Line Tension Sensing
  • Design principle: one node, two backends
  • Node: load_cell_node
  • ROS 2 interfaces
  • Signal processing pipeline
  • Interactions
  • Physical layer diagrams
  • Launch
• planning — Virtual Fish (Simulation Only)
  • Design: indirect coupling
  • Node: fish_agent
  • URDF / MJCF requirements
  • Interactions
  • Tuning tips
  • Launch
• diagnostics — Recording & Bring-Up Tests
  • Components overview
  • recorder — Run capture & visualization
  • hardware_check — Open-loop self-test
  • Launch
  • Related
• description — Robot Model Assets
  • Asset inventory
  • Kinematic tree (both modes)
  • The use_sim xacro switch
  • MJCF simulation scene
  • ros2_control joint ↔ Dynamixel mapping
  • Interactions
  • Related
• interfaces — Custom Messages
  • Messages
  • Topic usage
  • Design rationale
  • Build dependency graph
  • Related standard messages

Package map

The workspace is organised into seven packages. Five are application or asset packages; two (bringup, interfaces) are shared infrastructure.

        flowchart LR
    classDef cmake fill:#fff8e1,stroke:#f57f17,stroke-width:1.5px
    classDef python fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px
    classDef external fill:#eceff1,stroke:#607d8b,stroke-width:1.5px

    DESC["description<br/>URDF · MJCF"]:::cmake
    BR["bringup<br/>robot.launch.py"]:::cmake
    IFACE["interfaces<br/>FishingTension"]:::cmake

    CTRL["control"]:::python
    SENS["sensors"]:::python
    PLAN["planning"]:::python
    DIAG["diagnostics"]:::python

    CM["ros2_control host"]:::external
    RSP["robot_state_publisher"]:::external

    DESC --> BR
    BR --> CTRL & SENS & PLAN & DIAG
    BR --> CM & RSP
    CTRL & SENS & DIAG --> IFACE
    SENS -->|tension| CTRL
    PLAN -->|fish effort| CM
    CTRL -->|trajectory| CM
    

Quick reference

Package	Build	Runs on HW?	Primary responsibility
bringup — Launch Orchestration	ament_cmake	Yes	Top-level launch, use_sim switch, controller spawners, delegation to app packages.
control — Tension Controllers	ament_python	Yes	Tension-to-motion controllers (Julie admittance, Chaoyi force feedback).
sensors — Line Tension Sensing	ament_python	Yes	Publishes FishingTension from HX711 (HW) or MuJoCo line model (sim).
planning — Virtual Fish (Simulation Only)	ament_python	Sim only	Virtual fish disturbance via fish_agent.
diagnostics — Recording & Bring-Up Tests	ament_python	Yes†	Run recorder (sim) and hardware bring-up self-test (both modes).
description — Robot Model Assets	ament_cmake	Yes	URDF/xacro, MJCF, STL meshes; defines ros2_control hardware plugin.
interfaces — Custom Messages	ament_cmake	Yes	Custom FishingTension.msg shared across control, sensors, diagnostics.

† recorder is launched only when record:=true (typically sim). hardware_check runs in both modes when hardware_check:=true.

Cross-package data flow

Every tension-control run follows the same closed loop regardless of mode:

        flowchart LR
    classDef sense fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px
    classDef decide fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px
    classDef act fill:#fce4ec,stroke:#c62828,stroke-width:1.5px

    DIST["disturbance"]:::act
    ARM["2-DOF arm"]:::act
    LC["load_cell_node"]:::sense
    CTRL["tension ctrl<br/>MONITOR→HOOK→REG"]:::decide
    PTC["pos_traj_controller"]:::act

    DIST --> ARM
    ARM --> LC
    LC -->|/fishing_arm/tension| CTRL
    CTRL -->|/joint_trajectory| PTC --> ARM
    ARM -.->|/joint_states| CTRL
    

The controller state machine is identical in both controller implementations:

        stateDiagram-v2
    direction LR

    [*] --> MONITOR: t = 0

    MONITOR --> HOOK_SET: t ≥ bite_time<br/>hold q_init
    HOOK_SET --> REGULATE: hook done<br/>sweep → q_hook
    REGULATE --> ESTOP: |F| > F_limit
    ESTOP --> REGULATE: |F| safe

    note right of REGULATE
        Track 3.5 N
        Admittance or
        force-feedback
    end note
    

See ROS 2 Communication Graph for mode-specific ROS 2 graphs and topic tables.