Skip to content

Commit 58a6900

Browse files
curious-jpcurious-jp
committed
chore: Update Longitudinal_control.md with additional details for requestSpeedChange API
1 parent 1904b2a commit 58a6900

File tree

1 file changed

+130
-97
lines changed

1 file changed

+130
-97
lines changed

‎docs/developer_guide/Longitudinal_control.md‎

Lines changed: 130 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -1,158 +1,191 @@
11
# Longitudinal Control
22

3-
traffic_simulator has various ways to control the longitudinal behavior of the npc.
3+
traffic_simulator has various ways to control the longitudinal behavior of the entity.
4+
5+
## Basic Information
6+
### target_speed
7+
In this document, you will see variant called `target_speed` which is the target speed of the entity. The entity will always try to reach the target speed under the constraints such as acceleration or deceleration set by the user or if not by the default value. If `target_speed` is `NULL`, the entity will keep or change the speed with some other constraints set by the user or if not by the default value.
8+
9+
### Set functions
10+
Set functions directly changes the speed, acceleration, or deceleration of the entity. This will be executed immediately, even while the entity is trying to reach the target speed. It will ignore the physics of the entity and set the value directly.
411

512
## List of Longitudinal Controllers
613

7-
| Name | Description |
8-
| --------------------------------------------------------- | -------------------------------------------- |
9-
| [**requestSpeedChange**](#requestSpeedChange) | Changes the speed of the npc. |
10-
| [**requestSynchronize**](#requestSynchronize) | Synchronizes the npc with the target entity. |
11-
| [**setLinearVelocity**](#setLinearVelocity) | Sets the linear velocity of the npc. |
12-
| [**setTwist**](#setTwist) | Sets the twist of the npc. |
13-
| [**setAcceleration**](#setAcceleration) | Sets the acceleration of the npc. |
14-
| [**setAccelerationLimit**](#setAccelerationLimit) | Sets the acceleration limit of the npc. |
15-
| [**setAccelerationRateLimit**](#setAccelerationRateLimit) | Sets the acceleration rate limit of the npc. |
16-
| [**setDecelerationLimit**](#setDecelerationLimit) | Sets the deceleration limit of the npc. |
17-
| [**setDecelerationRateLimit**](#setDecelerationRateLimit) | Sets the deceleration rate limit of the npc. |
18-
| [**setVelocityLimit**](#setVelocityLimit) | Sets the velocity limit of the npc. |
14+
| Name | Description |
15+
| --------------------------------------------------------- | ----------------------------------------------- |
16+
| [**requestSpeedChange**](#requestSpeedChange) | Changes the speed of the entity. |
17+
| [**requestSynchronize**](#requestSynchronize) | Synchronizes the entity with the target entity. |
18+
| [**setLinearVelocity**](#setLinearVelocity) | Sets the linear velocity of the entity. |
19+
| [**setTwist**](#setTwist) | Sets the twist of the entity. |
20+
| [**setAcceleration**](#setAcceleration) | Sets the acceleration of the entity. |
21+
| [**setAccelerationLimit**](#setAccelerationLimit) | Sets the acceleration limit of the entity. |
22+
| [**setAccelerationRateLimit**](#setAccelerationRateLimit) | Sets the acceleration rate limit of the entity. |
23+
| [**setDecelerationLimit**](#setDecelerationLimit) | Sets the deceleration limit of the entity. |
24+
| [**setDecelerationRateLimit**](#setDecelerationRateLimit) | Sets the deceleration rate limit of the entity. |
25+
| [**setVelocityLimit**](#setVelocityLimit) | Sets the velocity limit of the entity. |
1926

2027
## Details
2128
### requestSpeedChange
22-
By using `API::requestSpeedChange`, you can change the speed of the npc.
29+
By using `API::requestSpeedChange`, you can change the speed of the entity.
2330
MiscObjectEntity can not be controlled by this API.
2431

25-
| Value | Type | Description |
26-
| ------------ | ------ | ----------------------------------------------------------- |
27-
| name | string | Name of the npc. |
28-
| target_speed | double | Target speed of the npc. |
29-
| continuous | bool | If true the npc will keep the speed until the next command. |
32+
| Value | Type | Description |
33+
| ------------ | ------ | -------------------------------------------------------------- |
34+
| name | string | Name of the entity. |
35+
| target_speed | double | Target speed of the entity. |
36+
| continuous | bool | If true the entity will keep the speed until the next command. |
3037
#### EgoEntity
3138
`target_speed` will be set as initial target speed of the EgoEntity only before the scenario starts.
3239

3340
#### Other entity
34-
The function will change the target speed of entity to `target_speed` immediately.
35-
If `continuous` is set to `false`, job to accelerate to target speed will be deleted after the velocity has reached the target speed. If set to `true`, the npc will keep the speed until the next longitudinal control command ordered. It will accelerate on maximum acceleration rate set previously.
36-
37-
| Value | Type | Description |
38-
| ------------ | ------------------------ | ----------------------------------------------------------- |
39-
| name | string | Name of the npc. |
40-
| target_speed | double | Target speed of the npc. |
41-
| transition | speed_change::Transition | Transition type. |
42-
| constraint | speed_change::Constraint | Constraint type. |
43-
| continuous | bool | If true the npc will keep the speed until the next command. |
41+
The function will change entities `target_speed` to given immediately.
42+
If `continuous` is set to `false`, job to accelerate to target speed will be deleted after the velocity has reached the target speed. If set to `true`, the entity will keep the speed until the next longitudinal control command ordered. It will accelerate on maximum acceleration rate set previously.
43+
44+
| Value | Type | Description |
45+
| ------------ | ------------------------ | -------------------------------------------------------------- |
46+
| name | string | Name of the entity. |
47+
| target_speed | double | Target speed of the entity. |
48+
| transition | speed_change::Transition | Transition type. |
49+
| constraint | speed_change::Constraint | Constraint type. |
50+
| continuous | bool | If true the entity will keep the speed until the next command. |
51+
4452
#### EgoEntity
4553
`target_speed` will be set as initial target speed of the EgoEntity only before the scenario starts.
4654

4755
#### Other entity
48-
If `continuous` is set to `false`, job to accelerate to target speed will be deleted after the velocity has reached the target speed. If set to `true`, the npc will keep the speed until the next longitudinal control command ordered.
56+
If `continuous` is set to `false`, job to accelerate to target speed will be deleted after the velocity has reached the target speed. If set to `true`, the entity will keep the speed until the next longitudinal control command ordered.
4957

50-
When `constraint` is set to `LONGITUDINAL_ACCELERATION`, the entity will accelerate to the target speed with acceleration rate you set.
58+
##### Longitudinal Acceleration
59+
When `constraint.type` is set to `LONGITUDINAL_ACCELERATION`, the entity will accelerate to the target speed with acceleration of `constraint.value`.
5160
- If `transition` is set to `LINEAR`, the entity will accelerate to the target speed linearly.
52-
- If `transition` is set to `AUTO`, it will change the maximum acceleration speed of the entity and append the job to change the target speed of the npc to the job queue. After the npc reaches the target speed, it will change the maximum acceleration speed back to the original value.
53-
- If `transition` is set to `STEP`, it will
54-
55-
56-
When `constraint` is set to `TIME`, the entity will accelerate to the target speed by the time you set.
57-
When `constraint` is set to `NONE`, is will append the job to change the target_speed of the npc to the job queue.
58-
59-
`change target speed` block in the below figure is the highest priority compared to other blocks.
60-
If target speed is set somewhere else, the entity will try to change the speed to the target speed under acceleration/deceleration constraints set by the user or if not by the default value.
61-
![requestSpeedChange](../images/Longitudinal_control/requestSpeedChange.png)
62-
63-
64-
| Value | Type | Description |
65-
| ------------ | --------------------------------- | ----------------------------------------------------------- |
66-
| name | string | Name of the npc. |
67-
| target_speed | speed_change::RelativeTargetSpeed | Relative target speed. |
68-
| continuous | bool | If true the npc will keep the speed until the next command. |
69-
70-
| Value | Type | Description |
71-
| ------------ | --------------------------------- | ----------------------------------------------------------- |
72-
| name | string | Name of the npc. |
73-
| target_speed | speed_change::RelativeTargetSpeed | Relative target speed. |
74-
| transition | speed_change::Transition | Transition type. |
75-
| constraint | speed_change::Constraint | Constraint type. |
76-
| continuous | bool | If true the npc will keep the speed until the next command. |
61+
- If `transition` is set to `AUTO`, it will change the maximum acceleration speed of the entity and append the job to change the target speed of the entity to the job queue. After the entity reaches the target speed, it will change the maximum acceleration speed back to the original value.
62+
- If `transition` is set to `STEP`, it will change the speed of the entity to the target speed immediately. It will ignore the acceleration rate set by the user.
63+
64+
##### Time Constraint Acceleration
65+
When `constraint.type` is set to `TIME`, the entity will accelerate to the target speed by the time of `constraint.value`.
66+
For `transition` it is the same as `LONGITUDINAL_ACCELERATION`.
67+
68+
##### None Constraint Acceleration
69+
When `constraint` is set to `NONE`, is will append the job to change the target_speed of the entity to the job queue.
70+
71+
```mermaid
72+
flowchart LR
73+
A[requestSpeedChange] --> B{constraint.type};
74+
B -- LONGITUDINAL_ACCELERATION --> C{transition};
75+
C -- LINEAR --> D[SetLinearAcceleration];
76+
D -- AUTO --> C;
77+
C -- AUTO --> E[SetAccelerationRateLimit
78+
or
79+
SetDecelerationRateLimit];
80+
E --> F[[ChangeTargetSpeed]];
81+
C -- STEP --> G[[changeTargetSpeed]];
82+
G --> H[setLinearVelocity];
83+
84+
B -- TIME --> I{transition};
85+
I -- LINEAR --> J[SetLinearAcceleration];
86+
J -- AUTO --> I;
87+
I -- AUTO --> K[SetAccelerationRateLimit
88+
or
89+
SetDecelerationRateLimit];
90+
K --> L[[ChangeTargetSpeed]];
91+
I -- STEP --> M[[changeTargetSpeed]];
92+
M --> N[setLinearVelocity];
93+
94+
B -- NONE ---> O[[ChangeTargetSpeed]];
95+
```
96+
97+
| Value | Type | Description |
98+
| ------------ | --------------------------------- | -------------------------------------------------------------- |
99+
| name | string | Name of the entity. |
100+
| target_speed | speed_change::RelativeTargetSpeed | Relative target speed. |
101+
| continuous | bool | If true the entity will keep the speed until the next command. |
102+
103+
| Value | Type | Description |
104+
| ------------ | --------------------------------- | -------------------------------------------------------------- |
105+
| name | string | Name of the entity. |
106+
| target_speed | speed_change::RelativeTargetSpeed | Relative target speed. |
107+
| transition | speed_change::Transition | Transition type. |
108+
| constraint | speed_change::Constraint | Constraint type. |
109+
| continuous | bool | If true the entity will keep the speed until the next command. |
77110

78111
### requestSynchronize
79112
By using `API::requestSynchronize`, you can request the entity to adjust speed to stop at the designated lanelet by the time target entity crosses the another designated lanelet.
80113

81114
| Value | Description |
82115
| ---------------- | ---------------------------------------------------------------------- |
83-
| name | Name of the npc. |
116+
| name | Name of the entity. |
84117
| target_name | Name of the target entity. |
85118
| target_sync_pose | Target lanelet pose for target entity. |
86119
| entity_target | Target lanelet pose for controlling entity. |
87120
| target_speed | Target speed for controlling entity (meter per second). |
88121
| tolerance | Tolerance for how much margin to accept to stop at the target (meter). |
89122

90123
### setLinearVelocity
91-
By using `API::setLinearVelocity`, you can set the linear velocity of the npc.
124+
By using `API::setLinearVelocity`, you can set the linear velocity of the entity.
92125

93-
| Value | Type | Description |
94-
| --------------- | ------ | --------------------------- |
95-
| name | string | Name of the npc. |
96-
| linear_velocity | double | Linear velocity of the npc. |
126+
| Value | Type | Description |
127+
| --------------- | ------ | ------------------------------ |
128+
| name | string | Name of the entity. |
129+
| linear_velocity | double | Linear velocity of the entity. |
97130

98131
### setTwist
99-
By using `API::setTwist`, you can set the twist of the npc.
132+
By using `API::setTwist`, you can set the twist of the entity.
100133

101-
| Value | Type | Description |
102-
| ----- | ------------------------- | ----------------- |
103-
| name | string | Name of the npc. |
104-
| twist | geometry_msgs::msg::Twist | Twist of the npc. |
134+
| Value | Type | Description |
135+
| ----- | ------------------------- | -------------------- |
136+
| name | string | Name of the entity. |
137+
| twist | geometry_msgs::msg::Twist | Twist of the entity. |
105138

106139
### setAcceleration
107140

108-
By using `API::setAcceleration`, you can set the acceleration of the npc.
141+
By using `API::setAcceleration`, you can set the acceleration of the entity.
109142

110-
| Value | Type | Description |
111-
| ------------ | ------------------------- | ------------------------ |
112-
| name | string | Name of the npc. |
113-
| acceleration | geometry_msgs::msg::Accel | Acceleration of the npc. |
143+
| Value | Type | Description |
144+
| ------------ | ------------------------- | --------------------------- |
145+
| name | string | Name of the entity. |
146+
| acceleration | geometry_msgs::msg::Accel | Acceleration of the entity. |
114147

115148
### setAccelerationLimit
116149

117-
By using `API::setAccelerationLimit`, you can set the acceleration limit of the npc.
150+
By using `API::setAccelerationLimit`, you can set the acceleration limit of the entity.
118151

119-
| Value | Type | Description |
120-
| ------------ | ------ | ------------------------------ |
121-
| name | string | Name of the npc. |
122-
| acceleration | double | Acceleration limit of the npc. |
152+
| Value | Type | Description |
153+
| ------------ | ------ | --------------------------------- |
154+
| name | string | Name of the entity. |
155+
| acceleration | double | Acceleration limit of the entity. |
123156

124157
### setAccelerationRateLimit
125158

126-
By using `API::setAccelerationRateLimit`, you can set the acceleration rate limit of the npc.
159+
By using `API::setAccelerationRateLimit`, you can set the acceleration rate limit of the entity.
127160

128-
| Value | Type | Description |
129-
| ----------------- | ------ | ----------------------------------- |
130-
| name | string | Name of the npc. |
131-
| acceleration_rate | double | Acceleration rate limit of the npc. |
161+
| Value | Type | Description |
162+
| ----------------- | ------ | -------------------------------------- |
163+
| name | string | Name of the entity. |
164+
| acceleration_rate | double | Acceleration rate limit of the entity. |
132165

133166
### setDecelerationLimit
134167

135-
By using `API::setDecelerationLimit`, you can set the deceleration limit of the npc.
168+
By using `API::setDecelerationLimit`, you can set the deceleration limit of the entity.
136169

137-
| Value | Type | Description |
138-
| ------------ | ------ | ------------------------------ |
139-
| name | string | Name of the npc. |
140-
| deceleration | double | Deceleration limit of the npc. |
170+
| Value | Type | Description |
171+
| ------------ | ------ | --------------------------------- |
172+
| name | string | Name of the entity. |
173+
| deceleration | double | Deceleration limit of the entity. |
141174

142175
### setDecelerationRateLimit
143176

144-
By using `API::setDecelerationRateLimit`, you can set the deceleration rate limit of the npc.
177+
By using `API::setDecelerationRateLimit`, you can set the deceleration rate limit of the entity.
145178

146-
| Value | Type | Description |
147-
| ----------------- | ------ | ----------------------------------- |
148-
| name | string | Name of the npc. |
149-
| deceleration_rate | double | Deceleration rate limit of the npc. |
179+
| Value | Type | Description |
180+
| ----------------- | ------ | -------------------------------------- |
181+
| name | string | Name of the entity. |
182+
| deceleration_rate | double | Deceleration rate limit of the entity. |
150183

151184
### setVelocityLimit
152185

153-
By using `API::setVelocityLimit`, you can set the velocity limit of the npc.
186+
By using `API::setVelocityLimit`, you can set the velocity limit of the entity.
154187

155-
| Value | Type | Description |
156-
| --------------- | ------ | -------------------------- |
157-
| name | string | Name of the npc. |
158-
| linear_velocity | double | Velocity limit of the npc. |
188+
| Value | Type | Description |
189+
| --------------- | ------ | ----------------------------- |
190+
| name | string | Name of the entity. |
191+
| linear_velocity | double | Velocity limit of the entity. |

0 commit comments

Comments
 (0)