DOCSEARCHbyAlgolia
Submit Docs

BeamNGpy Documentation

repository·master·Indexed 18 days ago

https://github.com/beamng/beamngpy

Official Python API for BeamNG.tech designed for research and industry applications. It provides remote control of vehicles, AI configuration, and access to high-fidelity sensor data including cameras, lidar, IMU, radar, and ultrasonic sensors. Key features include scenario control, road network access, multi-client support for multi-agent scenarios, and tools for exporting maps as .xodr OpenDRIVE files.

Tokens
22.8K
Snippets
71
Records
99
Agent score
63%

What's inside BeamNGpy

  1. BeamNGpy Core Features Overview

    master

    BeamNGpy provides a Python API to interact with BeamNG.tech. Key capabilities include:

    • Remote Control of Vehicles: Individually control steering, throttle, lights, and gear shifting for specific vehicles.
    • AI-controlled Vehicles: Configure and control BeamNG.tech's built-in AI to follow waypoints, follow other vehicles, span the map, or follow user-defined trajectories.
    • Dynamic Sensor Models: Access simulated sensor data including:
      • Cameras: Color, Depth, Semantic, and Instance annotations (with optional noise simulation).
      • Lidars (with optional noise simulation).
      • IMU (Inertial Measurement Units).
      • Ultrasonic Distance Measurements.
    • Road Network & Scenario Access: Access road geometry and active scene objects (vehicles/objects) for analysis.
    • Multiple Clients: Multiple BeamNGpy processes can connect to a single running BeamNG.tech instance, allowing for multi-agent scenarios where each client controls a different vehicle.

  3. Use Automated Sensors for perception tasks

    master

    BeamNGpy provides several high-level automated sensor classes for simulating perception systems. These include:

    • beamngpy.sensors.Camera: Visual data.
    • beamngpy.sensors.Lidar: Point cloud data.
    • beamngpy.sensors.Radar and beamngpy.sensors.IdealRadar: Radar-based detection.
    • beamngpy.sensors.Ultrasonic: Proximity sensing.
    • beamngpy.sensors.GPS: Global positioning.
    • beamngpy.sensors.PowertrainSensor: Vehicle powertrain data.
    • beamngpy.sensors.AdvancedIMU: Inertial measurement data.
    • beamngpy.sensors.RoadsSensor: Information about the road network.

  4. Use Classical Sensors for low-level vehicle data

    master

    For direct access to vehicle telemetry and state, use the classical sensor classes:

    • beamngpy.sensors.Sensor: Base sensor class.
    • beamngpy.sensors.State: General vehicle state.
    • beamngpy.sensors.Electrics: Electrical system data.
    • beamngpy.sensors.Damage: Vehicle damage information.
    • beamngpy.sensors.GForces: Acceleration/G-force data.
    • beamngpy.sensors.Timer: Timing information.
    • beamngpy.sensors.Logging: Log-based data.

  6. Manage Scenarios and Levels

    master

    To orchestrate simulation environments, use the following classes:

    • beamngpy.Scenario: Defines the logic and flow of a simulation scenario.
    • beamngpy.Level: Represents the simulation environment/map.
    • beamngpy.ScenarioObject: Represents objects that exist within a scenario.

  8. Quickstart: Run a basic scenario with BeamNGpy

    master

    To use BeamNGpy, you must have BeamNG.tech installed. You can specify the path to the BeamNG.tech installation and its user folder during the initialization of the BeamNGpy object.

    This example demonstrates how to:

    1. Initialize the BeamNGpy instance.
    2. Open the simulator.
    3. Create a Scenario on the 'west_coast_usa' map.
    4. Add a Vehicle (ETK800) to the scenario at a specific position and rotation.
    5. Load and start the scenario.
    6. Control the vehicle's AI to 'traffic' mode.
    7. Disconnect from the simulator.
    from beamngpy import BeamNGpy, Scenario, Vehicle

# Instantiate BeamNGpy instance running the simulator from the given path,
# communicating over localhost:25252
bng = BeamNGpy('localhost', 25252, home='/path/to/bng/tech', user='/path/to/bng/tech/userfolder')

# Launch BeamNG.tech
bng.open()

# Create a scenario in west_coast_usa called 'example'
scenario = Scenario('west_coast_usa', 'example')

# Create an ETK800 with the licence plate 'PYTHON'
vehicle = Vehicle('ego_vehicle', model='etk800', license='PYTHON')

# Add it to our scenario at this position and rotation
scenario.add_vehicle(vehicle, pos=(-717, 101, 118), rot_quat=(0, 0, 0.3826834, 0.9238795))

# Place files defining our scenario for the simulator to read
scenario.make(bng)

# Load and start our scenario
bng.scenario.load(scenario)
bng.scenario.start()

# Make the vehicle's AI span the map
vehicle.ai.set_mode('traffic')

input('Hit Enter when done...')

# Disconnect BeamNG
bng.disconnect()

  9. Install the Wireshark BeamNGpy plugin

    master

    Follow these steps to install the dissector plugin for Wireshark:

    1. Install Wireshark.
    2. Copy beamngpyDissector.lua and MessagePack.lua from the debug/ directory of this repository into your Wireshark plugins folder:
      • Windows: %appdata%/Wireshark/plugins
      • Linux: ~/.local/lib/wireshark/plugins
    3. Start a capture on the network interface used by BeamNGpy.
    4. Apply the filter beamngpy to isolate relevant traffic.

  10. Install BeamNGpy

    master

    You can install BeamNGpy using pip or conda.

    Using pip:

    pip install beamngpy

    To upgrade:

    pip install --upgrade beamngpy

    Using conda: Install from the conda-forge channel:

    conda install beamngpy -c conda-forge

    To upgrade:

    conda update beamngpy -c conda-forge --no-pin
    pip install beamngpy

  12. Run Template Car Generator in development mode

    master

    To develop the Template Car Generator, run the FastAPI server in development mode using the API entry point. Once running, you can access the web application, interactive API documentation (Swagger), or Redoc via your browser.

    • Web App: http://localhost:8000
    • API Docs: http://localhost:8000/docs
    • API Redoc: http://localhost:8000/redoc
    cd beamngpy
fastapi dev src/beamngpy/tools/template_car/api.py