BeamNGpy Reference

BeamNGpy

API

Vehicle

Sensors

API

Scenario

Procedural Objects

Roads

Sensors

Automated Sensors

Camera

Lidar

Ultrasonic Sensor

Powertrain Sensor

Advanced IMU

Classical Sensors

Sensor

State

Electrics

IMU

Timer

Damage

GForces

Logging

exception beamngpy.logging.BNGDisconnectedError

Exception class for BeamNGpy being disconnected when it shouldn’t.

exception beamngpy.logging.BNGError

Generic BeamNG error.

exception beamngpy.logging.BNGValueError

Value error specific to BeamNGpy.

beamngpy.logging.config_logging(handlers: List[Handler], replace: bool = True, level: int = 10, redirect_warnings: bool = True, log_communication: bool = False) → None

Function to configure logging.

Parameters

  • handlers (List[Handler]) – list of already configured logging.Handler objects

  • replace (bool) – whether to replace existing list of handlers with new ones or whether to add them, optional

  • level (int) – log level of the beamngpy logger object, optional. Defaults to logging.DEBUG.

  • redirect_warnings (bool) – whether to redirect warnings to the logger. Beware that this modifies the warnings settings.

  • log_communication (bool) – whether to log the BeamNGpy protocol messages between BeamNGpy and BeamNG.tech, optional

Return type

None

beamngpy.logging.create_warning(msg: str, category: Any = None) → None

Helper function for BeamNGpy modules to create warnings.

Parameters

  • msg (str) – message to be displayed

  • category (Any) – Category of warning to be issued. See warnings documentation for more details. Defaults to None.

Return type

None

beamngpy.logging.set_up_simple_logging(log_file: str | None = None, redirect_warnings: bool = True, level: int = 20, log_communication: bool = False) → None

Helper function that provides high-level control over beamng logging. For low-level control over the logging system use config_logging(). Sets up logging to sys.stderr and optionally to a given file. Existing log files are moved to <log_file>.1. By default beamngpy logs warnings and errors to sys.stderr, so this function is only of use, if the log output should additionaly be written to a file, or if the log level needs to be adjusted.

Parameters

  • log_file (str | None) – log filename, optional

  • redirect_warnings (bool) – Whether to redirect warnings to the logger. Beware that this modifies the warnings settings.

  • level (int) – log level of handler that is created for the log file. Defaults to logging.INFO.

  • log_communication (bool) – whether to log the BeamNGpy protocol messages between BeamNGpy and BeamNG.tech, optional

Return type

None

Tools

Miscellaneous

Quaternions

beamngpy.quat.angle_to_quat(angle: Float3) → Quat

Converts an euler angle to a quaternion.

Parameters

angle (Float3) – Euler angle in degrees.

Returns

Quaternion with the order (x, y, z, w) with w representing the real component.

Return type

Quat

beamngpy.quat.compute_rotation_matrix(quat: Quat) → numpy.ndarray

Calculates the rotation matrix for the given quaternion to be used in a scenario prefab.

Parameters

quat (Quat) – Quaternion with the order (x, y, z, w) with w representing the real component.

Returns

The rotation matrix as a NumPy array.

Return type

numpy.ndarray

beamngpy.quat.flip_y_axis(q: Quat) → Quat

Returns a rotation with a flipped y-axis.

Parameters

q (Quat) – Quaternion with the order (x, y, z, w) with w representing the real component.

Returns

The flipped quaternion.

Return type

Quat

beamngpy.quat.quat_as_rotation_mat_str(quat: Quat) → str

For a given quaternion, the function computes the corresponding rotation matrix and converts it into a string.

Parameters

quat (Quat) – Quaternion with the order (x, y, z, w) with w representing the real component.

Returns

Rotation matrix as a string.

Return type

str

beamngpy.quat.quat_multiply(a: Quat, b: Quat) → Quat

Multiplies two quaternions.

Parameters

  • a (Quat) – Quaternion with the order (x, y, z, w) with w representing the real component.

  • b (Quat) – Quaternion with the order (x, y, z, w) with w representing the real component.

Returns

The product of a and b as a quaternion.

Return type

Quat

Types

beamngpy.types.Color

Vehicle color. Can be either:

  • (R, G, B) tuple of floats,

  • (R, G, B, A) tuple of floats,

  • string of format 'R G B',

  • string of format 'R G B A',

  • a common color name (parsable by matplotlib.colors).

alias of Union[Tuple[float, float, float], Tuple[float, float, float, float], str]

beamngpy.types.Float2

alias of Tuple[float, float]

beamngpy.types.Float3

alias of Tuple[float, float, float]

beamngpy.types.Float4

alias of Tuple[float, float, float, float]

beamngpy.types.Float5

alias of Tuple[float, float, float, float, float]

beamngpy.types.Int2

alias of Tuple[int, int]

beamngpy.types.Int3

alias of Tuple[int, int, int]

beamngpy.types.Quat

alias of Tuple[float, float, float, float]

beamngpy.types.StrDict

alias of Dict[str, Any]

Connection

class beamngpy.connection.Connection(host: str, port: int | None = None)

The class for handling socket communication between BeamNGpy and the simulator, including establishing connections to both the simulator and to its vehicles individually, and for sending and recieving data across these sockets.

Instantiates an instance of the Connection class, creating an unconnected socket ready to be connected when required.

Parameters

  • host (str) – The host to connect to.

  • port (int | None) – The port to connect to.

PROTOCOL_VERSION = 'v1.21'
connect_to_beamng(tries: int = 25, log_tries: bool = True) → bool

Sets the socket of this connection instance and attempts to connect to the simulator over the host and port configuration set in this class. Upon failure, connections are re-attempted a limited amount of times.

Parameters

  • tries (int) – The number of connection attempts.

  • log_tries (bool) – True if the connection logs should be propagated to the caller. Defaults to True.

Returns

True if the connection was successful, False otherwise.

Return type

bool

connect_to_vehicle(vehicle: Vehicle, tries: int = 25) → None

Sets the socket of this Connection instance, and attempts to connect it to the given vehicle. Upon failure, connections are re-attempted a limited amount of times.

Parameters

  • vehicle (Vehicle) – The vehicle instance to be connected.

  • tries (int) – The number of connection attempts.

Return type

None

disconnect() → None

Closes socket communication for this Connection instance.

Return type

None

hello() → None

First function called after connections. Exchanges the protocol version with the connected simulator and raises an error upon mismatch.

Return type

None

message(req: str, **kwargs: Any) → Any

Generic message function which is parameterized with the type of message to send and all parameters that are to be embedded in the request. Responses are expected to have the same type as the request. If this is not the case, an error is raised.

Parameters

  • req (str) – The request type.

  • kwargs (Any) –

Returns

The response received from the simulator as a dictionary.

Return type

Any

recv(req_id: int) → StrDict | BNGError | BNGValueError
Parameters

req_id (int) –

Return type

StrDict | BNGError | BNGValueError

send(data: StrDict) → Response

Encodes the given data using Messagepack and sends the resulting bytes over the socket of this Connection instance. NOTE: messages are prefixed by the message length value.

Parameters

data (StrDict) – The data to encode and send

Return type

Response

class beamngpy.connection.Response(connection: Connection, req_id: int)
Parameters
ack(ack_type: str) → None
Parameters

ack_type (str) –

Return type

None

recv(type: str | None = None) → StrDict
Parameters

type (str | None) –

Return type

StrDict