# Komatsu HM400-5 Articulated Dump Truck — OpenPLX Model

This folder contains a detailed OpenPLX model of the Komatsu HM400-5, built using the core OpenPLX bundles `Vehicles`, `MachineModeling`, and `DriveTrain`.

## Repository structure

This section details the organization of the OpenPLX files for the model and additional files.

### `Variants/`

This directory holds the main OpenPLX files that serve as central entry points. These are fully configured vehicle variants, including drivetrain, built on the `Base` assembly. The models in this folder are instantiable and can be placed into scenes. They can also be used in simulations with control, which we call "scenarios". For this purpose, they must be placed in a scene with ground, as demonstrated in the `Scenarios/Scenes/` folder.
- `Variants/AngleControl/Drivetrain.openplx`
- `Variants/AngleControl/IndividualWheelMotors.openplx`
- `Variants/LinearActuatorControl/Drivetrain.openplx`
- `Variants/LinearActuatorControl/IndividualWheelMotors.openplx`

### `Scenarios/`

This directory contains runnable scenarios for demonstration and testing. Python scripts with `run` in their names start simulations using scenes and control scripts from the subfolders below.

#### `Scenarios/Scenes/`

This folder contains scenes. These are instantiable models with one or more variants and ground. They can serve as a main entry point for viewing.

- `Scenarios/Scenes/TwoTrucks.openplx`
- `Scenarios/Scenes/DumpTruck.openplx`
- `Scenarios/Scenes/DumpTruckAngleControl.openplx`
- `Scenarios/Scenes/DumpTruckFullDrivetrain.openplx`
- `Scenarios/Scenes/DumpTruckFullDrivetrainAngleControl.openplx`

The file `TwoTrucks.openplx` instantiates two variants with different initial states.

#### `Scenarios/Control/`

This folder contains control scripts in Python and additional files for control.
    
### `States/`

This folder contains reusable state traits for use in scenarios:
- `TurnLeft.openplx`
- `TurnRight.openplx`

### `Assets/`

This folder contains the necessary support files for the model assembly, including reusable model fragments, property traits, connection definitions, and OBJ/MTL geometry with exported rigid-body traits.

- `Assets/Base.openplx`

This file is a foundation for the instantiable main models in `Variants/`. It is the central definition of the common vehicle assembly, including:
- articulated chassis with intermediate link
- steering cylinders
- front A-frame suspension connection
- rear dual A-frame connection
- cargo bed and lift connection
- connector mapping from exported assets to OpenPLX interfaces

`Base` also incorporates shared physical properties defined in the `Assets/Properties/` folder:
- `Assets.Properties.Mass`
- `Assets.Properties.Suspension`

Control-specific properties are added by the variants:
- `Assets.Properties.AngleControl` for the angle-control variants
- `Assets.Properties.LinearActuatorControl` for the linear-actuator variants
- `Assets.Properties.Hydraulic` together with `Assets.Properties.LinearActuatorControl`

The `Assets` folder contains furthermore the following subfolders:


#### `Assets/Components/`

Contains reusable subsystems such as wheels or drivetrains which can be used to define different vehicle variants. 

#### `Assets/Properties/`

Contains key physical properties and settings for the model such as mass, suspension and hydraulic system properties.

#### `Assets/RigidBodyDefinitions/`
Stores any imported CAD geometries and their connection properties.

Key rigid-body definition file:
- `Assets/RigidBodyDefinitions/HM400/Generated.openplx`

#### `Assets/SignalInterfaces/`

Defines OpenPLX signals for model input and output for different subsystems of the complete vehicle.

## How to load

The typical entry points for loading the model are:
- `KomatsuHM400.Variants.AngleControl.Drivetrain`
- `KomatsuHM400.Variants.AngleControl.IndividualWheelMotors`
- `KomatsuHM400.Variants.LinearActuatorControl.Drivetrain`
- `KomatsuHM400.Variants.LinearActuatorControl.IndividualWheelMotors`
- `KomatsuHM400.Scenarios.Scenes.TwoTrucks`

### Run

To load the model either in AGX Dynamics or in Unity / Unreal use any of the `Variants` above.
To run the scenarios with control there are Python entry points directly in `Scenarios/`. Shared control maps and runner utilities can be found in `Scenarios/Control/`. Use one of:

`python Scenarios/run_dumptruck_linear_actuator_control.py`

or

`python Scenarios/run_dumptruck_angle_control.py`

or

`python Scenarios/run_dumptruck_full_drivetrain_linear_actuator_control.py`

or

`python Scenarios/run_dumptruck_full_drivetrain_angle_control.py`

## Model description

## Chassis
The front and rear frames are modeled as rigid bodies. The articulated steering connector between front and rear frame has been modeled with full kinematics.

The suspension consists of a trailing A-frame suspension supported by two spring/dampers for the front frame. The rear frame uses two trailing A-frames which interact by a pivoting beam. The rearmost A-frame also has two spring/dampers.

The springs and dampers have been modeled as linear with the properties for each suspension strut shown below. The values are rough estimates based on the weights of the empty/fully loaded vehicle and a target ride frequency around 1.5 Hz. If a more realistic ride frequency is required for both empty and fully loaded vehicle, non-linear spring and damper behavior should be incorporated.

    Front suspension linear setup:
        Stiffness:  750 kN/m
        Pre-load:   260 kN
        Damping:    200 kN/(m/s)

    Rear suspension linear setup:
        Stiffness: 2000 kN/m
        Pre-load:   400 kN
        Damping:    400 kN/(m/s)

Note: The rolling/oscillating compliance of the undercarriages is not modeled (i.e. no bushings or spherical joints are used to connect the trailing A-frame suspensions). The trailing A-frames are instead connected using simple hinge joints.

## Mass properties

Weight of some of the main components of the vehicle are listed in the shop manual [3]. These components include for example the engine, transmission, cooler, tanks, drive shafts, frame, cab and wheels.
Approximately 7 900 kg was not accounted for in the shop manual. It was assumed that 70% of this mass is located in the front section, which contains more components than the rear.
In the simulation model, most of the mass is assigned to `chassis.front_frame` and `chassis.rear_frame`. Their mass and centers of mass were adjusted to match axle loads specified in [3] for both unladen and fully loaded conditions, shown below. The mass centers of other parts such as dump body, trailing suspension arms and wheels were assigned based on imported CAD geometries.

    Vehicle without payload
    Axle    |     1     |    2    |    3    |
    Load    |  20 100   |  7 690  |  7 340  | [kg]
            |   57.2%   |  21.9%  |  20.9%  |


    Vehicle with full payload (40 000 kg)
    Axle    |     1     |    2    |    3    |
    Load    |  22 690   | 26 140  | 26 300  | [kg]
            |   30.2%   |  34.8%  |  35.0%  |

Note: The scaling of the dump bed mass with respect to payload currently only alters the longitudinal and not the vertical center of mass of the dump bed. For a more realistic mass center when fully loaded it is possible to fill the dump bed with granular material during simulation.

## Drivetrain

Two different drivetrains have been modeled: one simplified and one more detailed. Both drivetrains can be controlled using the OpenPLX signal interface.

### Simplified drivetrain

The simplified drivetrain applies an individual rotational velocity at each wheel. It is also possible to set a limit for available torque at each wheel. If no limit is set, the vehicle can apply effectively infinite torque to maintain desired wheel rotational velocity.

### Detailed drivetrain
The detailed drivetrain is modeled using the `DriveTrain` bundle of OpenPLX. It includes engine, torque converter, gearbox, differential gears for each axle, individual brakes on each wheel axle and final drive gears at the end of each wheel axle.
Most data on drivetrain components was taken from [1] and [3]. Some engine data was taken from [2] which uses an older generation of the same engine.

#### Engine

The vehicle uses the Komatsu SAA6D140E-7 engine, which is a 6-cylinder diesel, 2257 Nm @ 1400 rpm. It has been modeled as a mean value engine (MVE). [2]

    displacement_volume:      15.24e-3  # m^3 (15.24 L)
    max_torque:             2257.00      # N·m
    max_torque_RPM:         1400.00      # rpm
    max_power_RPM:          2000.00      # rpm
    idle_RPM:                700.00      # rpm
    max_RPM:                3000.00      # rpm
    crank_shaft_inertia:       4.00      # kg·m^2
    idle_throttle_angle:       0.17      # rad
    max_throttle_angle:        1.45      # rad
    throttle_pin_bore_ratio:   0.10
    max_volumetric_efficiency: 0.92
    inlet_volume:              1.10*displacement_volume
    air_fuel_ratio:           14.50      # diesel stoichiometric air-fuel ratio
    heat_value:         43400000.00      # J/kg diesel LHV

#### Gear ratios

The vehicle uses an automatic transmission with six forward gears and two reverse with the following gear ratios:

    # Gear no.       1     2     3     4     5     6
    forward_gears: [5.80, 3.79, 2.47, 1.62, 1.05, 0.69]
    reverse_gears: [5.63, 2.39]

Transmission gear ratios were not found explicitly stated and were instead estimated from vehicle speeds in each gear at 2000 rpm, obtained from [3] as shown below.
The calculation also uses tire size (29.5R25) together with the gear ratios of the differentials and final drives.

    Forward gears
        1     6.6 km/h
        2    10.1 km/h
        3    15.5 km/h
        4    23.7 km/h
        5    36.5 km/h
        6    55.9 km/h

    Reverse gears
        1     6.8 km/h
        2    16.0 km/h

Each axle has a differential gear:

    differential.gear_ratio: 3.727

and each wheel axle also has a final drive gear:

    final_drive.ratio: 4.941

### Wheels
Wheel size is 29.5R25. Based on general tire sources this corresponds to an outer diameter of about 1.87 m and a static rolling radius of about 0.835 m.

According to the Komatsu shop manual [3] the weights are:

    Tire:   520 kg
    Rim:    257 kg

Initial tire stiffness in the radial direction was estimated using unloaded vs loaded radius together with rated tire load (14000 - 22000 kg). This gives a span of about 1.2 - 2.2 kN/mm. In the current setup a value in the middle of this range was selected (1.6 kN/mm).

For remaining directions, stiffness and damping values were estimated based on an existing wheel loader tire model to preserve realistic relative levels between directions.

    along_radial.stiffness:   1.6e6
    along_axial.stiffness:    3.0e6
    around_radial.stiffness:  1.0e6
    around_axial.stiffness:   0.2e6

    along_radial.damping_constant:   8.0e4
    along_axial.damping_constant:    8.0e4
    around_radial.damping_constant:  8.0e4
    around_axial.damping_constant:   3.0e4

# OpenPLX signal interface

The model has common output signals for vehicle state, plus additional signals depending on the selected drivetrain and control variant.

Velocity-control inputs for steering and cargo bed are only available in the `LinearActuatorControl` variants.

Two comments on the current controls implementation: one regarding vehicle velocity output, and the other concerning the angle-controlled variants.

**Vehicle velocity**

To express the drive velocity of the vehicle, the velocity must be defined in the global frame together with a direction vector anchored to the vehicle.
In the current release of OpenPLX, it is not possible to output the direction vector of a mate connector as a signal. Instead, the current model provides two position output signals (front_frame_velocity_vector_start and front_frame_velocity_vector_end). These allow the control script to compute a direction vector between the two points, which can then be used to calculate the vehicle’s drive velocity.

**Angle control**

Controlling the steering and cargo bed angle using only OpenPLX signals (i.e., without external control logic) can be achieved by applying a torsion spring to the relevant joint. By tuning the spring’s stiffness and damping, the target angle can be adjusted during runtime to control the joint.
In the current implementation, the angle is continuously adjusted while a specified key is held down. To prevent overshooting the intended angle, it is necessary to also detect the key release event and, at that point, update the target angle to match the current angle.



## Common signals

**Output signals**

    front_frame_position
    front_frame_velocity
    front_frame_acceleration

    rear_frame_position
    rear_frame_velocity
    rear_frame_acceleration

    front_frame_velocity_vector_start
    front_frame_velocity_vector_end

    drivetrain_wheel_front_left_angular_velocity
    drivetrain_wheel_front_right_angular_velocity
    drivetrain_wheel_mid_left_angular_velocity
    drivetrain_wheel_mid_right_angular_velocity
    drivetrain_wheel_rear_left_angular_velocity
    drivetrain_wheel_rear_right_angular_velocity

    steering_left_cylinder_position
    steering_right_cylinder_position
    steering_angle
    steering_angular_velocity

    cargo_bed_left_cylinder_position
    cargo_bed_right_cylinder_position
    cargo_bed_angle
    cargo_bed_angular_velocity

## Linear actuator control

**Input signals**

    steering_left_vel_input
    steering_right_vel_input
    cargo_bed_left_vel_input
    cargo_bed_right_vel_input

## Angle control

**Input signals**

    steering_angle_input
    cargo_bed_angle_input

**Output signals**

    steering_torque

## Simplified drivetrain (individual wheel motors)

**Input signals**

    drivetrain_wheel_vel_front_left_input
    drivetrain_wheel_vel_front_right_input
    drivetrain_wheel_vel_mid_left_input
    drivetrain_wheel_vel_mid_right_input
    drivetrain_wheel_vel_rear_left_input
    drivetrain_wheel_vel_rear_right_input

**Output signals**

    drivetrain_wheel_front_left_torque
    drivetrain_wheel_front_right_torque
    drivetrain_wheel_mid_left_torque
    drivetrain_wheel_mid_right_torque
    drivetrain_wheel_rear_left_torque
    drivetrain_wheel_rear_right_torque

## Detailed drivetrain

**Input signals**

    drivetrain_throttle_input
    drivetrain_gear_selection_input

    drivetrain_front_left_brake_engage_input
    drivetrain_front_right_brake_engage_input
    drivetrain_mid_left_brake_engage_input
    drivetrain_mid_right_brake_engage_input
    drivetrain_rear_left_brake_engage_input
    drivetrain_rear_right_brake_engage_input

    drivetrain_front_diff_lock_input
    drivetrain_mid_diff_lock_input
    drivetrain_rear_diff_lock_input
    drivetrain_mid_center_axle_lock_input
    drivetrain_rear_center_axle_lock_input

**Output signals**

    drivetrain_engine_speed_rpm
    drivetrain_engine_torque
    drivetrain_gear_selection
    drivetrain_gear_ratio

    drivetrain_front_diff_lock_engaged
    drivetrain_mid_diff_lock_engaged
    drivetrain_rear_diff_lock_engaged
    drivetrain_mid_center_axle_lock_engaged
    drivetrain_rear_center_axle_lock_engaged

    drivetrain_wheel_front_left_torque
    drivetrain_wheel_front_right_torque
    drivetrain_wheel_mid_left_torque
    drivetrain_wheel_mid_right_torque
    drivetrain_wheel_rear_left_torque
    drivetrain_wheel_rear_right_torque

    drivetrain_torque_converter_slip_velocity
    drivetrain_torque_converter_turbine_torque
    drivetrain_torque_converter_pump_torque

## References

Model properties are based on:

1. Komatsu HM400-5 data sheet
   https://www.komatsu.com/content/dam/komatsu/websites/en-us/miscellaneous-web-site-assets/HM400_5_AESS878_0225_v2.pdf

2. Komatsu HD405-6 (engine reference)
   https://www.komatsu.eu/Assets/GetBrochureByProductName.aspx?id=HD325-6&langID=en

3. Komatsu HM400-5 Shop Manual (SEN06519-06)
