pb_teleop_twist_joy_node（手柄輸入與可替換控制入口）

1.pb_teleop_twist_joy_node（手柄輸入與可替換控制入口）

1.1.是否必須使用北極熊的手柄節點

可以不用，可以自己寫。對當前工程，更建議保留現成joy／joy_linux手柄驅動，繼續完善已有joy_bringup的映射與控制邏輯；北極熊節點保留作原工程復現參考。 自主導航需要目標請求和速度執行鏈，不要求必須通過本手柄節點發目標。

本節點提供兩種不同功能：manual_control把搖桿映射成底盤速度，auto_control把搖桿映射成相對機械人的導航目標；兩種模式都會把雲台搖桿積分成關節目標位置。當前配置為auto_control，因此底盤x、y的2.5／4.0在這條分支是目標偏移米數，不是實車速度上限。上游模式説明與源碼

上游README本身説明代碼較亂、不建議繼續基於它擴展，且README更新不及時；這可作為維護選擇的參考，具體功能仍以源碼為準。官方teleop_twist_joy提供Joy→Twist映射，同樣依賴joy處理輸入重發，不自帶整套機械人控制模式管理。北極熊README、官方Humble説明

1.1.1.當前“不使用北極熊節點”的註釋與啓動不一致

reality參數塊前面已經寫了“我們用的自己的teleop_twist_joy_node，不使用北極熊的節點”。但當前實物和仿真主入口仍無條件添加joy_teleop_launch；這個launch實際啓動joy的joy_node和pb_teleop_twist_joy_node，安裝副本也相同。註釋沒有停掉節點，本參數塊不能僅憑註釋標成已廢棄。

對應位置：實物入口、仿真入口、實際啓動節點。這裏只核對文件，沒有據此聲稱當前進程一定在運行。

自己的joy_bringup是另一套獨立啓動入口，不讀取本pb參數分組。若確定替換，應同時調整啓動入口、參數與速度出口；僅刪YAML塊會讓仍被啓動的pb節點改用源碼默認值，不等於禁用它。

北极熊当前auto_control：
    joy → 摇杆x/y × scale → 机器人参考系中的偏移点
        → TF换到map → NavigateToPose → Nav2规划／控制 → 速度链
    joy → 云台角速度 × ROS dt积分 → cmd_gimbal_joint目标位置

自己的joy_bringup：
    joy_linux → /joy → joy_node_cpp
        ├─ 直接底盘Twist → cmd_vel
        └─ 定时积分云台目标 → cmd_gimbal_joint
    不读取本块的enable_button、scale_chassis等参数

替换时的建议接线，尚未实施：
    导航最终速度 ─┐
                  ├─ 明确的模式／指令选择 → 唯一执行端输入
    手动速度 ─────┘
    两路先统一坐标、单位和自旋含义

本次本地及安裝pb包版本為1.0.2，安裝頭文件與本地一致；本地cpp／頭文件去除空白後與上游提交4a26966cb7958553677f4fe876d003c682c52b6d一致。原塊和安裝副本一致，simulation僅時鐘為True。本文保留參數説明，同時明確它是可替換的手柄入口，不是必須選用的導航組件。

1.2.參數

下面原樣保留髮送的24項參數及註釋。表格解釋pb實現，不會把這些值套到自己的joy_bringup。若以後從啓動中完整移除pb，本組參數才不再參與該節點運行。

pb_teleop_twist_joy_node:
  ros__parameters:
    use_sim_time: False
    robot_base_frame: gimbal_yaw
    control_mode: auto_control    # Option: auto_control, manual_control

    require_enable_button: true
    enable_button: 4              # L1 shoulder button
    enable_turbo_button: 5        # R1 shoulder button

    axis_chassis:
      x: 1                        # Left thumb stick vertical
      y: 0                        # Left thumb stick horizontal
      yaw: 6                      # button_left and button_right
    scale_chassis:
      x: 2.5
      y: 2.5
      yaw: 3.0
    scale_chassis_turbo:
      x: 4.0
      y: 4.0
      yaw: 6.0

    axis_gimbal:
      roll: -1                    # Disable
      pitch: 4                    # Right thumb stick vertical
      yaw: 3                      # Right thumb stick horizontal
    scale_gimbal:
      roll: 0.0
      pitch: -1.0
      yaw: 2.5
    scale_gimbal_turbo:
      roll: 0.0
      pitch: -1.5
      yaw: 3.5

1.2.1.ros__parameters（時鐘、參考系、模式與使能）

1.2.1.1.參數表

1.2.1.2.參數詳解

1.2.1.2.1.auto_control不是“開關自動駕駛模式”

auto按axis_chassis.x／y讀取搖桿，再乘當前檔scale，作為robot_base_frame中的目標位置偏移，查詢最新map←robot_base_frame TF轉換後發NavigateToPose。節流為ROS時間至少間隔0.25 s，名義最多4 Hz；實際頻率還取決於Joy回調、搖桿幅度和TF。目標生成

當前普通檔搖桿x=1表示在雲台軸前方取2.5 m偏移，turbo取4 m；不是要求底盤分別以2.5／4 m/s行駛。實際速度由Nav2控制器及速度鏈決定。目標會隨新Joy更新成新的前視點，不是直接轉發搖桿速度，也不通過axis_chassis.yaw給目標設朝向。

源碼只填寫局部Pose的position.x／y，沒有給orientation設置單位四元數；目標姿態構造需要修正／核對，不能把這條分支直接當作已經驗證的完整導航目標接口。沒有等待Action服務就緒或保留本節點的已接受目標句柄，本次未調用該Action驗證結果。

manual則直接發縮放後的Twist，不經本節點TF換軸，也沒有內置加減速平滑。默認輸出cmd_vel，當前導航平滑器訂閲的是cmd_vel_controller；不能因導航有velocity_smoother就認為手柄直髮速度也自動經過它。速度鏈與範圍

1.2.1.2.2.鬆開使能、搖桿回中與斷流

enable_turbo_button先判斷，滿足時直接turbo；否則檢查普通檔使能。失去使能時，在此前已發送過控制的條件下調用一次sendZeroCommand：auto向navigate_to_pose取消當前時刻以前的目標，同時發佈零Twist；不是持續發送零，也不等待確認取消已經完成。按鍵分支與停止

auto中abs(縮放後x)≤0.1且abs(縮放後y)≤0.1，只提前返回，不會取消上一目標。仍按着使能而鬆開搖桿時，車可能繼續完成此前目標，不能用“搖桿回中”代替Nav2取消。0.1比較的還是縮放後的座標偏移，普通檔與turbo對應的原始搖桿範圍不同。

取消按時間作用於同一個navigate_to_pose服務端，不只限定本節點保存的某個目標句柄；若其他決策客户端也發目標，需核對目標所有權。自己實現時宜保存並取消本次手柄目標，而不是靠跨客户端的時間取消充當模式仲裁。

本pb節點沒有Joy輸入年齡檢查，完全斷流時不會再進入釋放按鍵回調。雲台積分dt也沒有限制長間隔或回跳；重新來消息時可能把新角速度乘整個間隔。頭文件的sent_disable_msg_沒有顯式初始化，這個停止標誌還需要修正後才能依賴其初始狀態。上述為源碼邊界，本次沒有斷流或運動驗證。

1.2.2.底盤軸與比例（auto目標偏移、manual速度）

1.2.2.1.參數表

這裏使用完整參數名，明確每個分組的作用。軸索引是Joy.axes，不是Joy.buttons；註釋中的左右按鈕可能由驅動表達為一根軸，需核對實際消息。

getVal按axes[index]×scale計算；-1、缺少映射或超過消息軸數時返回0。它沒有把輸入軸統一夾到[-1,1]、檢查有限值或在這裏做死區；假定正常軸值範圍的滿杆輸出只是映射推算，不能當作異常輸入的硬上限。手柄型號、joy與joy_linux驅動不同，索引和正負方向均須用實際Joy消息核對。

1.2.3.雲台軸與比例（角速度積分成目標位置）

1.2.3.1.參數表

1.2.3.2.雲台積分、初始位置與時間

源碼保存從0開始的static pitch、yaw，每次已使能Joy回調更新：

pitch_target += axes[4] × 当前档pitch比例 × ROS dt
yaw_target   += axes[3] × 当前档yaw比例   × ROS dt
发布JointState：name=[gimbal_pitch_joint, gimbal_yaw_joint]
                position=[pitch_target, yaw_target]

position單位為rad，比例單位為rad/s；例如普通檔pitch軸為+1且dt=0.05 s，一次目標增量為-0.05 rad。這是公式示例，不是實測雲台角度。兩個目標沒有按當前實測關節初始化，也沒有pitch夾緊、yaw行程保護或dt異常保護。積分實現

鬆開使能不會發布新的雲台停止位置，而是停止調用該積分發送分支；末次位置是否繼續執行由接收端決定。控制節點也沒有自己的固定積分定時器，回調頻率由上游Joy消息和重發決定。當前PB joy launch配置deadzone=0.3、autorepeat_rate=20 Hz，這兩項屬於輸入驅動配置，不在原24項參數中。

1.2.4.相關源碼默認項（原YAML未顯式配置）

1.2.4.1.參數表

下面僅補兩項與底盤輸出格式有關的默認值，沒有向原YAML追加。pb源碼另有其他映射與發佈功能，本頁不把未發送的配置當作已經完整關閉全部額外輸出。

除use_sim_time由rclcpp時間源管理外，本頁pb功能參數在構造時讀取，沒有對應的參數更新回調。運行中改control_mode、按鍵或比例，不等於已有成員和Action客户端已經聯動改變；需重啓該節點再核對。也不能把自己的節點命名成同一個名字，就認為它自動擁有這些參數實現。

1.2.5.自己的joy_bringup已經有哪些功能，還缺什麼

本次讀到自己的Joy_Node／joy_node_cpp源碼及已安裝launch：

源碼：自己的手柄控制器、實物啓動、仿真啓動。源碼中有這些路徑，不代表已驗證編譯後的運動效果；本次沒有啓動它。

繼續完善自己的方案時，優先明確以下四件事：

1. 啓動選擇： 替換後主入口只啓動選定的手柄驅動和控制器；移除／關閉pb的Include，不靠刪參數來停節點，避免兩套驅動與映射一起啓動。
2. 指令出口與模式： 導航和手動輸入分別進入可辨認的話題，由一個模式選擇環節送到執行端；手動未取得控制權時不要持續向最終話題發零。切換時處理已有導航目標和雲台目標所有權。
3. 座標與單位： 導航最後cmd_vel按實際gimbal_yaw軸表達。自己的源碼只直接拷貝搖桿，未查詢TF；手動速度究竟按底盤還是雲台軸定義，必須與MCU協議一致。輸出JointState仍按pitch、yaw位置rad理解。當前最終速度約定
4. 使能、限值與反饋： 保留已有斷流和dt保護，按需要加手柄使能、速度範圍、雲台初始化和實際機械限位；auto若要用手柄發導航目標，再單獨實現有效Pose和目標句柄管理。

替換手柄節點不要求重寫Nav2的規劃器、控制器或速度平滑器，也不要求同時改MCU協議；是否需要改協議由當前接口是否能表達選定控制方式決定。本次只提供選擇和適配依據，沒有代替用户修改啓動、手柄代碼或協議。

1.2.6.本次核對與驗證範圍

• 已核對： pb包1.0.2與頭文件、固定上游源碼；24項原參數和兩套安裝副本；實物／仿真入口及joy_teleop安裝副本；自己的joy_bringup源碼、輸入驅動配置和安裝launch；串口訂閲cmd_vel及cmd_gimbal_joint。
• 源碼能確認： auto偏移與manual速度的不同單位；turbo優先使能；雲台角速度積分；當前yaw／roll不使用項；啓動註釋與實際Include不一致；兩套節點在指令輸出上的適配缺口。
• 建議： 繼續完善自己的joy_bringup，保留北極熊配置作參考；如暫時完整復現北極熊auto功能，可先使用其節點，但須處理本頁列出的實現條件，不能同時任由兩套節點向同一執行入口發送。
• 本次範圍： 僅整理文檔與目錄，未更改主入口、節點配置或原始碼，未查詢／改變當前控制模式，未發送Joy、速度、關節或導航目標，未做實車／仿真運動驗證。