From d5e96c539f2a2fe9494dbb313c9f8a1a0058bf4d Mon Sep 17 00:00:00 2001 From: sergi-e Date: Fri, 6 Mar 2020 12:41:54 +0100 Subject: [PATCH] New iteration on release comments --- Docs/index.md | 4 +-- Docs/ros_installation.md | 30 ++++++++++----------- Docs/ros_launchs.md | 30 ++++++++++----------- Docs/ros_msgs.md | 56 ++++++++++++++++++++-------------------- Docs/start_quickstart.md | 4 +-- mkdocs.yml | 1 - 6 files changed, 62 insertions(+), 63 deletions(-) diff --git a/Docs/index.md b/Docs/index.md index c85031423..92ef85971 100644 --- a/Docs/index.md +++ b/Docs/index.md @@ -138,11 +138,11 @@ CARLA forum CARLA messages reference - — Contains explanations and fields for every type of CARLA message available from ROS. + — Contains explanations and fields for every type of CARLA message available in ROS. Launchfiles reference - — Explains the launchfiles provided, its nodes and the topics these are publishing and subscribed to. + — Explains the launchfiles provided, its nodes, and the topics that are being consumed and published. ## Tutorials — General

diff --git a/Docs/ros_installation.md b/Docs/ros_installation.md index c7765f6d2..ea260877f 100644 --- a/Docs/ros_installation.md +++ b/Docs/ros_installation.md @@ -5,19 +5,19 @@ * a) using apt repository * b) using source repository * [__Run the ROS bridge__](#run-the-ros-bridge) - * Import error: No module named CARLA + * Solving ImportError: No module named CARLA * [__Setting CARLA__](#setting-carla) The ROS bridge enables two-way communication between ROS and CARLA. -In order to do so, the information from the CARLA server is translated to ROS topics. For example, the information retrieved by sensors is structured to fit ROS structure. -And also vice versa, the messages sent between nodes in ROS get translated to commands to be applied in CARLA. This is commonly used to update the state of a vehicle and apply controllers. +In order to do so, the information from the CARLA server is translated to ROS topics. For example, the information retrieved by sensors is structured to fit ROS messages. +In the same way, the messages sent between nodes in ROS get translated to commands to be applied in CARLA. This is commonly used to update the state of a vehicle and apply controllers. --- ## Requirements #### ROS melodic - * __ROS Kinetic/Melodic:__ follow the official documentation to [install ROS](http://wiki.ros.org/melodic/Installation/Ubuntu). Some ROS packages could be necessary, depending on the user needs, such as [rviz](https://wiki.ros.org/ainstein_radar_rviz_plugins) to visualize ROS data. - * __CARLA 0.9.7:__ only this and later versions are supported. Follow the [quick start installation](../getting_started/quickstart) or make the build for the corresponding platform. + * __ROS Kinetic/Melodic:__ follow the official documentation to [install ROS](http://wiki.ros.org/melodic/Installation/Ubuntu). Some ROS packages may be required, depending on the user needs, such as [rviz](https://wiki.ros.org/ainstein_radar_rviz_plugins) to visualize ROS data. + * __CARLA 0.9.7:__ previous versions are not compatible with the ROS bridge. Follow the [quick start installation](../getting_started/quickstart) or make the build for the corresponding platform. !!! Important Make sure that both CARLA and ROS work properly before continuing with the installation. @@ -49,7 +49,7 @@ sudo apt install carla-ros-bridge- #### b) Using source repository -In order to use the ROS bridge a catkin workspace is needed. The ROS bridge should be cloned and built in there to be available. +In order to use the ROS bridge, a catkin workspace is needed. It should be cloned and built in there. The following fragment creates a new workspace and clones the repository in there. ```sh #setup folder structure @@ -91,7 +91,7 @@ source ~/carla-ros-bridge/catkin_ws/devel/setup.bash ``` !!! Important - The source path can be added to environment to be set permanently, but it will cause conflict when working with another workspace. + The source path can be added to the environment to be set permanently, but it will cause conflict when working with another workspace. __3) start the ROS bridge:__ use any of the different launch files available that will serve to check if the bridge is running properly. Here are some suggestions: @@ -106,9 +106,9 @@ roslaunch carla_ros_bridge carla_ros_bridge_with_rviz.launch roslaunch carla_ros_bridge carla_ros_bridge_with_example_ego_vehicle.launch ``` -#### ImportError: no module named CARLA +#### Solving ImportError: no module named CARLA -The path to CARLA Python is missing. The apt installation does this automatically, but it may be missing for other installations. Execute the following command with the complete path to the _.egg_ file (included). Use the one, that is supported by the Python version installed: +The path to CARLA Python is missing. The apt installation does this automatically, but it may be missing for other installations. Execute the following command with the complete path to the _.egg_ file (included). Use the one that, is supported by the Python version installed: export PYTHONPATH=$PYTHONPATH:/PythonAPI/ @@ -123,25 +123,25 @@ python -c 'import carla;print("Success")' --- ## Setting CARLA -There is some configuration for CARLA available from the ROS bridge. This can be setup by editing the file: [`share/carla_ros_bridge/config/settings.yaml`](https://github.com/carla-simulator/ros-bridge/blob/master/carla_ros_bridge/config/settings.yaml). +Settings can be changed, in order to modify the way CARLA works along with the ROS bridge, by editing the file: [`share/carla_ros_bridge/config/settings.yaml`](https://github.com/carla-simulator/ros-bridge/blob/master/carla_ros_bridge/config/settings.yaml). The parameters available refer to: * __Host/port:__ the network settings to connect to CARLA using a Python client. * __Synchronous mode:__ * __If false (default):__ data is published on every `world.on_tick()` and every `sensor.listen()` callbacks. - * __If true:__ the bridge waits for all sensor data that is expected before the next tick. This might slow down the overall simulation but ensures reproducible results. -* __Wait for vehicle command:__ in synchronous mode, pauses the tick until a vehicle control is completted. + * __If true:__ the bridge waits for all the sensor messages expected before the next tick. This might slow down the overall simulation but ensures reproducible results. +* __Wait for vehicle command:__ in synchronous mode, pauses the tick until a vehicle control is completed. * __Simulation time-step:__ simulation time (delta seconds) between simulation steps. __It must be lower than 0.1__. Take a look at the [documentation](../simulation_time_and_synchrony) to learn more about this. -* __Role names for the Ego vehicles:__ a role names to identify ego vehicles. These will be controllable from ROS and thus, relevant topics will be created. +* __Role names for the Ego vehicles:__ role names to identify ego vehicles. These will be controllable from ROS and thus, relevant topics will be created. !!! Warning - In synchronous mode, only the ros-bridge is allowed to tick. Other CARLA clients must passively wait. + In synchronous mode only the ros-bridge is allowed to tick. Other CARLA clients must passively wait. #### Synchronous mode -The following topic allows to control the stepping when in synchronous mode: +The following topic allows to control the step update when in synchronous mode: | Topic | Message type | | ---------------- | ----------------------- | diff --git a/Docs/ros_launchs.md b/Docs/ros_launchs.md index 8ea933c4b..4cd26642f 100644 --- a/Docs/ros_launchs.md +++ b/Docs/ros_launchs.md @@ -3,7 +3,7 @@ --- ## carla_ackermann_control.launch -Creates a node to manage a vehicle using Ackermann controls instead of the CARLA control messages when these are not ideal to connect an AD stack. The node reads the vehicle info from CARLA and uses it to define the controller. A simple Python PID is used to adjust acceleration/velocity. It can be installed using: +Creates a node to manage a vehicle using Ackermann controls instead of the CARLA control messages. The node reads the vehicle info from CARLA and uses it to define the controller. A simple Python PID is used to adjust acceleration/velocity. It can be installed using: ```sh pip install --user simple-pid ``` @@ -32,7 +32,7 @@ Speed is in __m/s__, steering angle is driving angle (not wheel angle) in __radi --- ## carla_ego_vehicle.launch -Spawns an ego vehicle (`role-name="ego_vehicle"`) with the argument `sensor_definition_file` being this the location of a __.json__ file describing sensors attached to the vehicle. The format for this file is explained [here](https://github.com/carla-simulator/ros-bridge/tree/master/carla_ego_vehicle). +Spawns an ego vehicle (`role-name="ego_vehicle"`). To describe the sensors attached to the vehicle, the `sensor_definition_file argument` is used. This contains the location of a __.json__ file describing sensors attached to the vehicle. The format for this file is explained [here](https://github.com/carla-simulator/ros-bridge/tree/master/carla_ego_vehicle). To spawn the vehicle at a specific location, publish in: `/carla/ego_vehicle/initialpose` or use __RVIZ__ and select a position with: __2D Pose estimate__. @@ -46,7 +46,7 @@ Spawns an ego vehicle with sensors attached and waits for world information. --- ## carla_example_ego_vehicle.launch -As [carla_ego_vehicle.launch](#carla-ego-vehicle-launch), spawns an ego vehicle (`role-name="ego_vehicle"`), only this uses a provided file to pass the sensors attached to the vehicle. Said file can be found in: `share/carla_ego_vehicle/config/sensors.json`. +Based on [carla_ego_vehicle.launch](#carla-ego-vehicle-launch), spawns an ego vehicle (`role-name="ego_vehicle"`) using a provided file describing the sensors. Said file can be found in: `share/carla_ego_vehicle/config/sensors.json`.

carla_ego_vehicle_ego_vehicle (Node)

@@ -71,7 +71,7 @@ Spawns the infrastructure sensors passed as arguments. --- ## carla_ros_bridge.launch -Creates a node with some basic communication between CARLA and ROS. +Creates a node with some basic communications between CARLA and ROS.

carla_ros_bridge (Node)

@@ -134,12 +134,12 @@ Speed is in __m/s__, steering angle is driving angle (not wheel angle) in __radi --- ## carla_ros_bridge_with_example_ego_vehicle.launch -Spawns an ego vehicle with sensors attached and starts communication between CARLA and ROS sharing current simulation state, sensor and ego vehicle data. +Spawns an ego vehicle with sensors attached and starts communications between CARLA and ROS sharing current simulation state, sensor and ego vehicle data. The ego vehicle is set ready to be used in manual control.

carla_ros_bridge (Node)

-This node is in charge of most of the communication between CARLA and ROS for both the current state of the simulation, traffic lights, vehicle controllers and sensor data. +This node is in charge of most of the communications between CARLA and ROS for both the current state of the simulation, traffic lights, vehicle controllers and sensor data.

Subscribed to:

* /carla/debug_marker — [visualization_msgs.MarkerArray](http://docs.ros.org/melodic/api/visualization_msgs/html/msg/MarkerArray.html) @@ -172,7 +172,7 @@ This node is in charge of most of the communication between CARLA and ROS for bo

/carla_manual_control_ego_vehicle (Node)

-Retrieves from CARLA information regarding the ego vehicle. Uses keyboard input to publish messages containing the controller data to manage the ego vehicle. +Retrieves information from CARLA regarding the ego vehicle. Uses keyboard input to publish messages containing the controller data to manage the ego vehicle. The information retrieved includes both static and current state, the sensor data registered on every step and the general settings of the simulation.

Subscribed to:

@@ -204,10 +204,10 @@ Spawns an ego vehicle with sensors attached and waits for world information. --- ## carla_ros_bridge_with_rviz.launch -Starts some basic communication between CARLA and ROS and launches an instance of RVIZ ready to retrieve Lidar data. +Starts some basic communications between CARLA and ROS and launches an instance of RVIZ ready to retrieve Lidar data.

carla_ros_bridge (Node)

-Shares information between CARLA and ROS regarding the curent simulation state. +Shares information between CARLA and ROS regarding the current simulation state.

Subscribed to:

@@ -237,14 +237,14 @@ Runs an instance of RVIZ waiting for Lidar data. A ROS version of the CARLA script `manual_control.py` that receives and manages the information using ROS topics. It has some prerequisites: -* To display an image: a camera with role-name 'view' and resolution 800x600 -* To display the position: a gnss sensor with role-name 'gnss1' +* To display an image: a camera with role-name 'view' and resolution 800x600. +* To display the position: a gnss sensor with role-name 'gnss1'. * To detect other sensor data: the corresponding sensor.

/carla_manual_control_ego_vehicle (Node)

-Retrieves from CARLA information regarding the ego vehicle. Uses keyboard input to publish messages containing the controller data to manage the ego vehicle. +Retrieves information from CARLA regarding the ego vehicle. Uses keyboard input to publish messages containing the controller data to manage the ego vehicle. The information retrieved includes both static and current state, the sensor data registered on every step and the general settings of the simulation. @@ -288,7 +288,7 @@ export PYTHONPATH=/PythonAPI/carla/dist/carla-.

carla_ros_bridge (Node)

-This node is in charge of most of the communication between CARLA and ROS for both the current state of the simulation, traffic lights, vehicle controllers and sensor data. +This node is in charge of most of the communications between CARLA and ROS for both the current state of the simulation, traffic lights, vehicle controllers and sensor data.

Subscribed to:

@@ -322,7 +322,7 @@ This node is in charge of most of the communication between CARLA and ROS for bo

/carla_manual_control_ego_vehicle (Node)

-Retrieves from CARLA information regarding the ego vehicle. Uses keyboard input to publish messages containing the controller data to manage the ego vehicle. +Retrieves information from CARLA regarding the ego vehicle. Uses keyboard input to publish messages containing the controller data to manage the ego vehicle. The information retrieved includes both static and current state, the sensor data registered on every step and the general settings of the simulation.

Subscribed to:

@@ -384,7 +384,7 @@ export PYTHONPATH=$PYTHONPATH:/PythonAPI/carla-

/carla_waypoint_publisher (Node)

-Uses the current pose of the ego vehicle with role-name `ego_vehicle` as starting point. If the vehicle is respawned or moved, the route is newly calculated. +Uses the current pose of the ego vehicle with role-name `ego_vehicle` as starting point. If the vehicle is respawned or moved, the route is calculated again.

Subscribed to:

diff --git a/Docs/ros_msgs.md b/Docs/ros_msgs.md index 6bd700bef..1b21b50e8 100644 --- a/Docs/ros_msgs.md +++ b/Docs/ros_msgs.md @@ -1,6 +1,6 @@ # CARLA messages reference -The following reference lists all the CARLA messages available in the ROS bridge. These will can be used to enable communication in both ways. +The following reference lists all the CARLA messages available in the ROS bridge. These can be used to enable communication in both ways. Any doubts regarding these messages or the CARLA-ROS bridge can be solved in the forum:
@@ -61,23 +61,23 @@ These messages are used to control the simulation while in synchronous mode. The --- ## CarlaEgoVehicleControl.msg -Messages sent to apply a control to a vehicle in both modes, normal and manual. These are published in a stack. +Messages sent to apply a control to a vehicle in both modes, autopilot and manual. These are published in a stack. | Field | Type | Description | | ------------------- | ------- | ----------- | | `header` | [Header](http://docs.ros.org/melodic/api/std_msgs/html/msg/Header.html) | Time stamp and frame ID when the message is published. | -| `throttle` | float32 | Scalar value to cotrol the vehicle throttle: __[0.0,1.0]__ | -| `steer` | float32 | Scalar value to control the vehicle steering direction: __[-1.0,1.0]__ to control the vehicle steering | -| `brake` | float32 | Scalar value to control the vehicle brakes: __[0.0,1.0]__ | -| `hand_brake` | bool | If true, the hand brake is enabled. | -| `reverse` | bool | If true, the vehicle will move reverse. | +| `throttle` | float32 | Scalar value to cotrol the vehicle throttle: __[0.0, 1.0]__ | +| `steer` | float32 | Scalar value to control the vehicle steering direction: __[-1.0, 1.0]__ to control the vehicle steering | +| `brake` | float32 | Scalar value to control the vehicle brakes: __[0.0, 1.0]__ | +| `hand_brake` | bool | If __True__, the hand brake is enabled. | +| `reverse` | bool | If __True__, the vehicle will move reverse. | | `gear` | int32 | Changes between the available gears in a vehicle. | -| `manual_gear_shift` | bool | If ture, the gears will be shifted using `gear`. | +| `manual_gear_shift` | bool | If __True__, the gears will be shifted using `gear`. | --- ## CarlaEgoVehicleInfo.msg -Contains some static information regarding a vehicle, mostly the attributes that used to define its physics. +Contains some static information regarding a vehicle, mostly the attributes used to define the vehicle's physics. | Field | Type | Description | | --------------------------------------------- | ------------------------------------------------------- | ----------- | @@ -90,9 +90,9 @@ Contains some static information regarding a vehicle, mostly the attributes that | `damping_rate_full_throttle` | float32 | Damping rate when the throttle is at maximum. | | `damping_rate_zero_throttle_clutch_engaged` | float32 | Damping rate when the throttle is zero with clutch engaged. | | `damping_rate_zero_throttle_clutch_disengaged`| float32 | Damping rate when the throttle is zero with clutch disengaged. | -| `use_gear_autobox` | bool | If true, the vehicle will have an automatic transmission. | +| `use_gear_autobox` | bool | If __True__, the vehicle will have an automatic transmission. | | `gear_switch_time` | float32 | Switching time between gears. | -| `clutch_strength` | float32 | The clutch strength of the vehicle. Measured in Kgm^2/s. | +| `clutch_strength` | float32 | The clutch strength of the vehicle. Measured in __Kgm^2/s__. | | `mass` | float32 | The mass of the vehicle measured in Kg. | | `drag_coefficient` | float32 | Drag coefficient of the vehicle's chassis. | | `center_of_mass` | geometry_msgs/Vector3 | The center of mass of the vehicle. | @@ -150,7 +150,7 @@ Details for a test scenario. --- ## CarlaScenarioList.msg -Contains a list a series of test scenarios to run in ScenarioRunner. +Contains a list of test scenarios to run in ScenarioRunner. | Field | Type | Description | | ----------- | ------------------------------------ | ---------------------- | @@ -174,8 +174,8 @@ Details the current world settings of the simulation. | -------------------------- | ------- | ------------------------------------------------------------- | | `frame` | uint64 | Current frame number. | | `fixed_delta_seconds` | float32 | Simulation time between last and current step. | -| `synchronous_mode` | bool | If true, synchronous mode is enabled. | -| `synchronous_mode_running` | bool | True when the simulation is running. False when it is paused. | +| `synchronous_mode` | bool | If __True__, synchronous mode is enabled. | +| `synchronous_mode_running` | bool | __True__ when the simulation is running. __False__ when it is paused. | --- ## CarlaTrafficLightStatus.msg @@ -205,12 +205,12 @@ Contains the information needed to apply a movement controller to a walker. | ----------- | ---------------------- | ----------------------------- | | `direction` | geometry_msgs/Vector3 | Vector that controls the direction of the walker. | | `speed` | float32 | A scalar value to control the walker's speed. | -| `jump` | bool | If true, the walker will jump. | +| `jump` | bool | If __True__, the walker will jump. | --- ## CarlaWaypoint.msg -Summarizes data regarding a waypoint. +Summarizes data contained in a waypoint. | Field | Type | Description | | ------------- | ------------------ | ----------------------------- | @@ -233,7 +233,7 @@ Information about the current CARLA map (name and OpenDRIVE). --- ## EgoVehicleControlCurrent.msg -Represents the current time and the speed and acceleration values of the vehicle used by the controller. It is part of a `Carla_Ackermann_Control.EgoVehicleControlInfo.msg` message. +Represents the current time, speed and acceleration values of the vehicle used by the controller. It is part of a `Carla_Ackermann_Control.EgoVehicleControlInfo.msg` message. | Field | Type | Description | | ----------- | -------- | ----------------------------- | @@ -260,7 +260,7 @@ Contains all the current values used within an Ackermann controller. These messa --- ## EgoVehicleControlMaxima.msg -Represents the maximum values that restrict the controller. It is part of a `Carla_Ackermann_Control.EgoVehicleControlInfo.msg` message. +Represents the restrictions of a controller (limit values). It is part of a `Carla_Ackermann_Control.EgoVehicleControlInfo.msg` message. | Field | Type | Description | | -------------------- | -------- | ----------------------------- | @@ -269,7 +269,7 @@ Represents the maximum values that restrict the controller. It is part of a `Car | `max_accel` | float32 | Max. acceleration for a vehicle. | | `max_decel` | float32 | Max. deceleration for a vehicle. Default: __8 m/s^2__ | | `min_accel` | float32 | Min. acceleration for a vehicle. When the Ackermann taget accel. exceeds this value, the input accel. is controlled. | -| `max_pedal` | float32 | ??? |