First draft

This commit is contained in:
sergi-e 2020-02-24 16:40:57 +01:00 committed by Marc Garcia Puig
parent 2b29bc24ef
commit b27d5d10c3
4 changed files with 346 additions and 0 deletions

133
Docs/ros_installation.md Normal file
View File

@ -0,0 +1,133 @@
<h1>ROS bridge installation</h1>
* [__Requirements__](#requirements)
* [__Bridge installation__](#bridge-installation)
* a) apt-get ROS bridge
* b) Repository download
* Import error: No module named CARLA
* [__Run the ROS bridge__](#run-the-ros-bridge)
* [__Settings__](#settings)
The ROS bridge enables communication between ROS and CARLA so that both softwares can reach full potential by combining their features.
---------------
##Requirements
<h4>ROS melodic</h4>
* __ROS melodic:__ follow the official documentation to [install ROS](http://wiki.ros.org/melodic/Installation/Ubuntu).
* __CARLA:__ any version later than __XX__ should work properly. 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.
---------------
##Bridge installation
<h4>a) apt-get ROS bridge</h4>
First add the apt repository
```sh
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 81061A1A042F527D &&
sudo add-apt-repository "deb [trusted=yes] http://34.227.255.250/carla-ros-bridge-melodic/ bionic main"
```
Then simply install the ROS bridge:
```sh
sudo apt-get update &&
sudo apt-get install carla-ros-bridge
```
<h4>b) Repository download</h4>
In order to work use the ROS bridge, first create a catkin workspace, instal the ROS bridge in there and build it to be available:
```sh
#setup folder structure
mkdir -p ~/carla-ros-bridge/catkin_ws/src
cd ~/carla-ros-bridge
git clone https://github.com/carla-simulator/ros-bridge.git
cd catkin_ws/src
ln -s ../../ros-bridge
source /opt/ros/kinetic/setup.bash
cd ..
#install required ros-dependencies
rosdep update
rosdep install --from-paths src --ignore-src -r
#build
catkin_make
```
<h4>ImportError: no module named CARLA</h4>
The path to CARLA Python is missing. Please 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:<path/to/carla/>/PythonAPI/<your_egg_file>
!!! Note
_.egg_ files may be either in `/PythonAPI/` or `/PythonAPI/dist/` depending on the CARLA installation.
To check the installation, import CARLA from Python and wait for a sucess message:
```sh
python -c 'import carla;print("Success")'
```
---------------
##Run the ROS bridge
__1) run CARLA:__ the way to do so will depend on the the CARLA installation chosen, so here is a brief summary:
* __Quick start/release package:__ run `./CarlaUE4.sh` in `/carla/`.
* __apt-get installation:__ run `./CarlaUE4.sh` in `/opt/carla/bin/`.
* __Build installation:__ run `make launch` in `/carla/`.
__2) __ The way to do so will depend on the the CARLA installation chosen, so here is a brief summary:
```sh
export PYTHONPATH=$PYTHONPATH:<path/to/carla/>/PythonAPI/<your_egg_file>
source ~/carla-ros-bridge/catkin_ws/devel/setup.bash
```
__3) start the ROS bridge:__ use any of the different packages available that will serve to check if the bridge is running properly. Here are some suggestions:
```sh
# Option 1: start the ros bridge
roslaunch carla_ros_bridge carla_ros_bridge.launch
# Option 2: start the ros bridge together with RVIZ
roslaunch carla_ros_bridge carla_ros_bridge_with_rviz.launch
# Option 3: start the ros bridge together with an example ego vehicle
roslaunch carla_ros_bridge carla_ros_bridge_with_example_ego_vehicle.launch
```
---------------
##Settings
There is some configuration for CARLA available from the ROS bridge. This can be setup by editing the file: [`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:
* __Ego vehicle:__ the list in `/carla/ego_vehicle/rolename` sets role names to identify ego vehicles. These will be controllable from ROS and thus, relevant topics will be created.
* __Host/port:__ the network settings to connect to CARLA using a Python client.
* __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.
* __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 within the current frame. This might slow down the overall simulation but ensures reproducible results.
* __Wait for vehicle command:__ in synchronous mode, this boolean determines if a vehicle command should be received before executing the next tick.
!!! Warning
In synchronous mode, only the ros-bridge is allowed to tick. Other CARLA clients must passively wait.
<h4>Synchronous mode</h4>
* Pause/Play
* Execute single step
The following topic allows to control the stepping.
| Topic | Type |
| ---------------- | ----------------------- |
| `/carla/control` | carla_msgs.CarlaControl |
A CARLA [Control rqt plugin](https://github.com/carla-simulator/ros-bridge/blob/master/rqt_carla_control/README.md) is available to publish to the topic.

187
Docs/ros_topics_ref.md Normal file
View File

@ -0,0 +1,187 @@
<h1>Supported features</h1>
The ROS bridge enables communication between ROS and CARLA so that both softwares can reach full potential by combining their features.
* [__Listed features__](#listed-features)
* [__ROS packages__](#ros_packages)
* [__ROS topics__](#ros_topics)
---------------
##Listed features
* __Sensors:__
* Lidar.
* Cameras (depth, RGB and segmentation).
* __Messages:__
* Transform publications.
* Manual control using Ackerman msg.
* Marker/bounding box messages for cars/pedestirans.
* __Other:__
* Synchronous mode in CARLA.
* Handling ROS dependencies.
* Add traffic lights.
---------------
##ROS packages
<h4> CARLA ego vehicle </h4>
`carla_ego_vehicle` provides a generic way to spawn an ego vehicle and attach sensors to it. You can find further documentation [here](carla_ego_vehicle/README.md).
<h4> CARLA infrastructure sensors </h4>
`carla_infrastructure` provides a generic way to spawn a set of infrastructure sensors defined in a config file. You can find further documentation [here](carla_infrastructure/README.md).
<h4> Waypoint calculation </h4>
To make use of the Carla waypoint calculation a ROS Node is available to get waypoints. You can find further documentation [here](carla_waypoint_publisher/README.md).
---------------
##ROS topics
<h4> Synchronous mode </h4>
It is possible to control the simulation execution:
- Pause/Play
- Execute single step
The following topic allows to control the stepping.
| Topic | Type |
| ---------------- | ---------------------------------------------------------- |
| `/carla/control` | [carla_msgs.CarlaControl](carla_msgs/msg/CarlaControl.msg) |
A [CARLA Control rqt plugin](rqt_carla_control/README.md) is available to publish to the topic.
<h4> Ego Vehicle </h4>
<h5> Sensors </h5>
The ego vehicle sensors are provided via topics with prefix /carla/ego_vehicle/&lt;sensor_topic>
Currently the following sensors are supported:
Publish GNSS location, collision events...
| Sensor | Topic | Type |
| | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| __Camera__ | `/carla/<ROLE NAME>/camera/rgb/<SENSOR ROLE NAME>/image_color` | [sensor_msgs.Image](http://docs.ros.org/api/sensor_msgs/html/msg/Image.html) |
| __Camera__ | `/carla/<ROLE NAME>/camera/rgb/<SENSOR ROLE NAME>/camera_info` | [sensor_msgs.CameraInfo](http://docs.ros.org/api/sensor_msgs/html/msg/CameraInfo.html) |
| __Lidar__ | `/carla/<ROLE NAME>/lidar/<SENSOR ROLE NAME>/point_cloud` | [sensor_msgs.PointCloud2](http://docs.ros.org/api/sensor_msgs/html/msg/PointCloud2.html) |
| __Radar__ | `/carla/<ROLE NAME>/radar/<SENSOR ROLE NAME>/radar` | [ainstein_radar_msgs.RadarTargetArray](https://github.com/AinsteinAI/ainstein_radar/blob/master/ainstein_radar_msgs/msg/RadarTargetArray.msg) |
| __IMU__ | `/carla/<ROLE NAME>/imu` | [sensor_msgs.Imu](https://docs.ros.org/melodic/api/sensor_msgs/html/msg/Imu.html) |
| __GNSS__ | `/carla/<ROLE NAME>/gnss/<SENSOR ROLE NAME>/fix` | [sensor_msgs.NavSatFix](http://docs.ros.org/api/sensor_msgs/html/msg/NavSatFix.html) |
| __Collision__ | `/carla/<ROLE NAME>/collision` | [carla_msgs.CarlaCollisionEvent](carla_msgs/msg/CarlaCollisionEvent.msg) |
|__Lane invasion__ | `/carla/<ROLE NAME>/lane_invasion` | [carla_msgs.CarlaLaneInvasionEvent](carla_msgs/msg/CarlaLaneInvasionEvent.msg) |
!!! Note
Radar data can be visualized on rviz using [ainstein_radar_rviz_plugins](https://wiki.ros.org/ainstein_radar_rviz_plugins).
<h5> Object sensor </h5>
| Topic | Type | Description |
| ---------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `/carla/<ROLE NAME>/objects` | [derived_object_msgs.ObjectArray](http://docs.ros.org/api/derived_object_msgs/html/msg/ObjectArray.html) | all vehicles and walkers, except the ego vehicle |
<h5> Control </h5>
| Topic | Type |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| `/carla/<ROLE NAME>/vehicle_control_cmd` (subscriber) | [carla_msgs.CarlaEgoVehicleControl](carla_msgs/msg/CarlaEgoVehicleControl.msg) |
| `/carla/<ROLE NAME>/vehicle_control_cmd_manual` (subscriber) | [carla_msgs.CarlaEgoVehicleControl](carla_msgs/msg/CarlaEgoVehicleControl.msg) |
| `/carla/<ROLE NAME>/vehicle_control_manual_override` (subscriber) | [std_msgs.Bool](http://docs.ros.org/api/std_msgs/html/msg/Bool.html) |
| `/carla/<ROLE NAME>/vehicle_status` | [carla_msgs.CarlaEgoVehicleStatus](carla_msgs/msg/CarlaEgoVehicleStatus.msg) |
| `/carla/<ROLE NAME>/vehicle_info` | [carla_msgs.CarlaEgoVehicleInfo](carla_msgs/msg/CarlaEgoVehicleInfo.msg) |
There are two modes to control the vehicle.
1. Normal Mode (reading commands from `/carla/<ROLE NAME>/vehicle_control_cmd`)
2. Manual Mode (reading commands from `/carla/<ROLE NAME>/vehicle_control_cmd_manual`)
This allows to manually override a Vehicle Control Commands published by a software stack. You can toggle between the two modes by publishing to `/carla/<ROLE NAME>/vehicle_control_manual_override`.
[carla_manual_control](carla_manual_control/) makes use of this feature.
For testing purposes, you can stear the ego vehicle from the commandline by publishing to the topic `/carla/<ROLE NAME>/vehicle_control_cmd`.
Examples for a ego vehicle with role_name 'ego_vehicle':
Max forward throttle:
rostopic pub /carla/ego_vehicle/vehicle_control_cmd carla_msgs/CarlaEgoVehicleControl "{throttle: 1.0, steer: 0.0}" -r 10
Max forward throttle with max steering to the right:
rostopic pub /carla/ego_vehicle/vehicle_control_cmd carla_msgs/CarlaEgoVehicleControl "{throttle: 1.0, steer: 1.0}" -r 10
The current status of the vehicle can be received via topic `/carla/<ROLE NAME>/vehicle_status`.
Static information about the vehicle can be received via `/carla/<ROLE NAME>/vehicle_info`
<h6> Sensors </h6>
| Topic | Type |
| ------------------------------------------- | -------------------------------------------------------------------------------- |
| `/carla/<ROLE NAME>/twist_cmd` (subscriber) | [geometry_msgs.Twist](http://docs.ros.org/api/geometry_msgs/html/msg/Twist.html) |
CAUTION: This control method does not respect the vehicle constraints. It allows movements impossible in the real world, like flying or rotating.
You can also control the vehicle via publishing linear and angular velocity within a Twist datatype.
Currently this method applies the complete linear vector, but only the yaw from angular vector.
<h6> Ackermann control </h6>
In certain cases, the [Carla Control Command](carla_msgs/msg/CarlaEgoVehicleControl.msg) is not ideal to connect to an AD stack.
Therefore a ROS-based node `carla_ackermann_control` is provided which reads [AckermannDrive](http://docs.ros.org/api/ackermann_msgs/html/msg/AckermannDrive.html) messages.
You can find further documentation [here](carla_ackermann_control/README.md).
<h4> Other actors </h4>
| Topic | Type | Description |
| ------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `/carla/objects` | [derived_object_msgs.ObjectArray](http://docs.ros.org/api/derived_object_msgs/html/msg/ObjectArray.html) | all vehicles and walkers |
| `/carla/marker` | [visualization_msgs.Marker](http://docs.ros.org/api/visualization_msgs/html/msg/Marker.html) | visualization of vehicles and walkers |
| `/carla/actor_list` | [carla_msgs.CarlaActorList](carla_msgs/msg/CarlaActorList.msg) | list of all carla actors |
| `/carla/traffic_lights` | [carla_msgs.CarlaTrafficLightStatusList](carla_msgs/msg/CarlaTrafficLightStatusList.msg) | list of all traffic lights with their status |
<h4> Status of CARLA </h4>
| Topic | Type | Description |
| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
| `/carla/status` | [carla_msgs.CarlaStatus](carla_msgs/msg/CarlaStatus.msg) | |
| `/carla/world_info` | [carla_msgs.CarlaWorldInfo](carla_msgs/msg/CarlaWorldInfo.msg) | Info about the CARLA world/level (e.g. OPEN Drive map) |
<h4> Walkers </h4>
| Topic | Type | Description |
| ---------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------ |
| `/carla/walker/<ID>/walker_control_cmd` (subscriber) | [carla_msgs.CarlaWalkerControl](carla_msgs/msg/CarlaWalkerControl.msg) | Control a walker |
| `/carla/walker/<ID>/odometry` | [nav_msgs.Odometry](http://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) | odometry of walker |
<h4> Other vehicles </h4>
| Topic | Type | Description |
| ------------------------------ | ---------------------------------------------------------------------------- | ------------------- |
| `/carla/vehicle/<ID>/odometry` | [nav_msgs.Odometry](http://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) | odometry of vehicle |
<h4> Debug marker </h4>
It is possible to draw markers in CARLA.
Caution: Markers might affect the data published by sensors.
The following markers are supported in 'map'-frame:
- Arrow (specified by two points)
- Points
- Cube
- Line Strip
| Topic | Type | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------- |
| `/carla/debug_marker` (subscriber) | [visualization_msgs.MarkerArray](http://docs.ros.org/api/visualization_msgs/html/msg/MarkerArray.html) | draw markers in CARLA world |

View File

@ -2,6 +2,8 @@
* [Requirements](#requirements) * [Requirements](#requirements)
* [Downloading CARLA](#downloading-carla) * [Downloading CARLA](#downloading-carla)
* a) apt-get installation
* b) Repository download
* [Running CARLA](#running-carla) * [Running CARLA](#running-carla)
* Command-line options * Command-line options
* [Updating CARLA](#updating-carla) * [Updating CARLA](#updating-carla)
@ -25,6 +27,25 @@ If you have [pip](https://pip.pypa.io/en/stable/installing/) in your system, you
--- ---
## Downloading CARLA ## Downloading CARLA
There is an __apt repository__ for CARLA 0.9.7. This is the easiest way to get that release in Linux.
To get another release in Linux or install CARLA in Windows: __download the repository__.
Both methods will set CARLA ready to run.
<h4>a) apt-get CARLA 0.9.7</h4>
First, add the repository to the system:
```sh
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys DB53A429E64554FC &&
sudo add-apt-repository "deb [trusted=yes] http://34.227.255.250/carla-0.9.7/ bionic main"
```
Then, simply install it. CARLA will be in the `/opt/` folder, where other software such as ROS install themselves:
```sh
sudo apt-get update
sudo apt-get install carla
```
<h4>b) Downloading the repository</h4>
<div class="build-buttons"> <div class="build-buttons">
<p> <p>
<a href="https://github.com/carla-simulator/carla/blob/master/Docs/download.md" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release"> <a href="https://github.com/carla-simulator/carla/blob/master/Docs/download.md" target="_blank" class="btn btn-neutral" title="Go to the latest CARLA release">
@ -58,6 +79,8 @@ Linux:
Windows: Windows:
CarlaUE4.exe CarlaUE4.exe
``` ```
!!! Important
In the __apt-get__ installation, `CarlaUE4.sh` can be found in `/opt/carla/bin/`, instead of the main `/carla/` folder where it normally is.
A window will open, containing a view over the city. This is the "spectator" view. To fly around the city use the mouse and WASD keys (while clicking). The simulator is now running as a server, waiting for a client app to connect and interact with the world. A window will open, containing a view over the city. This is the "spectator" view. To fly around the city use the mouse and WASD keys (while clicking). The simulator is now running as a server, waiting for a client app to connect and interact with the world.

View File

@ -51,6 +51,9 @@ nav:
- 'Create a sensor': 'tuto_D_create_sensor.md' - 'Create a sensor': 'tuto_D_create_sensor.md'
- 'Make a release': 'tuto_D_make_release.md' - 'Make a release': 'tuto_D_make_release.md'
- 'Generate pedestrian navigation': 'tuto_D_generate_pedestrian_navigation.md' - 'Generate pedestrian navigation': 'tuto_D_generate_pedestrian_navigation.md'
- ROS bridge:
- 'ROS bridge installation': 'ros_installation.md'
- 'Supported features': 'ros_topics_ref.md'
- Contributing: - Contributing:
- 'Contribution guidelines': 'cont_contribution_guidelines.md' - 'Contribution guidelines': 'cont_contribution_guidelines.md'
- 'Code of conduct': 'cont_code_of_conduct.md' - 'Code of conduct': 'cont_code_of_conduct.md'