Guardian (Obstacle Stop Protection) Service Interface

Overview

The Guardian service interface provides obstacle-aware behavior management, including speed attenuation and active stop triggering. It supports both parameter configuration and runtime enable/disable control through C++ APIs and ROS 2 communication.

Function	C++ Support	ROS 2 Support
Set Guardian Parameters	✔	✔
Enable/Disable Guardian	✔	✘

Set Guardian Parameters

C++ Interface

Function:rcClientInterfaceSetGuardian

/**
 * @brief Configure Guardian parameters.
 * 
 * This function sets the velocity decay ratio and trigger source for Guardian behavior.
 * 
 * @param from                 Operation mode (e.g., NAV or JOY).
 * @param velocity_decay_ratio Speed attenuation ratio (0.0 to 1.0).
 * @param trigger_source       Trigger source identifier.
 * @return                     true if the parameters are set successfully, false otherwise.
 */
bool rcClientInterfaceSetGuardian(
    common::NAV_OR_JOY_MODE from,
    float velocity_decay_ratio,
    std::string trigger_source);

Example Usage:

robot_control::common::NAV_OR_JOY_MODE mode = robot_control::common::NAV_OR_JOY_MODE::joy_control;
float decay_ratio = 0.5; // Example value, representing the speed decay ratio.
std::string source = "SOURCE_A"; // Example trigger source
bool success = rcClientInterfaceSetGuardian(mode, decay_ratio, source);
if (success) {
    std::cout << "Guardian Parameters Set Successfully." << std::endl;
} else {
    std::cout << "Failed to Set Guardian Parameters." << std::endl;
}

WARNING

Note

• Ensure that the provided velocity decay ratio and trigger source are valid.

ROS2 Interface

This interface subscribes to the /guardian topic to receive Guardian commands for obstacle-related protection behavior. The topic uses the daystar_navigation_msgs::msg::Guardian message type, which contains relevant configuration parameters. Upon receiving data, the system updates Guardian parameters accordingly.

Topic Name	Topic Type	Role
/guardian	daystar_navigation_msgs::msg::Guardian	Subscriber

Message Structure

The daystar_navigation_msgs::msg::Guardian message typically includes parameters related to obstacle stop behavior, such as velocity decay ratio, control mode, and trigger source. Please refer to the specific .msg definition for details.

Example Usage

daystar_navigation_msgs::msg::Guardian guardian_msg;
// Fill in guardian_msg fields according to the message definition

Testing Methods

• Publish a single message:

ros2 topic pub --once /guardian daystar_navigation_msgs/msg/Guardian "{...}"

• Publish continuously at 10 Hz:

ros2 topic pub --rate 10 /guardian daystar_navigation_msgs/msg/Guardian "{...}"

Precautions

• Ensure that the ROS 2 node responsible for handling the Guardian topic is running and actively subscribed.
• The message format must strictly adhere to the daystar_navigation_msgs::msg::Guardian message definition.
• When continuously publishing messages, control the frequency to avoid network congestion (e.g., ≤10 Hz recommended).

---

Enable/Disable Guardian Functionality

C++ Interface

Function: rcClientInterfaceSetGuardianSwitch

/**
 * @brief Enable or disable the Guardian functionality.
 * 
 * This function is used to turn the Guardian protection mechanism on or off.
 * 
 * @param from    Specifies the operation mode (e.g., navigation or joystick control).
 * @param enable  Set to true to enable Guardian, false to disable it.
 * @return        Returns true if the operation was successful; false otherwise.
 */
bool rcClientInterfaceSetGuardianSwitch(
    robot_control::common::NAV_OR_JOY_MODE from,
    bool enable);

Usage Example

robot_control::common::NAV_OR_JOY_MODE mode = robot_control::common::NAV_OR_JOY_MODE::joy_control;
bool enable_guardian = true; // Example: enable Guardian
bool success = rcClientInterfaceSetGuardianSwitch(mode, enable_guardian);
if (success) {
    std::cout << "Guardian Switch Set Successfully." << std::endl;
} else {
    std::cout << "Failed to Set Guardian Switch." << std::endl;
}

Precautions

• Ensure that the enable parameter value is valid (true or false).
• This function is typically used in runtime scenarios where safety modes need to be dynamically activated or bypassed (e.g., in manual override situations).