External hardware and software can be integrated with BeamNG.drive and BeamNG.tech, by listening for UDP packets containing the desired data.
There’s several UDP protocols available, and if you are a hardware or software manufacturer, you can implement your own protocol with relative ease (see Other Protocols section below).
These protocols can be enabled and configured in Options > Other > Protocols > OutGauge UDP protocol.
OutGauge UDP protocol
This protocol shares very basic information about the vehicle, such as speed, pedals, some dashboard lights, etc.
It uses the same format used by Live For Speed, which means that most digital displays and 3rd party software that works with OutGauge in LFS will also work in BeamNG.drive. Not all fields are implemented at the moment. The UDP packet has the following format:
// Items marked as `N/A` are not implemented.
typedef struct xxx {
unsigned time; // time in milliseconds (to check order) // N/A, hardcoded to 0
char car[4]; // Car name // N/A, fixed value of "beam"
unsigned short flags; // Info (see OG_x below)
char gear; // Reverse:0, Neutral:1, First:2...
char plid; // Unique ID of viewed player (0 = none) // N/A, hardcoded to 0
float speed; // M/S
float rpm; // RPM
float turbo; // BAR
float engTemp; // C
float fuel; // 0 to 1
float oilPressure; // BAR // N/A, hardcoded to 0
float oilTemp; // C
unsigned dashLights; // Dash lights available (see DL_x below)
unsigned showLights; // Dash lights currently switched on
float throttle; // 0 to 1
float brake; // 0 to 1
float clutch; // 0 to 1
char display1[16]; // Usually Fuel // N/A, hardcoded to ""
char display2[16]; // Usually Settings // N/A, hardcoded to ""
int id; // optional - only if OutGauge ID is specified
} xxx;
-- OG_x - bits for flags
local OG_SHIFT = 1 -- key // N/A
local OG_CTRL = 2 -- key // N/A
local OG_TURBO = 8192 -- show turbo gauge
local OG_KM = 16384 -- if not set - user prefers MILES
local OG_BAR = 32768 -- if not set - user prefers PSI
-- DL_x - bits for dashLights and showLights
local DL_SHIFT = 2 ^ 0 -- shift light
local DL_FULLBEAM = 2 ^ 1 -- full beam
local DL_HANDBRAKE = 2 ^ 2 -- handbrake
local DL_PITSPEED = 2 ^ 3 -- pit speed limiter // N/A
local DL_TC = 2 ^ 4 -- tc active or switched off
local DL_SIGNAL_L = 2 ^ 5 -- left turn signal
local DL_SIGNAL_R = 2 ^ 6 -- right turn signal
local DL_SIGNAL_ANY = 2 ^ 7 -- shared turn signal // N/A
local DL_OILWARN = 2 ^ 8 -- oil pressure warning
local DL_BATTERY = 2 ^ 9 -- battery warning
local DL_ABS = 2 ^ 10 -- abs active or switched off
local DL_SPARE = 2 ^ 11 -- N/A
MotionSim UDP protocol
This is a simplistic protocol that could be used to guide motion platforms. Only the most basic information is shared - for more advanced uses, please check ‘Other Protocols’ below.
typedef struct xxx {
char format[4]; // allows to verify if packet is the expected format, fixed value of "BNG1"
float posX, posY, posZ; // world position of the vehicle
float velX, velY, velZ; // velocity of the vehicle
float accX, accY, accZ; // acceleration of the vehicle, gravity not included
float upX, upY, upZ; // vector components of a vector pointing "up" relative to the vehicle
float rollPos, pitchPos, yawPos; // angle of roll, pitch and yaw of the vehicle
float rollVel, pitchVel, yawVel; // angular velocities of roll, pitch and yaw of the vehicle
float rollAcc, pitchAcc, yawAcc; // angular acceleration of roll, pitch and yaw of the vehicle
} xxx;
Other protocols
I’m an end-user and want to use other protocols
Please follow the product manual for your hardware / motion sim platform / digital dash / etc.
I’m a manufacturer and want to implement my own protocol
For programmers/manufacturers only: if you need assistance to integrate your hardware or software with BeamNG, you can reach us via email.
Programming your protocol
If you are a programmer from a hardware or software manufacturer, you may want to access more information than that offered by the default protocols described above.
- Before v0.32, you were forced to overwrite one of the official core files (such as overwriting
outgauge.lua
, or overwritingmotionSim.lua
). - Starting in v0.32, this area has been revamped, and you can place your own additional files inside
lua/vehicle/protocols/
.
To make things easier for end-users, we recommend you distribute your file in the form of a .ZIP
mod file:
- Open the User folder .
- Inside the User folder, create a folder called
USER_FOLDER/mods/unpacked/MY_PROTOCOL/lua/vehicle/protocols/
. - Inside you should create a
.LUA
file for your custom protocol. For example,USER_FOLDER/mods/unpacked/MY_PROTOCOL/lua/vehicle/protocols/myProtocol.lua
.
- You may want to use one of our official protocol files as a starting point. Our protocols are distributed under the open source bCDDL license, and located in
PROGRAM_INSTALL_FOLDER/lua/vehicle/protocols/*.lua
.
- Your custom protocol will be running as soon as you reload the vehicle Ctrl + R. To test changes to your code, save your
.LUA
file and reload the vehicle.
Distributing your protocol
When you have finished developing your .LUA
protocol file, you can transform it into a “mod” file, by going to ESC menu
> Mods
> Mods Manager
> myprotocol > PACK
.
This will move your code into a new file: USER_FOLDER/mods/my_protocol.zip
. You can distribute this file to end-users in several ways:
- Recommended:
upload it to the official BeamNG mod repository
. Users can then search your protocol in the
Mods
menu, installing it with one click. More information here . - Alternative: you may distribute the
.ZIP
file yourself (for example, using your own web server, or included together with your software package, etc). You will want to include the following link in your product manual:https://go.beamng.com/installing-mods-manually
. This way, users will have up-to-date instructions on what to do with your.ZIP
file.