rclcpp: Document value = declare_parameter Parameter pattern for basic parameter usage

[emersonknapp]

Issue Type

• 🐛 Bug / Problem
• ✏️ Typo / Grammar
• 📖 Outdated Content
• 🚀 Enhancement

Generated by Generative AI

No response

Distribution

all

Description

The very first usage most people see in https://docs.ros.org/en/rolling/Tutorials/Beginner-Client-Libraries/Using-Parameters-In-A-Class-CPP.html
is really complicated and verbose.

Most nodes, most of the time, get their read-only params up front a single time, and there is a much better syntax for that than is suggested in the introductory materials

auto param_value = declare_parameter(...);

Affected Pages/Sections

No response

Screenshots or Examples (if applicable)

No response

Suggested Fix

No response

Additional Context

No response

[kamal2730]

Hello @emersonknapp I would like to work on this issue can you assign this to me ?

[kamal2730]

Hi, I have been looking into this issue and I wanted to check in with you before proceeding.

The issue suggests introducing the simpler declare_parameter() return value syntax for read-only parameters:

class MinimalParam : public rclcpp::Node
{
public:
  MinimalParam()
  : Node("minimal_param_node")
  {
    auto my_param = this->declare_parameter("my_parameter", "world");

    auto timer_callback = [this, my_param](){
      RCLCPP_INFO(this->get_logger(), "Hello %s!", my_param.c_str());
    };

    timer_ = this->create_wall_timer(1000ms, timer_callback);
  }

private:
  rclcpp::TimerBase::SharedPtr timer_;
};

However, after reviewing the tutorial carefully, I noticed that directly replacing the existing code would break section 3.1 ("Change via the console"), since that section intentionally uses get_parameter() inside the timer callback to demonstrate live parameter updates at runtime.

I see two possible approaches:

1. Add this simpler snippet as a separate introductory example before the existing node, with a brief explanation of when each pattern is appropriate.
2. Keep the existing code as-is and add a note or callout explaining that declare_parameter() returns the value directly, and that this simpler pattern is preferred for read-only parameters.

I wanted to check with you before proceeding — which approach would better align with the goals of this tutorial? I am happy to go with whichever direction you prefer.

Thank you!

[emersonknapp]

I think that changing up the existing code sample would be better. We can show getting the initial values of two parameters in the constructor. And I don't think a timer is the right pattern for getting parameter updates, one can register a parameter changed callback to get updates, and that's a better usage pattern to get updates exactly when they are received rather than artificially delayed by a timer period. The example could show updating one of the parameters there, one that is not read only

[kamal2730]

Hi! I’ve updated the code snippet based on your feedback. Could you please review it? If it looks good, I’ll proceed with rewriting the 'Examine the code' section and then open the PR.

class MinimalParam : public rclcpp::Node
{
public:
  MinimalParam()
  : Node("minimal_param_node")
  {
    auto read_only_param = this->declare_parameter("my_read_only_param", "world");
    dynamic_param_ = this->declare_parameter("my_dynamic_param", "default_value");

    RCLCPP_INFO(this->get_logger(), "Read-only param: %s", read_only_param.c_str());
    RCLCPP_INFO(this->get_logger(), "Dynamic param: %s", dynamic_param_.c_str());

    param_handler_ = std::make_shared<rclcpp::ParameterEventHandler>(this);
    cb_handle_ = param_handler_->add_parameter_callback(
      "my_dynamic_param",
      [this](const rclcpp::Parameter & p) {
        this->dynamic_param_ = p.as_string();
        RCLCPP_INFO(this->get_logger(), "Value updated to: %s", this->dynamic_param_.c_str());
      });
  }

private:
  std::string dynamic_param_;
  std::shared_ptr<rclcpp::ParameterEventHandler> param_handler_;
  rclcpp::ParameterCallbackHandle::SharedPtr cb_handle_;
};