UDP Communication Message

This section describes the UDP message protocol regarding the types and data structures of exchanged messages based on the communication supported by the simulator.

UDP Communication Message

This section explains the message types, each packet structure, and the data size exchanged according to the UDP communication in the Ego Network and Simulator Network provided in the Network Settings.

Ego Network

The UDP messages transmitted to the Ego Network and the protocol information for each message are as follows.

Ego Ctrl Cmd

• Message Definition: Vehicle Control Command

• Message Protocol:

  • Total Packet Size : 55 Bytes

  • Data Size : 3 Bytes + 20 Bytes

  • Data Structure and Type

    • CtrlMode Command

      • 1 : KeyBoard

      • 2 : AutoMode
        

    • Gear Command (1 byte)

      • M : 0

      • P : 1 (Parking)

      • R : 2 (Reverse)

      • N : 3 (Neutral)

      • D : 4 (Drive)

      • L : 5 (Level L)
        

    • longCmdType (1byte / CmdType / byte): Index to determine the control method.

      • longCmdType == 1: Throttle control. accel/brake/steering

      • longCmdType == 2: Velocity control. velocity/steering

      • longCmdType == 3: Acceleration control.
        

    • Longitudinal speed Control (4byte / Veloctiy / float).

      • Use when the longCmdType is 2 ( km/h ).

      • Longtitudinal

    • Longtitudinal Acceleration Control (4byte / Acceleration / float).

      • Use when the longCmdType is 3 ( m/s² ).
        

    • Longtitudinal Accelerator Control Command (4byte /Acceleration CMD float).

      • Acceleration Pedal Input value (0 ~ 1).
        

    • Longtitudinal Brake Control Command (4byte / Brake CMD / float).

      • Brake Pedal Input value (0 ~ 1).
        

    • Lateral Control Command (4byte / Steer CMD / float).

      • Lateral Control Input value (-1 ~ 1 ).

      • Actual control value = Desired steering value (degrees) / Maximum steering angle.
        (For example, Maximum steering angle: Niro = 36.25, Ioniq = 36.25.)

The longitudinal speed control method was changed to an acceleration control method. This implementation limits acceleration to 1 m/s² for speed increases and -2 m/s² for speed decreases, preventing sudden changes in speed that could lead to chattering. As a result, although the reaction time to discontinuous speed inputs is slower, the system now converges more stably to the target speed, as illustrated in the figure below.

Ground Vehicle Direct Ctrl Cmd

• Message Definition: Message for direct control of Wheel-based Ground Vehicles (vehicles and robots). (User → SIM)

• Message Protocol

  • Total Packet Size: 85 bytes

  • Data Size: Header(33byte) + Payload(52byte)

• Header

  • msg_type : 65

• Payload

• steer_type

  • Refer to the Table 1.

• throttle

  • Longitudinal acceleration control commands for forward/reverse operation:

    • When steer type == SKID_STEERING (1) or ACKERMANN_STEERING (2), the vehicle receives forward/reverse inputs:

      • sign: Indicates direction [+(forward) / -(reverse)]

      • value: Throttle input [1 (maximum) to 0 (minimum)]

    • When steer type == ZERO_TURN (3), inputs are provided for the vehicle's rotation direction and magnitude during zero turns:

      • sign: Indicates direction [+(right turn) / -(left turn)]

      • value: Throttle input for the amount of rotation [1 (maximum) to 0 (minimum)]

• skid_steering

  • Available lateral control commands when steer type == SKID_STEERING (1):

    • sign: Indicates direction [+(right turn) / -(left turn)]

    • value: Throttle input for the amount of rotation [1 (maximum) to 0 (minimum)]

• steer_angle

  • Available lateral steering control commands when steer type == ACKERMANN_STEERING (2):

    • sign: Indicates direction [+(steering wheel right turn) / -(steering wheel left turn)]

    • value: Steering angle input [1 (maximum) to 0 (minimum)]

      • Actual control value = Desired steering value (degrees) / Maximum steering angle.
        The maximum steering angle follows the vehicle's dynamic specifications.

      • An array is configured to receive steering values for up to 10 axes, adhering to the vehicle's dynamic specifications.

Ground Vehicle State Ctrl Cmd

• Message Definition: Message for controlling the Target State of Wheel-based Ground Vehicles (vehicles and robots) (User → SIM)

• Message Protocol

  • Total Packet Size: 41 bytes

  • Data Size: Header(33byte) + Payload(8byte)

• Header

  • msg_type : 66

• Payload

• TargetLongitudinalVelocity

  • Target longitudinal speed during speed control.

  • m/s

• TargetAngularVelocity

  • Target angular velocity during speed control.

  • rad/s

Ghost Ctrl Cmd

• Message Definition: A message to control the Ego-vehicle using Ghost Mode. (User → SIM)
  

  

• Message Protocol

  • Total packet size: 63 bytes

  • Data size: 32 bytes
    

• Total Packet Structure

Ego Vehicle Status

The data structure of the UDP communication Ego-Vehicle Status message has been changed as follows.

• Add Timestamp (8 bytes)

• Add Angular Velocity (12 bytes)

When using Sync Mode, the calculations are based on the simulator start time instead of the Unix timestamp.

• Message Definition: A message to control the Ego-vehicle.

• Message Protocol

  • Total Packet Size : 181 Bytes

  • Data Size : 50 Bytes + 102 Bytes

  • Timestamp information

    • Data Description: Elapsed time from the Unix timestamp (01/01/1970)

    • First 4 bytes: Elapsed time in seconds

    • Second 4 bytes: Fractional seconds of the timestamp expressed in nanoseconds

  • CtrlMode information

    • 1 : KeyBoard

    • 2 : AutoMode

  • gear information

    • M : 0

    • P : 1 (Parking)

    • R : 2 (Reverse)

    • N : 3 (Neutral)

    • D : 4 (Driving)

    • L : 5 (L-level)

  • Velocity in the direction of the vehicle's movement (4byte / signed velocity, float)

    • Data Description : It is the velocity in the direction of the vehicle's movement and it is measured by km/h.

  • Map data id value (Map data id, int)

    • DigitalTwin Map = 0 ~ 9999

    • Virtual Map = 10000 ~ 19999

  • Longitudinal control command (4byte / Accel / float)

    • Data Description : Acceleration Pedal Input value (0 ~ 1).

  • longitudinal control command (4byte / Brake / float)

    • Data Description : Brake Pedal Input value (0 ~ 1).

  • Ego-vehicle Size (size XYZ, float)

    • Data Description : Represents the size of the object, measured in meters (m).

  • Vehicle Overhang information (4byte / OverHang / float)

    • Data Description : Ego-vehicle’s OverHang information.

  • Vehicle WheelBase information (4byte / WheelBase/ float)

    • Data Description : Ego-vehicle’s WheelBase information.

  • Vehicle Rear Overhang information (4byte / Rear OverHang / float)

    • Data Description : Ego-vehicle’s Rear OverHang information.

  • Vehicle Position information (pos XYZ, float)

    • Data Description : Represents the vehicle’s position, measured in meters (m).

  • Vehicle Rotation information (Roll/Pitch/Heading, float)

    • Data Description : Represents the vehicle’s rotation, measured in degrees (deg).

  • Vehicle Velocity information (4Byte * 3 / Velocity_XYZ / float)

    • Data Description : Represents the vehicle’s current velocity, measured in km/h.

      • float x

      • float y

      • float z

  • Angular velocity information ( 4 bytes * 3, deg/s)

    • Data Description: Vector representing the angular velocity around the center of the vehicle.

    • float x

    • float y

    • float z

  • acceleration (4Byte * 3 / Accel_XYZ / float)

    • Vehicle’s acceleration vector ( m/s² )

      • float x

      • float y

      • float z

  • Vehicle’s lateral information (Steer, float)

    • Data Description : Represents the lateral direction of the vehicle, measured in degrees (deg).

  • It also includes the ID information of the MGeo Link where the vehicle is located (38 bytes / Link ID / String) (New).

Object Info

The data structure of the UDP communication Object Info message has been changed as follows:

• A Timestamp (8 bytes) has been added at the beginning of the data packet.

• The Timestamp is included only once per packet, rather than being added for each object within the packet.

• Message Definition: A message representing information about surrounding objects spawned by the user.

• Message Protocol

  • Total Packet Size : 2160 Bytes

  • Data Size : 2120 Bytes(106 Bytes * 20)

    • The data can provide information about a total of 20 objects, including sur-vehicles, pedestrians, and other objects, ordered by their closest distance from the user's vehicle.

  • Object ID (Index) information (2byte / Objid / int)

    • Data Description : Represents the Object’s Unique ID.

  • Object Type information (ObjType, short)

    • Data Description : Represents the Object’s type.

      • Ego Vehicle : -1 (For ROS, Ego Type is defined as -1.)

      • Pedestrian : 0

      • Sur-vehicle : 1

      • Object : 2

  • Object Position information (pos XYZ, float)

    • Data Description : Represents the position of the Object, measured in meters (m).

  • Object Rotation information (Heading, float)

    • Data Description : Represents the rotation of the Object, measured in degrees (deg).

  • Object Size information (size XYZ, float)

    • Data Description : Represents the Object’s size, measured in meters (m).

  • Object Overhang information (4byte / OverHang / float)

    • Data Description : Object’s OverHang information.

  • Object WheelBase information (4byte / WheelBase/ float)

    • Data Description : Object’s WheelBase information.

  • Object Rear Overhang information (4byte / Rear OverHang / float)

    • Data Description : Object’s Rear OverHang information.

  • Object’s velocity information (4Byte * 3 / Velocity_XYZ / float)

    • Data Description : Represents the Object’s current velocity, measured in km/h.

      • float x

      • float y

      • float z

  • Object’s Acceleration (4Byte * 3 / Accel_XYZ / float)

    • Object’s acceleration vector ( m/s² )

      • float x

      • float y

      • float z

  • ID information of the MGeo Link where the object is located ( 38 byte / Link ID / String)

    • Only NPCs output the MGeo Link ID information; other objects do not output this information.

Get TrafficLight Status

• Message Definition: A message for a Traffic Light status information.

• Message Protocol

  • Total Packet Size : 48 Bytes

  • Data Size : 16 Bytes

  • trafficLightIndex

    • Message Description : Traffic Light ID.

  • trafficLightType

    • Message Description : Traffic Light Type.

      • 3-Light (R-Y-G) : 0

      • 3-Light (R-Y-GLeft) : 1

      • 4-Light (R-Y-GLeft-G) : 2

      • 3-Light (Y-Y-Y) : 100

  • trfficLightStatus

    • Message Description : Traffic Light Status.

      • Red : 1

      • Yellow : 4

      • Green : 16

      • GreenLeft : 32

      • Green with GreenLeft : 48

      • Yellow with Green : 20

      • Yellow with GreenLeft : 36

      • Red with Yellow: 5

      • default : -1

Set TrafficLight Ctrl

• Message Definition: A message for controlling the traffic light state.

• Message Protocol

  • Total Packet Size : 46 Bytes

  • Data Size : 14 Bytes

  • trafficLightIndex

    • Message Description : Traffic Light ID.

  • trafficLightStatus

    • Message Description : Configure the Traffic Light status.

      • Red : 1

      • Yellow : 4

      • Green : 16

      • GreenLeft : 32

      • Green with GreenLeft : 48

      • Yellow with Green : 20

      • Yellow with GreenLeft : 36

      • Red with Yellow: 5

      • default : -1

Collision Data

The data structure of the UDP communication Collision Data message has been changed as follows:

• A Timestamp (8 bytes) has been added in front of the objType.

• The Timestamp is included only once per packet, rather than being added for each object within the packet.

• The actual output data for a specific object does not include a Timestamp.

• Message Definition: A message representing a collision data with Ego-vehicle.

• Message Protocol

  • Total Packet Size : 181 bytes

  • Data Size : 148(28*5 + 8) bytes

  • Timestamp information

  • Object Type information (2byte / ObjType / short)

    • Data Description : Object type information which collided with the Ego-Vehicle.

      • Ego Vehicle : -1

      • Pedestrian : 0

      • Sur-vehicle : 1

      • Object : 2

  • Object ID (Index) information (2byte / Objid / short)

    • Data Description : Unique ID information of the object that collided with the Ego-Vehicle.

  • Object Position information (4byte / posXYZ / float)

    • Data Description : Object’s position information which collided with the Ego-Vehicle, measured in meters (m).

  • Global Offset information (4byte / posXYZ / float)

    • global_offset_x

    • global_offset_y

    • global_offset_z

Get Intersection Status

• Message Definition: Intersection Status information

• Message Protocol

  • Total Packet Size : 37 Bytes

  • Data Size : 8 Bytes

  • Intersection Index (2 byte / IntIndex / short)

    • Represents the intersection index

  • Intersection Status (2 byte / IntStatus / short)

    • Represents the Intersection status.

  • Elapsed time in the current intersection state. (4 byte / IntTime / float)

    • intersection_status_time

Set Intersection Status

• Message Definition: Intersection Control information.

• Message Protocol

  • Total Packet Size : 40 Bytes

  • Data Size : 8 Bytes

  • Intersection Index (2 byte / IntIndex / short)

    • Represents Intersection Index.

  • Intersection Status (2 byte / IntStatus / short)

    • Intersection Status

  • Elapsed time in the configured intersection state. (4 byte / IntTime / float)

    • intersection_status_time

Scenario Load

• Message Definition : Load the Scenario file (.json).

• Message Protocol

  • Total Packet Size : 69 Bytes

  • Data Size : 37 Bytes

  • file_name (30 byte / filename / string)

    • Determine the file name to load in .json format.

      • The filename must be within 30 bytes and should not include the .json extension.

      • If the filename is less than 30 bytes, fill the remaining byte count (30 bytes - filename byte count) with spaces to ensure the total byte size is met before sending.

  • delete_all (1 byte / delete_all /bool )

    • True : Delete and load Scenario data excluding Ego-vehicle.

    • False : Load all the Scenario Data.

      • delete_all 이 False 일 때 아래의 Load Option을 사용해서 원하는 Scenario Data Load 가능.

  • load_network_connection_data (1 byte / network /bool )

    • True : Load network connection.

    • False : Not loading the network connection.

  • load_ego_vehicle_data (1 byte / ego_vehicle /bool )

    • True : Load Ego Scenario Data.

    • False : Not loading the Ego Scenario Data.

  • load_surrounding_vehicle_data (1 byte / npc_vehicle /bool )

    • True : Load NPC Vehicle Scenario Data.

    • False : Not loading NPC Vehicle Scenario Data.

  • load_pedestrian_data (1 byte / pedestrian /bool )

    • True : Load pedestrian Scenario Data.

    • False : Not loading the pedestrian Scenario Data.

  • load_object_data (1 byte / object /bool)

    • True : Load Object Scenario Data.

    • False : Not loading the Object Scenario Data.

  • set_pause (1 byte / pause /bool)

    • True : Keep it in a pause mode after loading the Scenario (Press the ESC key to switch to the Play mode).

    • False : Immediately switch to Play mode after loading the scenario.

SaveSensorData

• Message Definition: Save the sensor’s current data.

• Message Protocol

  • Total Packet Size : 125 Bytes

  • Data Size : 91 Bytes

  • is_custom_file_name (1 byte / custom / bool)

    • When set to false, data is saved in the SaveFile\SensorData path of the simulator file.

  • custom_file_name (30 byte / file name / String)

    • (Use when is_custom_file_name: true is set) Specify the file name to be saved.

  • file_dir (60 byte / file dir/ String)

    • (Use when is_custom_file_name: true is set) Specify the path of the file to be saved.

SaveSensorData is the same message as Sensor Sync Data in the SIM's UDP network settings, differing only in name.

Sensor Control

• Message Definition : Control the sensor’s position.

• Message Protocol

  • Total Packet Size: 59 Bytes

  • Data Size: 26 Bytes

  • sensor_index (2 byte / Sensor Index/ int)

    • Sensor Index number to control its position.
      Sensor Index: {Sensor model-N}

      

  • Sensor Position information (4 byte / posXYZ / float).

    • Data Description : Represents the sensor’s position, measured in meters (m).

  • Sensor Rotation information (4 byte *3 / Roll Pitch Heading / float)

    • Data Description : Represents the sensor’s rotation, and measured in degrees (deg).

Turn Signal Lamp Control

• Message Definition: Control Turn left/right Signal.

• Message Protocol

  • Total Packet Size : 33 Bytes

  • Data Size : 2 Bytes

  • trunSignal (1byte / turnSignal / byte)

    • 0 : No Signal

    • 1 : Left Signal

    • 2 : Right Signal

  • emergencySignal (1byte / emergencySignal / byte)

    • 0 : No Signal

    • 1 : Emergency Signal

Simulator Network

The UDP messages transmitted to the Simulator Network and the protocol information for each message are as follows.

Multi Ego Setting

• Message Definition

  • Multi-Ego Control Command (User → SIM)

  • A message that allows setting the position, rotation, speed, gear, and more for multiple Ego-vehicles.

• Message Protocol

  • Total Packet Size: 683 Bytes

  • Data Size: 648 Bytes(4 + 4 + 32 Bytes * 20)
    

  • Total Packet Structure

Body Data (32 Bytes)

Gear Mode

Ctrl_Mode

NPC Vehicle Collision Data

• Message Definition: A message representing the collision data with NPC vehicles.

• Message Protocol

  • Total Packet Size : 1156 Bytes

  • Data Size : 1120 Bytes(112 Bytes * 10)

    • The data can provide information about a total of 20 objects, including sur-vehicles, pedestrians, and other objects, ordered by their closest distance from the user's vehicle.

  • Object Type information for object number 1 (ObjType, short)

    • Data Description : Object type information.

      • Ego Vehicle : -1

      • Pedestrian : 0

      • Sur-vehicle : 1

      • Object : 2

  • Object ID (Index) information for object number 1 (2byte / Objid / short)

    • Data Description : Object’s Unique ID information which collided with the Ego-Vehicle.

  • Object Position information for object number 1 (pos XYZ, float)

    • Data Description : Represents the object’s position, measured in meters (m).

  • Object Rotation information for object number 1 (Heading, float)

    • Data Description : Represents the object’s rotation, measured in degrees (deg).

  • Object Size information for object number 1 (size XYZ, float)

    • Data Description : Represents the object’s size, measured in meters (m).

  • Object Velocity information for object number 1 (4Byte * 3 / Velocity_XYZ / float)

    • Data Description : Represents the NPC vehicle’s current velocity, measured in km/h.

      • float x

      • float y

      • float z

  • Object’s acceleration for object number 1 (4Byte * 3 / Accel_XYZ / float)

    • Vehicle’s Acceleration Vector ( m/s² )

      • float x

      • float y

      • float z

  • Object Type information for object number 2 (ObjType, short)

    • Data Description : Object Type information.

      • Ego Vehicle : -1

      • Pedestrian : 0

      • Sur-vehicle : 1

      • Object : 2

  • Object ID (Index) information for object number 1 (2byte / Objid / short)

    • Data Description : Object’s Unique ID information which collided with Ego-Vehicle.

  • Object’s position information for object number 2 (pos XYZ, float)

    • Data Description : Represents object’s position, measured in meters (m).

  • Object’s rotation information for object number 2 (Heading, float)

    • Data Description : Represents object’s rotation, measured in degrees (deg).

  • Object’s size information for object number 2 (size XYZ, float)

    • Data Description : Represents the object’s size, measured in meters (m).

  • Object Velocity information for object number 2 (4Byte * 3 / Velocity_XYZ / float)

    • Data Description : Represents the NPC vehicle’s current velocity, measured in km/h.

      • float x

      • float y

      • float z

  • Object’s acceleration for object number 2 (4Byte * 3 / Accel_XYZ / float)

    • Vehicle’s Acceleration vector ( m/s² )

      • float x

      • float y

      • float z