Guides¶

BeamNG Control¶

This guide describes the feature set of the beamng_control package. It connects ROS to the BeamNG.tech simulation platform and converts sensor information into ROS and, where appropriate, Rviz compatible ROS messages.

Starting the Node¶

To start the node a running instance of BeamNG.tech is needed that has been started through the BeamNGpy library. A list of compatible versions can be found on the home page or in the README.md.

Defining Scenarios¶

The BeamNG ROS Integration supports JSON-based scenario definition. Example files can be found in the beamng_control/config/scenarios/ directory.

General Setup¶

Scenarios are defined through JSON objects, here is a list of possible keys and values.

Key	Value Type	Value Specification	Entry Type
`"version"`	String	BeamnG ROS Integration version, f.ex. `1`	Mandatory
`"level"`	String	BeamNG.tech level name, f.ex. `"west_coast_usa"`.	Mandatory
`"mode"`	String	Value	Optional
`"vehicles"`	Array	At least one vehicle needs to be specified in order to obtain a valid scenario. See the table below for the Specification.	Mandatory
`"name"`	String	Name of the level.	Mandatory
`"time_of_day"`	Float	Value between `0` and `1` where the range `[0, .5]` corresponds to the times between 12 a.m. and 12 p.m. and `[.5], 1]` corresponds to the time range between 12 p.m. and 12 a.m.	Optional
`"weather_presets"`	String	Weather presets are level specific, ToDo	Optional

Vehicle Definition¶

Vehicles are also defined as JSON objects.

Key	Value Type	Value Specification	Entry Type
`"name"`	String	Name of the vehicle, used for identification	Mandatory
`"model"`	String	Name of the vehicle type, f.ex. `etk800`	Mandatory
`"position"`	Array	Array of 3 floats, specifying the `x`, `y`, and `x` position of the vehicle.	Mandatory
`"rotation"`	Array	Array of 4 floats, specifying the vehicle rotation quaternion.	Mandatory
`"sensors"`	Array	Array of JSON objects, specifying the vehicles sensor parameters.	Optional

Sensor Definition¶

Sensors are also defined with the help of JSON objects. To avoid redundancy, the sensor definition of complex sensors has been split into two parts, where the default values are stored in an extra JSON file. Default values can be overridden by adding them to the JSON object with a new value. All sensors automatically publish their data to the topic /beamng_control/<vehicle name>/<unique_sensor_id>.

Damage Sensor¶

Message type: beamng_msgs.msg.DamagSensor

Key	Value Type	Value Specification	Entry Type
`"type"`	String	`"Damage"`	Mandatory
`"name"`	String	Unique sensor id.	Mandatory

Timer¶

Message type: beamng_msgs.msg.TimeSensor

Key	Value Type	Value Specification	Entry Type
`"type"`	String	`"Timer"`	Mandatory
`"name"`	String	Unique sensor id.	Mandatory

GForces¶

Message type: beamng_msgs.msg.GForceSensor

Key	Value Type	Value Specification	Entry Type
`"type"`	String	`"GForces"`	Mandatory
`"name"`	String	Unique sensor id.	Mandatory

Electrics¶

Message type: beamng_msgs.msg.ElectricsSensor

Key	Value Type	Value Specification	Entry Type
`"type"`	String	`"Electrics"`	Mandatory
`"name"`	String	Unique sensor id.	Mandatory

Camera¶

Contrary to other sensors, the Camera sensor may publish to multiple topics. If the camera sensor is configured to collect color, depth, annotation, and instance data, it is published to the respective topics:

/beamng_control/<vehicle_id>/<camera_id>/color

/beamng_control/<vehicle_id>/<camera_id>/depth

/beamng_control/<vehicle_id>/<camera_id>/annotation

/beamng_control/<vehicle_id>/<camera_id>/instance

The message type for all topics is sensor_msgs.msg.Image. Note that although the bounding_box option is given, this feature is still under development and will automatically be disabled.

Key	Value Type	Value Specification	Entry Type
`"type"`	String	`"Camera.default"`	Mandatory
`"name"`	String	Unique sensor id.	Mandatory
`"position"`	Array	Array of 3 floats, specifying the `x`, `y`, and `x` position of the sensor.	Mandatory
`"orientation"`	Array	Array of 4 floats, specifying the vehicle rotation quaternion	Mandatory
`"resolution"`	Array	Tuple of ints, defining the `x` and `y` resolution of the resulting images.	Optional
`"fov"`	Integer	Camera field of view.	Optional
`"colour"`	Boolean	Dis-/Enables color image generation.	Optional
`"depth"`	Boolean	Dis-/Enables depth image generation.	Optional
`"annotation"`	Boolean	Dis-/Enables ground truth generation for object type annotation.	Optional
`"instance"`	Boolean	Dis-/Enables ground truth generation for instance annotation.	Optional
`"bounding_box"`	Boolean	This feature is not supoprted at the moment and will be automatically disabled.	Optional

Lidar¶

Message type: sensor_msgs.msg.PointCloud2

Key	Value Type	Value Specification	Entry Type
`"type"`	String	`"Lidar.default"`	Mandatory
`"name"`	String	Unique sensor id.	Mandatory
`"vertical_resolution"`	Integer	Vertical sensor resolution.	Mandatory
`"vertical_angle"`	Float	Vertical angle.	Mandatory
`"hz"`	Integer	Laser frequency.	Mandatory
`"angle"`	Integer		Mandatory
`"max_distance"`	Integer	Maximal distance for data collection.	Mandatory
`"visualized"`	Integer	Dis-/Enable in-simulation Lidar visualization.	Mandatory

Controlling the Simulation¶

Various services to control the state of the simulation are available.

Name	Type	Purpose
`/beamng_control/get_scenario_state`	`bng_msgs.msg.GetScenarioState.srv`	Determining the current state of the scenario.
`/beamng_control/start_scenario`	`bng_msgs.msg.StartScenario.srv`	Starting a loaded scenario.
`/beamng_control/pause`	`bng_msgs.msg.ChangeSmulationState.srv`	Pause the simulation.
`/beamng_control/resume`	`bng_msgs.msg.ChangeSmulationState.srv`	Resume the simulation.

While the simulation is paused, it can be advanced a given amount of steps through the action server:

Name	Type	Purpose
`/beamng_control/step`	`bng_msgs.msg.Step`	Determining the current state of the scenario.

Vehicle Creation and Control¶

Name	Type	Purpose
`/beamng_control/get_current_vehicles`	`beamng_msgs.srv.GetCurrentVehiclesInfo`	Get list of spawned vehicles.
`/beamng_control/spawn_vehicle`	`beamng_msgs.srv.SpawnVehicle`	Spawn new vehicle.
`/beamng_control/teleport_vehicle`	`beamng_msgs.srv.TeleportVehicle`	Teleport vehicle.

BeamNG Agent Control¶

This guide documents the feature set of the beamng_agent package. Its main purpose is to provide an interface to steer individual vehicles.

Starting the Node¶

For starting the node a running instance of BeamNG.tech is needed that has been started through the BeamNGpy library. Then a beamng_control node needs to be launched to start a scenario of your choice. After adjusting its parameter, the node can then be run by typing roslaunch beamng_agent example.launch.

Vehicle Control¶

The node establishes a connection to an already spawned vehicle in the simulation and subscribes to the beamng_agent/<vehicle_id>/control topic with message type beamng_msgs.msg.VehicleControl.

Field	Type	Definition
steering	`float32`	Rotation of the steering wheel, from -1.0 to 1.0.
throttle	`float32`	Intensity of the throttle, from 0.0 to 1.0.
brake	`float32`	Intensity of the brake, from 0.0 to 1.0.
parkingbrake	`float32`	Intensity of the parkingbrake, from 0.0 to 1.0.
clutch	`float32`	Clutch level, from 0.0 to 1.0.
gear	`int8`	Gear index, -1 equals backwards, 0 equals neutral, 1 to X equals Nth gear.