From fc246c8f1ca6942c726d55bd3a1e303d1c32c815 Mon Sep 17 00:00:00 2001 From: Pascal Serrarens Date: Tue, 2 Jan 2024 11:52:14 +0100 Subject: [PATCH] Updated documentation --- Activation.h | 24 +++++++++++------------- CMakeLists.txt | 3 ++- DifferentialDrive.h | 15 +++++++++++++++ Placement.h | 23 ++++++++++------------- Propulsion.h | 10 ++++------ Quadcopter.h | 15 +++++++-------- Roboid.h | 25 +++++++++++++------------ Switch.h | 8 +++++--- Thing.h | 5 +++++ 9 files changed, 72 insertions(+), 56 deletions(-) diff --git a/Activation.h b/Activation.h index 546cb28..cb4efd9 100644 --- a/Activation.h +++ b/Activation.h @@ -7,28 +7,26 @@ namespace Passer { namespace RoboidControl { /// @brief Activation function for control +/// @note This is mainly for future use :-) class Activation { - public: - static float HeavisideStep(float inputValue, float bias = 0); // Range: {0,1} +public: + static float HeavisideStep(float inputValue, float bias = 0); // Range: {0,1} - static float Tanh(float inputValue); // Range: (-1, 1) + static float Tanh(float inputValue); // Range: (-1, 1) - static float Sigmoid(float inputValue); // Range: (0, 1) + static float Sigmoid(float inputValue); // Range: (0, 1) static float Linear(float inputValue, float bias = 0, float range = 0); - static float Quadratic(float inputValue, - float bias = 0, - float range = 0); // minValue = bias + static float Quadratic(float inputValue, float bias = 0, + float range = 0); // minValue = bias - static float ParticleLife(float minValue, - float maxValue, - float attraction, - float inputValue); // minValue = bias + static float ParticleLife(float minValue, float maxValue, float attraction, + float inputValue); // minValue = bias }; -} // namespace RoboidControl -} // namespace Passer +} // namespace RoboidControl +} // namespace Passer using namespace Passer::RoboidControl; #endif \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index af7da6f..41f5e38 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -43,7 +43,7 @@ include_directories( add_library(RoboidControl STATIC "Roboid.cpp" "Perception.cpp" - "PerceivedObject.cpp" + "TrackedObject.cpp" "Propulsion.cpp" "Motor.cpp" "DifferentialDrive.cpp" @@ -52,6 +52,7 @@ add_library(RoboidControl STATIC "Sensor.cpp" "Switch.cpp" "Thing.cpp" + "Quadcopter.cpp" ) enable_testing() diff --git a/DifferentialDrive.h b/DifferentialDrive.h index 406fb09..2b51025 100644 --- a/DifferentialDrive.h +++ b/DifferentialDrive.h @@ -54,7 +54,22 @@ public: /// forward, float yaw) function. virtual void SetTwistSpeed(Vector3 linear, float yaw = 0.0F, float pitch = 0.0F, float roll = 0.0F); + + /// @brief Calculate the linear velocity of the roboid based on the wheel + /// velocities + /// @return The velocity of the roboid in local space + /// @details The actual values may not be accurate, depending on the available + /// information + /// @remark This will be more expanded/detailed in a future version of Roboid + /// Control virtual Polar GetVelocity() override; + /// @brief Calculate the angular velocity of the roboid based on the wheel + /// velocities + /// @return The angular speed of the roboid in local space + /// @details The actual value may not be accurate, depending on the available + /// information + /// @remark This will be more expanded/detailed in a future version of Roboid + /// Control virtual float GetAngularVelocity() override; }; diff --git a/Placement.h b/Placement.h index 1fe1c5d..fd94ec8 100644 --- a/Placement.h +++ b/Placement.h @@ -8,7 +8,7 @@ namespace Passer { namespace RoboidControl { /// @brief A plament is used to specify where a Thing is placed on the Roboid. -/// +/// @details /// It is not always necessary to exactly specify the position and orientation /// of a Thing. You can use a simple constructor in that case: /// @@ -36,7 +36,7 @@ namespace RoboidControl { /// Placement p = Placement(thing, Vector2(-0.04F, 0.06F)); /// \endcode class Placement { - public: +public: /// @brief Placement of a Thing on a Roboid /// @param thing The Thing which is placed /// @param position The position of the Thing in carthesian coordinates @@ -44,34 +44,31 @@ class Placement { /// Negative angles are to the left. /// @param verticalAngle The vertical direction angle of the Thing. Negative /// angles are downward. - Placement(Thing* thing, - Vector3 position = Vector3::zero, - float horizontalDirection = 0.0F, - float verticalAngle = 0.0F); + Placement(Thing *thing, Vector3 position = Vector3::zero, + float horizontalDirection = 0.0F, float verticalAngle = 0.0F); /// @brief Placement of a Thing on a Roboid without position /// @param thing The Thing which is place /// @param horizontalDirection The horizontal direction angle of the Thing. /// Negative angles are to the left. /// @param verticalDirection The vertical direction angle of the Thing. /// Negative angles are downward. - Placement(Thing* thing, - float horizontalDirection, + Placement(Thing *thing, float horizontalDirection, float verticalDirection = 0.0F); /// @brief Default constructor with a zero placement Placement(); /// @brief The parent placement in the Roboid hierarchy /// @remark Reserved for future use - Placement* parent = nullptr; + Placement *parent = nullptr; /// @brief An array of children of this placement in the Roboid hierarchy /// @remark Reserved for future use - Placement** children = nullptr; + Placement **children = nullptr; /// @brief The number of children of this placemet in the Roboid hierarchy /// @remark Reserved for future use unsigned int childCount = 0; /// @brief The Thing which is placed - Thing* thing; + Thing *thing; /// @brief The position of the Thing in carthesian coordinates Vector3 position; /// @brief The angle or direction of the Thing in the horizontal plane @@ -80,6 +77,6 @@ class Placement { float verticalDirection; }; -} // namespace RoboidControl -} // namespace Passer +} // namespace RoboidControl +} // namespace Passer using namespace Passer::RoboidControl; \ No newline at end of file diff --git a/Propulsion.h b/Propulsion.h index 47d4b91..588e42b 100644 --- a/Propulsion.h +++ b/Propulsion.h @@ -13,10 +13,9 @@ class Roboid; /// @brief The Propulsion module for a Roboid is used to move the Roboid in /// space -/// -/// Usually, a specific implementation of the propulsion module is used for a -/// robot. This base class does not implement the functions to move the Roboid -/// around. +/// @details Usually, a specific implementation of the propulsion module is used +/// for a robot. This base class does not implement the functions to move the +/// Roboid around. class Propulsion { public: /// @brief Default Constructor for Propulsion @@ -40,8 +39,6 @@ public: /// index could be found Placement *GetMotorPlacement(unsigned int motorIx); - // Velocity control - /// @brief Sets the forward and rotation speed of a (grounded) Roboid /// @param forward The target forward speed /// @param yaw The target rotation speed around the vertical axis @@ -72,6 +69,7 @@ public: /// The actual unit of the angular velocity depend on the implementation virtual float GetAngularVelocity(); + /// @brief The roboid of this propulsion system Roboid *roboid = nullptr; protected: diff --git a/Quadcopter.h b/Quadcopter.h index 6c7b212..c82de96 100644 --- a/Quadcopter.h +++ b/Quadcopter.h @@ -8,30 +8,29 @@ namespace Passer { namespace RoboidControl { /// @brief Support for Quadcopter as a propulsion method +/// @note This is work in progress class Quadcopter : public Propulsion { - public: +public: /// @brief Default constuctor Quadcopter(); virtual void SetTwistSpeed(float forward, float yaw = 0.0F) override; virtual void SetTwistSpeed(Vector2 linear, float yaw = 0.0F) override; - virtual void SetTwistSpeed(Vector3 linear, - float yaw = 0.0F, - float pitch = 0.0F, - float roll = 0.0F) override; + virtual void SetTwistSpeed(Vector3 linear, float yaw = 0.0F, + float pitch = 0.0F, float roll = 0.0F) override; Vector3 GetTargetVelocity(); float GetYawSpeed(); float GetPitchSpeed(); float GetRollSpeed(); - protected: +protected: Vector3 velocity = Vector3::zero; float pitchSpeed = 0.0F; float yawSpeed = 0.0F; float rollSpeed = 0.0F; }; -} // namespace RoboidControl -} // namespace Passer +} // namespace RoboidControl +} // namespace Passer using namespace Passer::RoboidControl; \ No newline at end of file diff --git a/Roboid.h b/Roboid.h index babc90e..4a64ef6 100644 --- a/Roboid.h +++ b/Roboid.h @@ -33,41 +33,42 @@ public: /// @brief Retrieve the current position of the roboid /// @return The position in carthesian coordinates in world space - /// The origin and units of the position depends on the position tracking - /// system used. This value will be Vector3::zero unless a position is - /// received through network synchronisation + /// @details The origin and units of the position depends on the position + /// tracking system used. This value will be Vector3::zero unless a position + /// is received through network synchronisation virtual Vector3 GetPosition(); /// @brief Retrieve the current orientation of the roboid /// @return The orientation quaternion in world space - /// The origin orientation depends on the position tracking system used. This - /// value will be Quaternion::identity unless an orientation is received - /// though network synchronization + /// @details The origin orientation depends on the position tracking system + /// used. This value will be Quaternion::identity unless an orientation is + /// received though network synchronization virtual Quaternion GetOrientation(); /// @brief Update the current position of the roboid /// @param worldPosition The position of the roboid in carthesian coordinates - /// in world space The use of this function will also update the positions and + /// in world space + /// @details The use of this function will also update the positions and /// orientations of the perceived objects by the roboid /// (roboid->perception->perceivedObjects), as these are local to the /// roboid's position. virtual void SetPosition(Vector3 worldPosition); /// @brief Update the current orientation of the roboid /// @param worldOrientation The orientation of the roboid in world space - /// The use of this function will also update the orientations of the + /// @details The use of this function will also update the orientations of the /// perceived objects by the roboid (roboid->perception->perceivedObjets), /// as these are local to the roboid' orientation. virtual void SetOrientation(Quaternion worldOrientation); private: /// @brief The position of the roboid in carthesian coordinates in world space - /// This position may be set when NetworkSync is used to receive + /// @details This position may be set when NetworkSync is used to receive /// positions from an external tracking system. These values should not be set /// directly, but SetPosition should be used instead. Vector3 worldPosition = Vector3::zero; /// @brief The orientation of the roboid in world space - /// The position may be set when NetworkSync is used to receive orientations - /// from an external tracking system. This value should not be set directly, - /// but SetOrientation should be used instead. + /// @details The position may be set when NetworkSync is used to receive + /// orientations from an external tracking system. This value should not be + /// set directly, but SetOrientation should be used instead. Quaternion worldOrientation = Quaternion::identity; }; diff --git a/Switch.h b/Switch.h index 6fddb69..f15e3ad 100644 --- a/Switch.h +++ b/Switch.h @@ -7,12 +7,14 @@ namespace RoboidControl { /// @brief A digital switch input class Switch : public Sensor { - public: +public: /// @brief Default constructor Switch(); + /// @brief Test of the switch is on + /// @return true when the switch returns a HIGH value virtual bool IsOn(); }; -} // namespace RoboidControl -} // namespace Passer \ No newline at end of file +} // namespace RoboidControl +} // namespace Passer \ No newline at end of file diff --git a/Thing.h b/Thing.h index 14db035..4bccc58 100644 --- a/Thing.h +++ b/Thing.h @@ -12,10 +12,15 @@ public: /// @brief The type of Thing unsigned int type; + /// @brief The type of a switch sensor static const unsigned int SwitchType; + /// @brief The type of a distance sensor static const unsigned int DistanceSensorType; + /// @brief The type of a controlled motor static const unsigned int ControlledMotorType; + /// @brief The type of an uncontrolled motor static const unsigned int UncontrolledMotorType; + /// @brief The type of an object received from the network static const unsigned int ExternalType; /// @brief Check if the Thing is a Motor