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、速度、關節或導航目標，未做實車／模擬運動驗證。