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 overwriting motionSim.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.

Protocols