From 35dbbe88cce34d669a91f9ff8f54a560eb48527b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?M=2E=20Fatih=20C=C4=B1r=C4=B1t?= <mfc@leodrive.ai>
Date: Mon, 6 Jun 2022 16:55:11 +0300
Subject: [PATCH] separate stamp and control_time, fill in README.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: M. Fatih Cırıt <mfc@leodrive.ai>
---
 autoware_control_msgs/README.md              | 30 ++++++++++++++++++++
 autoware_control_msgs/msg/Control.msg        |  7 +++++
 autoware_control_msgs/msg/ControlHorizon.msg | 11 +++++--
 autoware_control_msgs/msg/Lateral.msg        |  4 +++
 autoware_control_msgs/msg/Longitudinal.msg   |  4 +++
 5 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/autoware_control_msgs/README.md b/autoware_control_msgs/README.md
index 40631bd..d90f3d1 100644
--- a/autoware_control_msgs/README.md
+++ b/autoware_control_msgs/README.md
@@ -6,8 +6,38 @@ Vehicle dimensions and axes: <https://autowarefoundation.github.io/autoware-docu
 
 ### Lateral.msg
 
+Defines a lateral control command message with a timestamp.
+
+The message conveys the expectation for vehicle's lateral state to be in the given configuration in the time point: `control_time`.
+
+- The field `steering_tire_angle` is required.
+- The field `steering_tire_rotation_rate` is optional but may be required by some nodes.
+  - If this field is used, `is_defined_steering_tire_rotation_rate` must be set `true`.
+
 ### Longitudinal.msg
 
+Defines a longitudinal control command message with a timestamp.
+
+The message conveys the expectation for vehicle's longitudinal state to be in the given configuration in the time point: `control_time`.
+
+- The field `velocity` is required.
+- The field `acceleration` is optional but may be required by some nodes.
+  - If this field is used, `is_defined_acceleration` must be set `true`.
+- The field `jerk` is optional but may be required by some nodes.
+  - If this field is used, `is_defined_jerk` must be set `true`.
+
 ### Control.msg
 
+Defines a control command message, combining `Lateral.msg` and `Longitudinal.msg`.
+
+The message conveys the expectation for vehicle's combined control state to be in the given configuration in the time point: `control_time`.
+
+If the `control_time` is defined, the `control_time` field in the `lateral` and `longitudinal` fields are ignored.
+
 ### ControlHorizon.msg
+
+Defines a control commands array calculated for a future horizon.
+
+- Control messages are ordered from near to far future `[0 to N)` with `time_step_ms` increments.
+- First element of the array contains the control signals at the `control_time` of this message.
+- The `control_time` field in each element of the controls array can be ignored.
diff --git a/autoware_control_msgs/msg/Control.msg b/autoware_control_msgs/msg/Control.msg
index a463118..765024e 100644
--- a/autoware_control_msgs/msg/Control.msg
+++ b/autoware_control_msgs/msg/Control.msg
@@ -1,6 +1,13 @@
 # Control message with lateral and longitudinal components
 
+# Time this message was created
 builtin_interfaces/Time stamp
 
+# Time this configuration state is expected to be achieved in (optional)
+builtin_interfaces/Time control_time
+
+# Lateral control command
 Lateral lateral
+
+# Longitudinal control command
 Longitudinal longitudinal
diff --git a/autoware_control_msgs/msg/ControlHorizon.msg b/autoware_control_msgs/msg/ControlHorizon.msg
index 1c6ecd2..1c3cad2 100644
--- a/autoware_control_msgs/msg/ControlHorizon.msg
+++ b/autoware_control_msgs/msg/ControlHorizon.msg
@@ -1,13 +1,18 @@
-# Control messages predicted for a future horizon
+# Control messages calculated for a future horizon
 #
 # Control messages are ordered from near to far future [0 to N) with time_step_ms increments.
 #
-# First element of the array contains the control signals at the stamp of this message.
+# First element of the array contains the control signals at the control_time of this message.
 #
-# The stamps in the controls array can be ignored.
+# The control_time field in each element of the controls array can be ignored.
 
+# Time this message was created
 builtin_interfaces/Time stamp
 
+# Time when controls[0] configuration state is expected to be achieved in
+builtin_interfaces/Time control_time
+
+# Time difference between consecutive elements of the controls array in milliseconds
 float32 time_step_ms
 
 Control[] controls
diff --git a/autoware_control_msgs/msg/Lateral.msg b/autoware_control_msgs/msg/Lateral.msg
index d7b6367..7cf5680 100644
--- a/autoware_control_msgs/msg/Lateral.msg
+++ b/autoware_control_msgs/msg/Lateral.msg
@@ -8,8 +8,12 @@
 # Positive values represents left inclination (if forward)
 # Negative values represents right inclination (if forward)
 
+# Time this message was created
 builtin_interfaces/Time stamp
 
+# Time this configuration state is expected to be achieved in (optional)
+builtin_interfaces/Time control_time
+
 # Desired angle of the steering tire in rad (radians)
 float32 steering_tire_angle
 
diff --git a/autoware_control_msgs/msg/Longitudinal.msg b/autoware_control_msgs/msg/Longitudinal.msg
index 7acceba..f8f245a 100644
--- a/autoware_control_msgs/msg/Longitudinal.msg
+++ b/autoware_control_msgs/msg/Longitudinal.msg
@@ -5,8 +5,12 @@
 # Positive values represent forward motion (+X)
 # Negative values represent backward motion (-X)
 
+# Time this message was created
 builtin_interfaces/Time stamp
 
+# Time this configuration state is expected to be achieved in (optional)
+builtin_interfaces/Time control_time
+
 # Desired vehicle velocity in in m/s
 float32 velocity