diff --git a/Docs/ros_installation.md b/Docs/ros_installation.md new file mode 100644 index 000000000..b457098c0 --- /dev/null +++ b/Docs/ros_installation.md @@ -0,0 +1,133 @@ +

ROS bridge installation

+ + * [__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 +

ROS melodic

+ + * __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 + +

a) apt-get ROS bridge

+ +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 +``` + +

b) Repository download

+ +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 +``` + +

ImportError: no module named CARLA

+ +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:/PythonAPI/ + +!!! 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:/PythonAPI/ +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. + +

Synchronous mode

+ +* 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. diff --git a/Docs/ros_topics_ref.md b/Docs/ros_topics_ref.md new file mode 100644 index 000000000..9b0425aa7 --- /dev/null +++ b/Docs/ros_topics_ref.md @@ -0,0 +1,187 @@ +

Supported features

+ +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 + +

CARLA ego vehicle

+ +`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). + +

CARLA infrastructure sensors

+ +`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). + +

Waypoint calculation

+ +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 + +

Synchronous mode

+ +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. + + +

Ego Vehicle

+ +
Sensors
+ +The ego vehicle sensors are provided via topics with prefix /carla/ego_vehicle/<sensor_topic> + +Currently the following sensors are supported: + +Publish GNSS location, collision events... + +| Sensor | Topic | Type | +| | -------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| __Camera__ | `/carla//camera/rgb//image_color` | [sensor_msgs.Image](http://docs.ros.org/api/sensor_msgs/html/msg/Image.html) | +| __Camera__ | `/carla//camera/rgb//camera_info` | [sensor_msgs.CameraInfo](http://docs.ros.org/api/sensor_msgs/html/msg/CameraInfo.html) | +| __Lidar__ | `/carla//lidar//point_cloud` | [sensor_msgs.PointCloud2](http://docs.ros.org/api/sensor_msgs/html/msg/PointCloud2.html) | +| __Radar__ | `/carla//radar//radar` | [ainstein_radar_msgs.RadarTargetArray](https://github.com/AinsteinAI/ainstein_radar/blob/master/ainstein_radar_msgs/msg/RadarTargetArray.msg) | +| __IMU__ | `/carla//imu` | [sensor_msgs.Imu](https://docs.ros.org/melodic/api/sensor_msgs/html/msg/Imu.html) | +| __GNSS__ | `/carla//gnss//fix` | [sensor_msgs.NavSatFix](http://docs.ros.org/api/sensor_msgs/html/msg/NavSatFix.html) | +| __Collision__ | `/carla//collision` | [carla_msgs.CarlaCollisionEvent](carla_msgs/msg/CarlaCollisionEvent.msg) | +|__Lane invasion__ | `/carla//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). + + +
Object sensor
+ +| 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, except the ego vehicle | + +
Control
+ +| Topic | Type | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | +| `/carla//vehicle_control_cmd` (subscriber) | [carla_msgs.CarlaEgoVehicleControl](carla_msgs/msg/CarlaEgoVehicleControl.msg) | +| `/carla//vehicle_control_cmd_manual` (subscriber) | [carla_msgs.CarlaEgoVehicleControl](carla_msgs/msg/CarlaEgoVehicleControl.msg) | +| `/carla//vehicle_control_manual_override` (subscriber) | [std_msgs.Bool](http://docs.ros.org/api/std_msgs/html/msg/Bool.html) | +| `/carla//vehicle_status` | [carla_msgs.CarlaEgoVehicleStatus](carla_msgs/msg/CarlaEgoVehicleStatus.msg) | +| `/carla//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//vehicle_control_cmd`) +2. Manual Mode (reading commands from `/carla//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//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//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//vehicle_status`. +Static information about the vehicle can be received via `/carla//vehicle_info` + +
Sensors
+ +| Topic | Type | +| ------------------------------------------- | -------------------------------------------------------------------------------- | +| `/carla//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. + +
Ackermann control
+ +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). + +

Other actors

+ +| 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 | + +

Status of CARLA

+ +| 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) | + +

Walkers

+ +| Topic | Type | Description | +| ---------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------ | +| `/carla/walker//walker_control_cmd` (subscriber) | [carla_msgs.CarlaWalkerControl](carla_msgs/msg/CarlaWalkerControl.msg) | Control a walker | +| `/carla/walker//odometry` | [nav_msgs.Odometry](http://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) | odometry of walker | + +

Other vehicles

+ +| Topic | Type | Description | +| ------------------------------ | ---------------------------------------------------------------------------- | ------------------- | +| `/carla/vehicle//odometry` | [nav_msgs.Odometry](http://docs.ros.org/api/nav_msgs/html/msg/Odometry.html) | odometry of vehicle | + +

Debug marker

+ +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 | diff --git a/Docs/start_quickstart.md b/Docs/start_quickstart.md index 3fddd1ec3..9f2d20337 100644 --- a/Docs/start_quickstart.md +++ b/Docs/start_quickstart.md @@ -2,6 +2,8 @@ * [Requirements](#requirements) * [Downloading CARLA](#downloading-carla) + * a) apt-get installation + * b) Repository download * [Running CARLA](#running-carla) * Command-line options * [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 +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. + +

a) apt-get CARLA 0.9.7

+ +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 +``` + +

b) Downloading the repository

+

@@ -58,6 +79,8 @@ Linux: Windows: 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. diff --git a/mkdocs.yml b/mkdocs.yml index ed7141f60..b92334142 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,9 @@ nav: - 'Create a sensor': 'tuto_D_create_sensor.md' - 'Make a release': 'tuto_D_make_release.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: - 'Contribution guidelines': 'cont_contribution_guidelines.md' - 'Code of conduct': 'cont_code_of_conduct.md'