# joy_teleop

*This file is ai generated. Do not edit this file directly. Instead, edit the node source code and run the generate-node-docs command to update this file.*

## Description

The `joy_teleop` node is a generic joystick teleoperation interface that maps joystick buttons and axes to ROS topics, services, and actions. It provides flexible configuration to control robots using any joystick, allowing users to map joystick inputs to arbitrary message/service/action types.

## Subscribers

| Topic | Type | Description |
|-------|------|-------------|
| `joy` | `sensor_msgs/msg/Joy` | Receives joystick input messages containing button and axis states |

## Publishers

Publishers are dynamically created based on configuration. Each configured topic command creates a publisher with:
- **Topic name**: User-defined in configuration
- **Message type**: User-defined in configuration (e.g., `geometry_msgs/msg/TwistStamped`, `geometry_msgs/msg/Wrench`)
- **Description**: Publishes command messages when configured buttons/axes are activated

## Services

Service clients are dynamically created based on configuration. Each configured service command creates a client with:
- **Service name**: User-defined in configuration
- **Service type**: User-defined in configuration
- **Description**: Calls service when configured buttons/axes are activated

## Actions

Action clients are dynamically created based on configuration. Each configured action command creates a client with:
- **Action name**: User-defined in configuration
- **Action type**: User-defined in configuration
- **Description**: Sends action goals when configured buttons/axes are activated

## Parameters

The node uses a hierarchical parameter structure where each command is configured under its own namespace. All parameters are defined dynamically through configuration files.

### Command Configuration Parameters

Each command requires the following base parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `<command_name>.type` | string | Interface type: `topic`, `service`, or `action` |
| `<command_name>.interface_type` | string | ROS message/service/action type (e.g., `geometry_msgs/msg/Twist`) |

#### Topic Commands

| Parameter | Type | Description |
|-----------|------|-------------|
| `<command_name>.topic_name` | string | Name of the topic to publish to |
| `<command_name>.deadman_buttons` | list of integers | Button indices that must be pressed (1-indexed) |
| `<command_name>.deadman_axes` | list of integers | Axis indices that must be at 1.0 |
| `<command_name>.deadman_axes_negative` | list of integers | Axis indices that must be at -1.0 |
| `<command_name>.message_value.<field>` | dict | Fixed message field values to publish |
| `<command_name>.axis_mappings.<field>.axis` | integer | Joystick axis index to map from |
| `<command_name>.axis_mappings.<field>.button` | integer | Joystick button index to map from |
| `<command_name>.axis_mappings.<field>.value` | any | Fixed value to use |
| `<command_name>.axis_mappings.<field>.scale` | float | Scaling factor for axis/button value |
| `<command_name>.axis_mappings.<field>.offset` | float | Offset to add after scaling |
| `<command_name>.axis_mappings.<field>.index` | integer | Index for array fields (default: 0) |

#### Service Commands

| Parameter | Type | Description |
|-----------|------|-------------|
| `<command_name>.service_name` | string | Name of the service to call |
| `<command_name>.buttons` | list of integers | Button indices that must be pressed |
| `<command_name>.axes` | list of integers | Axis indices that must be at 1.0 |
| `<command_name>.axes_negative` | list of integers | Axis indices that must be at -1.0 |
| `<command_name>.service_request` | dict | Request fields to set when calling service |

#### Action Commands

| Parameter | Type | Description |
|-----------|------|-------------|
| `<command_name>.action_name` | string | Name of the action server |
| `<command_name>.buttons` | list of integers | Button indices that must be pressed |
| `<command_name>.axes` | list of integers | Axis indices that must be at 1.0 |
| `<command_name>.axes_negative` | list of integers | Axis indices that must be at -1.0 |
| `<command_name>.action_goal` | dict | Goal fields to set when sending action |

## Example Usage

### Basic Launch

```bash
ros2 run joy_teleop joy_teleop --ros-args --params-file /path/to/config.yaml
```

### Example Configuration File

```yaml
joy_teleop:
  ros__parameters:
    # Topic command with axis mapping (for continuous control)
    cmd_vel:
      type: topic
      interface_type: geometry_msgs/msg/TwistStamped
      topic_name: cmd_vel
      deadman_buttons: [4]
      axis_mappings:
        twist-linear-x:
          axis: 1
          scale: 0.5
          offset: 0.0
        twist-angular-z:
          axis: 0
          scale: 0.5
          offset: 0.0

    # Topic command with fixed message (for discrete control)
    stop:
      type: topic
      interface_type: geometry_msgs/msg/Twist
      topic_name: cmd_vel
      deadman_buttons: [0, 2]
      message_value:
        linear-x:
          value: 0.0
        angular-z:
          value: 0.0

    # Service command
    reset_odom:
      type: service
      interface_type: std_srvs/srv/Empty
      service_name: reset_odometry
      buttons: [8]
      service_request: {}

    # Action command
    navigate:
      type: action
      interface_type: nav2_msgs/action/NavigateToPose
      action_name: navigate_to_pose
      buttons: [9]
      action_goal:
        pose-header-frame_id: "map"
        pose-pose-position-x: 1.0
        pose-pose-position-y: 2.0
```

### Launch with Joy Node

```python
from launch import LaunchDescription
from launch_ros.actions import Node
from ament_index_python.packages import get_package_share_directory
import os

def generate_launch_description():
    config_file = os.path.join(
        get_package_share_directory('joy_teleop'),
        'config', 'joy_teleop_example.yaml'
    )
    
    return LaunchDescription([
        Node(
            package='joy',
            executable='joy_node',
            name='joy_node'
        ),
        Node(
            package='joy_teleop',
            executable='joy_teleop',
            parameters=[config_file]
        )
    ])
```

## Notes

- Button and axis indices are 0-indexed
- Topic commands with `message_value` publish once per button press (debounced)
- Topic commands with `axis_mappings` publish continuously while deadman buttons are held
- Service and action commands are debounced to prevent multiple calls per button press
- Messages with a `header` field will have the timestamp automatically filled with the current time
- Field names in configuration use `-` as separator (e.g., `twist-linear-x` maps to `twist.linear.x`)