Add command configurations to API (#82)

### What change is being made

Please provide a detailed description of WHAT change is being made such that the reader is able to
understand the change holistically.

### Why this change is being made

Please provide the rationale behind the change and additional context like links to documents,
related work or issues.

### Tested

Please provide a description how this change was tested, e.g. unit tests, hardware tests or commands
you run.

GitOrigin-RevId: 390e4c59813e388b8a53a2a84fec709623dc4675

Author: awoll-bdai

control/command_interface.hpp

@@ -17,6 +17,29 @@ struct SE2VelocityConfig {
   std::optional<SE2VelocityRanges> ranges{};
 };
 
+/**
+ * @brief Configuration for SE3 pose commands.
+ */
+struct SE3PoseConfig {
+  // Currently no configuration options, but this struct is defined for consistency and future
+  // extensibility.
+};
+
+/**
+ * @brief Configuration for boolean selector commands.
+ */
+struct BooleanSelectorConfig {
+  // Currently no configuration options, but this struct is defined for consistency and future
+  // extensibility.
+};
+
+/**
+ * @brief Configuration for float scalar commands.
+ */
+struct FloatScalarConfig {
+  std::optional<Range> range{};
+};
+
 /**
  * @class CommandInterface
  *
@@ -33,6 +56,7 @@ class CommandInterface {
    *
    * @param command_name The name of the command.
    * @param config The configuration for the commanded se2 velocity.
+   * @return True if initialization succeeded, false otherwise.
    */
   virtual bool initSe2Velocity(const std::string& command_name,
                                const SE2VelocityConfig& /*config*/) {
@@ -55,8 +79,10 @@ class CommandInterface {
    * Called once during initialization (usually non real-time).
    *
    * @param command_name The name of the command.
+   * @param config The configuration for the commanded SE3 pose.
+   * @return True if initialization succeeded, false otherwise.
    */
-  virtual bool initSe3Pose(const std::string& command_name) {
+  virtual bool initSe3Pose(const std::string& command_name, const SE3PoseConfig& /*config*/) {
     LOG_STREAM(ERROR, "initSe3Pose() not implemented for command: " << command_name);
     return false;
   }
@@ -76,8 +102,11 @@ class CommandInterface {
    * Called once during initialization (usually non real-time).
    *
    * @param command_name The name of the command.
+   * @param config The configuration for the commanded boolean selector.
+   * @return True if initialization succeeded, false otherwise.
    */
-  virtual bool initBooleanSelector(const std::string& command_name) {
+  virtual bool initBooleanSelector(const std::string& command_name,
+                                   const BooleanSelectorConfig& /*config*/) {
     LOG_STREAM(ERROR, "initBooleanSelector() not implemented for command: " << command_name);
     return false;
   }
@@ -97,8 +126,11 @@ class CommandInterface {
    * Called once during initialization (usually non real-time).
    *
    * @param command_name The name of the command.
+   * @param config The configuration for the commanded float scalar.
+   * @return True if initialization succeeded, false otherwise.
    */
-  virtual bool initFloatValue(const std::string& command_name) {
+  virtual bool initFloatValue(const std::string& command_name,
+                              const FloatScalarConfig& /*config*/) {
     LOG_STREAM(ERROR, "initFloatValue() not implemented for command: " << command_name);
     return false;
   }

control/components.cpp

@@ -411,7 +411,7 @@ CommandSE3PoseInput::CommandSE3PoseInput(const std::string& key, const std::stri
     : key_(key), command_name_(command_name) {}
 
 bool CommandSE3PoseInput::init(RobotStateInterface& /*state*/, CommandInterface& command) {
-  return command.initSe3Pose(command_name_);
+  return command.initSe3Pose(command_name_, SE3PoseConfig{});
 }
 
 bool CommandSE3PoseInput::read(OnnxRuntime& runtime, RobotStateInterface& /*state*/,
@@ -451,7 +451,7 @@ CommandBooleanInput::CommandBooleanInput(const std::string& key, const std::stri
     : key_(key), command_name_(command_name) {}
 
 bool CommandBooleanInput::init(RobotStateInterface& /*state*/, CommandInterface& command) {
-  return command.initBooleanSelector(command_name_);
+  return command.initBooleanSelector(command_name_, BooleanSelectorConfig{});
 }
 
 bool CommandBooleanInput::read(OnnxRuntime& runtime, RobotStateInterface& /*state*/,
@@ -465,11 +465,12 @@ bool CommandBooleanInput::read(OnnxRuntime& runtime, RobotStateInterface& /*stat
 }
 
 // Implementation of CommandFloatInput methods
-CommandFloatInput::CommandFloatInput(const std::string& key, const std::string& command_name)
-    : key_(key), command_name_(command_name) {}
+CommandFloatInput::CommandFloatInput(const std::string& key, const std::string& command_name,
+                                     const metadata::FloatCommandMetadata& metadata)
+    : key_(key), command_name_(command_name), metadata_(metadata) {}
 
 bool CommandFloatInput::init(RobotStateInterface& /*state*/, CommandInterface& command) {
-  return command.initFloatValue(command_name_);
+  return command.initFloatValue(command_name_, FloatScalarConfig{.range = metadata_.range});
 }
 
 bool CommandFloatInput::read(OnnxRuntime& runtime, RobotStateInterface& /*state*/,

control/components.hpp

@@ -483,15 +483,18 @@ class CommandFloatInput : public Input {
    *
    * @param key ONNX input tensor name (e.g., "commands.speed_scale").
    * @param command_name Name of the float command to read.
+   * @param metadata Float command metadata containing optional value range.
    */
-  CommandFloatInput(const std::string& key, const std::string& command_name);
+  CommandFloatInput(const std::string& key, const std::string& command_name,
+                    const metadata::FloatCommandMetadata& metadata);
 
   bool init(RobotStateInterface& state, CommandInterface& command) override;
   bool read(OnnxRuntime& runtime, RobotStateInterface& state, CommandInterface& command) override;
 
  private:
-  std::string key_;           ///< ONNX input tensor name.
-  std::string command_name_;  ///< Float command name.
+  std::string key_;                          ///< ONNX input tensor name.
+  std::string command_name_;                 ///< Float command name.
+  metadata::FloatCommandMetadata metadata_;  ///< Float command configuration.
 };
 
 /**

control/matcher.cpp

@@ -397,7 +397,13 @@ bool CommandFloatMatcher::matches(const Match& maybe_match) {
 std::vector<std::unique_ptr<Input>> CommandFloatMatcher::createInputs() const {
   std::vector<std::unique_ptr<Input>> inputs;
   for (const auto& [name, match] : found_matches_) {
-    inputs.push_back(std::make_unique<CommandFloatInput>(match.name, name));
+    metadata::FloatCommandMetadata metadata;
+    if (match.metadata.has_value()) {
+      auto maybe_metadata =
+          metadata::safe_json_get<metadata::FloatCommandMetadata>(match.metadata.value());
+      if (maybe_metadata.has_value()) metadata = maybe_metadata.value();
+    }
+    inputs.push_back(std::make_unique<CommandFloatInput>(match.name, name, metadata));
   }
   return inputs;
 }
@@ -415,12 +421,13 @@ bool CommandSE2VelocityMatcher::matches(const Match& maybe_match) {
 std::vector<std::unique_ptr<Input>> CommandSE2VelocityMatcher::createInputs() const {
   std::vector<std::unique_ptr<Input>> inputs;
   for (const auto& [name, match] : found_matches_) {
-    if (!match.metadata.has_value()) continue;
-    auto maybe_metadata =
-        metadata::safe_json_get<metadata::SE2VelocityCommandMetadata>(match.metadata.value());
-    if (!maybe_metadata.has_value()) continue;
-    inputs.push_back(
-        std::make_unique<CommandSE2VelocityInput>(match.name, name, maybe_metadata.value()));
+    metadata::SE2VelocityCommandMetadata metadata;
+    if (match.metadata.has_value()) {
+      auto maybe_metadata =
+          metadata::safe_json_get<metadata::SE2VelocityCommandMetadata>(match.metadata.value());
+      if (maybe_metadata.has_value()) metadata = maybe_metadata.value();
+    }
+    inputs.push_back(std::make_unique<CommandSE2VelocityInput>(match.name, name, metadata));
   }
   return inputs;
 }

control/metadata.hpp

@@ -97,6 +97,31 @@ inline void from_json(const json& j, SE2VelocityCommandMetadata& cmd) {
   }
 }
 
+/**
+ * @brief Metadata for float scalar commands.
+ *
+ * Specifies optional range constraints for float scalar commands.
+ */
+struct FloatCommandMetadata {
+  std::optional<Range> range{};  ///< Optional range constraint for the float command.
+};
+
+/**
+ * @brief Parse FloatCommandMetadata from JSON.
+ *
+ * @param j JSON object optionally containing "range" field.
+ * @param cmd FloatCommandMetadata object to populate.
+ */
+inline void from_json(const json& j, FloatCommandMetadata& cmd) {
+  if (j.contains("range") && j["range"].is_array() && j["range"].size() == 2) {
+    Range range;
+    j.at("range").get_to(range);
+    cmd.range = range;
+  } else {
+    cmd.range = std::nullopt;
+  }
+}
+
 /**
  * @brief Metadata for height scan sensors.
  *

control/test/components_test.cpp

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Robotics and AI Institute LLC dba RAI Institute. All rights reserved.
 
 #include "components.hpp"
+#include "matcher.hpp"
 #include "mock_command_interface.hpp"
 #include "mock_state_interface.hpp"
 #include "onnx_runtime.hpp"
@@ -211,4 +212,49 @@ TEST_F(OnnxComponentsTest, MemoryOutput_WithRealRuntime) {
   EXPECT_TRUE(memory_was_overwritten) << "Memory should be overwritten with new output data";
 }
 
+// ---------------  Matcher tests for default metadata --------------------------------
+
+TEST(CommandFloatMatcherTest, CreatesInputWithoutMetadata) {
+  CommandFloatMatcher matcher;
+  Match match_without_metadata{.name = "cmd.float.gain"};
+  ASSERT_TRUE(matcher.matches(match_without_metadata));
+
+  auto inputs = matcher.createInputs();
+  ASSERT_EQ(inputs.size(), 1u) << "Should create input even without metadata";
+}
+
+TEST(CommandFloatMatcherTest, CreatesInputWithMetadata) {
+  CommandFloatMatcher matcher;
+  Match match_with_metadata{
+      .name = "cmd.float.scale",
+      .metadata = R"({"range": [-1.0, 1.0]})",
+  };
+  ASSERT_TRUE(matcher.matches(match_with_metadata));
+
+  auto inputs = matcher.createInputs();
+  ASSERT_EQ(inputs.size(), 1u);
+}
+
+TEST(CommandSE2VelocityMatcherTest, CreatesInputWithoutMetadata) {
+  CommandSE2VelocityMatcher matcher;
+  Match match_without_metadata{.name = "cmd.se2_velocity.vel"};
+  ASSERT_TRUE(matcher.matches(match_without_metadata));
+
+  auto inputs = matcher.createInputs();
+  ASSERT_EQ(inputs.size(), 1u) << "Should create input even without metadata";
+}
+
+TEST(CommandSE2VelocityMatcherTest, CreatesInputWithMetadata) {
+  CommandSE2VelocityMatcher matcher;
+  Match match_with_metadata{
+      .name = "cmd.se2_velocity.vel",
+      .metadata =
+          R"({"ranges": {"lin_vel_x": [-1.0, 1.0], "lin_vel_y": [-0.5, 0.5], "ang_vel_z": [-2.0, 2.0]}})",
+  };
+  ASSERT_TRUE(matcher.matches(match_with_metadata));
+
+  auto inputs = matcher.createInputs();
+  ASSERT_EQ(inputs.size(), 1u);
+}
+
 }  // namespace exploy::control

control/test/controller_test.cpp

@@ -206,9 +206,9 @@ class OnnxControllerTest : public ::testing::Test {
         .WillOnce(Return(true));
     EXPECT_CALL(command_mock_, initSe2Velocity("vel_with_range", HasRanges(kRanges)))
         .WillOnce(Return(true));
-    EXPECT_CALL(command_mock_, initSe3Pose("pose")).WillOnce(Return(true));
-    EXPECT_CALL(command_mock_, initBooleanSelector("selector")).WillOnce(Return(true));
-    EXPECT_CALL(command_mock_, initFloatValue("value")).WillOnce(Return(true));
+    EXPECT_CALL(command_mock_, initSe3Pose("pose", _)).WillOnce(Return(true));
+    EXPECT_CALL(command_mock_, initBooleanSelector("selector", _)).WillOnce(Return(true));
+    EXPECT_CALL(command_mock_, initFloatValue("value", _)).WillOnce(Return(true));
   }
 
   void ExpectInitCustom() {

control/test/mock_command_interface.hpp

@@ -12,13 +12,16 @@ class MockCommandInterface : public CommandInterface {
               (const std::string& command_name, const SE2VelocityConfig& config), (override));
   MOCK_METHOD(std::optional<SE2Velocity>, se2Velocity, (const std::string& command_name),
               (override));
-  MOCK_METHOD(bool, initSe3Pose, (const std::string& command_name), (override));
+  MOCK_METHOD(bool, initSe3Pose, (const std::string& command_name, const SE3PoseConfig& config),
+              (override));
   MOCK_METHOD(std::optional<SE3Pose>, se3Pose, (const std::string& command_name),
               (const, override));
-  MOCK_METHOD(bool, initBooleanSelector, (const std::string& command_name), (override));
+  MOCK_METHOD(bool, initBooleanSelector,
+              (const std::string& command_name, const BooleanSelectorConfig& config), (override));
   MOCK_METHOD(std::optional<bool>, booleanSelector, (const std::string& command_name),
               (const override));
-  MOCK_METHOD(bool, initFloatValue, (const std::string& command_name), (override));
+  MOCK_METHOD(bool, initFloatValue,
+              (const std::string& command_name, const FloatScalarConfig& config), (override));
   MOCK_METHOD(std::optional<float>, floatValue, (const std::string& command_name),
               (const override));
 };

control/test/testdata/test_onnx_generator.py

@@ -199,6 +199,7 @@ def get_command_metadata() -> dict:
                 "ang_vel_z": [-2.5, 2.5],
             },
         },
+        "cmd.float.value": {},
     }