vreRlActuator.h

Go to the documentation of this file.

/*******************************************************************************
** Copyright (c) 2025 MAK Technologies
** All rights reserved.
*******************************************************************************/
 
//! \file vreRlActuator.h
//! \ingroup vreVrfRtd
//! \brief Rotary-wing aircraft actuator component for VREngage
//!
//! This file defines the DtVreRlActuator class, which provides real-time
//! dynamics integration for rotary-wing aircraft controlled through VREngage.
//! It handles joystick input, updates control surfaces, and maintains
//! proper kinematic state.
 
#pragma once
 
#include <vreVrfRtd/vreRtdBackendLibCommon.h>
#include <vreVrfmodel/vreRotaryWingActuator.h>
 
class DtSetDestroyRequest;
class DtSetRestoreRequest;
class DtSetAltitudeRequest;
class DtSetLocationRequest;
class DtSetHeadingRequest;
class DtSimMessage;
class DtBooleanInputPort;
class DtAnalogInputPort;
 
namespace makVre
{
class MiniPID;
}
 
namespace RotorLibCGF
{
class HelicopterDynamics;
};
 
namespace RlCgfVrf
{
class Bot;
class StateRepository;
class JoystickControlledBot;
class HeliCGF;
class DtVreRlParameters;
 
//! \brief Type string for VREngage rotary-wing actuator component
//!
//! Constant used to identify this component type in the simulation system.
const char TS_VREngageActuator[] = "rotorlib-cgf-vr-engage-actuator";
 
//! \brief Rotary-wing aircraft actuator component for VREngage
//!
//! This class provides the real-time dynamics integration for rotary-wing aircraft
//! controlled through VREngage. It processes joystick inputs, handles control surface
//! movement, and maintains proper kinematic state.
//!
//! \note Generally the VREngage actuator should not directly write the kinematic
//! state to the state repository but use its output ports instead. This
//! allows to use the Update Repository Actuator which in turn allows to
//! mix the RTD actuator with the VRF Flight Kinematics Actuator.
//! However, there are exceptions:
//! - setRestore() and setLocation() (same if player takes control) use
//!   state repository methods like processSetRestore() and checkAndClampAircraftOnGround()
//!   which directly write the kinematic state to the state repository.
//!
//! Reason:
//! - VRF often calls DtVrfMovingObjectStateRepository::clampToGround() after
//!   a setLocation request. This method considers the current kinematic state
//!   of the state repository which has to be assigned beforehand.
//! - The kinematic state is written to the state repository only
//!   at certain situations (setRestore, setLocation etc.) while the
//!   RTD actuator is active (see isPlayerControlled()). Hence, there should
//!   be no critical interference with other actuators.
class RTD_VRF_BACKEND_PLUGIN_EXPORT DtVreRlActuator : public makVre::DtVreRotaryWingActuatorComponent
{
public:
   //! \brief Constructor
   //! \param name The name of the component
   //! \param object The local object this component belongs to
   //! \param simManager The simulation services manager
   //! \param compDescriptor Component descriptor containing configuration
   //! \param parentRegistry Parent registry for reader/writer functionality
   //!
   //! Initializes a new rotary-wing actuator component for VREngage control.
   DtVreRlActuator(const DtString& name, DtLocalObject* object, DtSimulationServices* simManager,
      DtComponentDescriptor* compDescriptor, DtReaderWriterRegistry* parentRegistry);
 
   //! \brief Virtual destructor
   //!
   //! Cleans up resources used by the actuator component.
   virtual ~DtVreRlActuator() override;
 
   //! \brief Gets the state repository
   //! \return Pointer to the rotary-wing entity state repository
   //!
   //! Returns the state repository used by this rotary-wing aircraft.
   DtRotaryWingEntityStateRepository* getStateRepository();
 
   //! \brief Gets the component type
   //! \return The type string for this component
   //!
   //! Returns TS_VREngageActuator as the component type identifier.
#if RTD_VRF_PLUGIN_VER >= 440
   virtual const char* type() const override;
#else
   virtual DtString type() const;
#endif
 
   //! \brief Performs per-frame processing
   //!
   //! Called once per simulation frame to update the component state,
   //! process inputs, and generate outputs.
   virtual void tick() override;
 
   //! \brief Initializes the component before the first tick
   //!
   //! Performs initialization that must occur before the first tick,
   //! such as setting up initial state values.
   virtual void preFirstTickInit() override;
 
   //! \brief Initializes the component
   //! \return True if initialization was successful
   //!
   //! Performs initial setup of the component, including configuration
   //! loading and port initialization.
   virtual bool init() override;
 
   //! \brief Creates component ports
   //! \return True if port creation was successful
   //!
   //! Creates input and output ports for helicopter controls including
   //! collective, cyclic, pedals, and wheel brakes.
   virtual bool createPorts() override;
 
   //! \brief Component factory function
   //! \param name The name for the new component
   //! \param object The local object the component will belong to
   //! \param simManager The simulation services manager
   //! \param compDescriptor Component descriptor containing configuration
   //! \param parentRegistry Parent registry for reader/writer functionality
   //! \return Pointer to the newly created component
   //!
   //! Static factory function used for component creation through the component registry.
   static DtSimComponent* creator(const DtString& name, DtLocalObject* object, DtSimulationServices* simManager,
      DtComponentDescriptor* compDescriptor, DtReaderWriterRegistry* parentRegistry);
 
protected:
   //! \brief Checks if the entity is currently player-controlled
   //! \return True if the entity is player-controlled, false otherwise
   //!
   //! Determines whether the entity is currently under player control
   //! through VREngage or AI control.
   bool isPlayerControlled();
 
   //! \brief Writes output data to ports
   //!
   //! Updates all output ports with current state data.
   void writeOutputData();
 
   //! \brief Calculates current fuel consumption
   //! \return Current fuel consumption rate
   //!
   //! Calculates the current fuel consumption based on engine state and power settings.
   virtual double calculateFuel() const;
 
   //! \brief Sets the aircraft speed
   //! \param speed The new speed value to set
   //!
   //! Sets the current speed of the aircraft.
   virtual void setSpeed(DtReal speed);
 
   //! \brief Checks and adjusts the aircraft position to keep it on the ground
   //! \param localPosition The current local position to check
   //!
   //! Ensures the aircraft doesn't sink into or float above the ground
   //! when it should be in contact with the terrain.
   virtual void checkAndClampAircraftOnGround(const DtVector& localPosition);
 
   //! \brief Copies state from RTD to the state repository
   //!
   //! Copies the current state from the real-time dynamics engine to
   //! the state repository to synchronize the simulation state.
   virtual void copyStateFromRTD();
 
   //! \brief Copies state from RTD to provided parameters
   //! \param position Output parameter for position
   //! \param velocity Output parameter for velocity
   //! \param acceleration Output parameter for acceleration
   //! \param orientation Output parameter for orientation
   //! \param rotVelocity Output parameter for rotational velocity
   //!
   //! Copies the current state from the real-time dynamics engine to
   //! the provided output parameters.
   virtual void copyStateFromRTD(
      DtVector& position, DtVector& velocity, DtVector& acceleration, DtTaitBryan& orientation, DtVector& rotVelocity);
 
   //! \brief Copies state from the state repository to RTD
   //!
   //! Copies the current state from the state repository to the real-time
   //! dynamics engine to synchronize the simulation state.
   virtual void copyStateToRTD();
 
   //! \brief Gets the rotary-wing parameters
   //! \return Pointer to the rotary-wing parameters
   //!
   //! Returns the parameters used to configure this rotary-wing aircraft.
   const DtVreRlParameters* getParameters();
 
   //! \brief Enables or disables state propagation thresholding
   //! \param enable True to enable thresholding, false to disable
   //!
   //! Enables or disables thresholding for state propagation to reduce
   //! network traffic by only sending significant state changes.
   void setStatePropThresholdingEnabled(bool enable);
 
   //! \brief Sets the radio interface for this component
   //! \param radio The radio interface to use
   //!
   //! Configures the radio interface used for communication with this component.
#if RTD_VRF_PLUGIN_VER >= 430
   virtual void setRadio(DtSimRadio* radio) override;
#else
   virtual void setRadio(DtSimBaseRadio* radio);
#endif
 
   //! \brief Static callback for radio messages
   //! \param msg The received message
   //! \param usr User data pointer (points to the actuator instance)
   //!
   //! Static callback function invoked when a radio message is received.
   //! Routes the message to the appropriate instance.
   static void radioMsgCallback(DtSimMessage* msg, void* usr);
 
   //! \brief Processes a radio message
   //! \param msg The message to process
   //!
   //! Handles incoming radio messages directed to this component.
   virtual void processRadioMsg(DtSimMessage* msg);
 
   //! \brief Processes a restore request
   //! \param req The restore request to process
   //!
   //! Restores the entity to a previously saved state.
   //! Note: This method directly writes to the state repository. See class notes.
   virtual void processSetRestore(DtSetRestoreRequest* req);
 
   //! \brief Processes a location change request
   //! \param req The location request to process
   //!
   //! Changes the entity's location.
   //! Note: This method directly writes to the state repository. See class notes.
   virtual void processSetLocation(DtSetLocationRequest* req);
 
   //! \brief Processes a heading change request
   //! \param req The heading request to process
   //!
   //! Changes the entity's heading.
   virtual void processSetHeading(DtSetHeadingRequest* req);
 
   //! \brief Input port for joystick enabled state
   DtBooleanInputPort* myJoystickEnabledPort;
 
#if RTD_VRF_PLUGIN_VER < 440
   //! \brief Input port for wheel brake control (boolean version)
   DtBooleanInputPort* myWheelBrakePort;
#else
   //! \brief Input port for wheel brake control (analog version)
   DtAnalogInputPort* myWheelBrakePort;
 
   //! \brief Input port for pedal control (yaw)
   DtAnalogInputPort* myPedalPort;
 
   //! \brief Input port for collective control (lift)
   DtConstrainedAnalogInputPort* myCollectivePort;
 
   //! \brief Input port for cyclic control (pitch/roll)
   DtConstrainedDualAxisAnalogInputPort* myCyclicPort;
#endif
 
   //! \brief Flag indicating whether the entity is player-controlled
   bool myPlayerControlled;
 
   //! \brief Pointer to the real-time dynamics model
   RotorLibCGF::HelicopterDynamics* myDynamics;
 
   //! \brief Last recorded speed value
   DtReal myLastSpeed;
 
   //! \brief PID controller for X-axis stabilization
   makVre::MiniPID* myXPid;
 
   //! \brief PID controller for Y-axis stabilization
   makVre::MiniPID* myYPid;
 
   //! \brief Previous latitude value for position tracking
   float myPreviousLat;
 
   //! \brief Previous longitude value for position tracking
   float myPreviousLon;
 
   //! \brief Flag indicating whether collective control should be reversed
   bool myReverseCollective;
};
} // namespace RlCgfVrf