Small fixes and addons. Bump to 1.3.6

Author: camilo

check/qlibs_cpp_test.cpp

@@ -277,6 +277,12 @@ void test_ltisys( void )
         t += dt;
     }
 
+    pidController controller;
+    auto othergains = 1.5_kc + 0.1_ki;
+    controller.setup(1.5_kc + 0.1_ki, dt);
+    auto gains = controller.getGains();
+
+    cout << "kc = "<< gains.Kc << " ki = "<< gains.Ki << endl;
     cout << "discreteSystem"<< endl;
     //discreteTF<3,3> dtf= {
     //    { 0.1f, 0.2f, 0.3f },

library.json

@@ -16,7 +16,7 @@
       "maintainer": true
     }
   ],
-  "version": "1.3.5",
+  "version": "1.3.6",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*"

library.properties

@@ -1,5 +1,5 @@
 name=qlibs
-version=1.3.5
+version=1.3.6
 license=MIT
 author=J. Camilo Gomez C. <[email protected]>
 maintainer=J. Camilo Gomez C. <[email protected]>

src/CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required( VERSION 3.2 )
 project( qlibs-cpp
-         VERSION 1.3.5
+         VERSION 1.3.6
          DESCRIPTION "A collection of useful C++ libraries for embedded systems"
          LANGUAGES CXX )
 

src/include/ltisys.hpp

@@ -88,10 +88,10 @@ namespace qlibs {
         constexpr explicit timeDelay(real_t v) : value(v) {}
         /** @cond **/
         constexpr size_t operator()(const real_t dt) const {
-            return static_cast<size_t>((value / dt) + 0.5f);
+            return static_cast<size_t>( ( value/dt )  + 0.5_re);
         }
         constexpr size_t operator[](const real_t dt) const {
-            return static_cast<size_t>((value / dt) + 0.5f);
+            return static_cast<size_t>( ( value/dt ) + 0.5_re);
         }
         /** @endcond **/
     };
@@ -234,8 +234,8 @@ namespace qlibs {
             size_t na{ 0U };
             size_t nb{ 0U };
             real_t b0{ 0.0_re };
-            real_t min{ REAL_MIN };
-            real_t max{ REAL_MAX };
+            real_t min{ -REAL_MAX };
+            real_t max{ +REAL_MAX };
             void normalizeTransferFunction( real_t *num,
                                             real_t *den,
                                             size_t n_num,
@@ -257,8 +257,32 @@ namespace qlibs {
             * @param[in] u A sample of the input signal that excites the system
             * @return The system response.
             */
+
+            /**
+            * @brief Drives the LTI system recursively using the provided input
+            * sample.
+            * @details This function evaluates the system response based on the
+            * given input signal and the internal state of the system. It must
+            * be called periodically with a fixed time step to maintain correct
+            * system behavior.
+            *
+            * @pre The instance must be properly initialized before calling this method.
+            *
+            * @note The user is responsible for ensuring that this function is invoked at consistent
+            * intervals equal to the system's time step @a dt. This timing should
+            * be enforced using a hardware timer, software timer, real-time task,
+            * or another reliable timing mechanism.
+            *
+            * @param[in] u A new input sample that excites (drives) the system.
+            * @return The system's output (response) at the current time step.
+            */
             real_t excite( real_t u );
 
+            /// @copydoc excite(real_t)
+            real_t operator()( const real_t u ) {
+                return excite( u );
+            }
+
             /**
             * @brief Check if the LTI system is initialized.
             * @return @c true if the system has been initialized, otherwise

src/include/numa.hpp

@@ -86,7 +86,8 @@ namespace qlibs {
                        const real_t sn_2 = 0.0_re ) noexcept;
 
             /**
-            * @brief Perform a numerical integration step.
+            * @brief Perform a numerical integration step by using the specified
+            * integration method.
             * @param[in] s The input signal
             * @param[in] dt The time-step given in seconds.
             * @param[in] bUpdate Flag to update the states ( @c true by default).
@@ -97,7 +98,8 @@ namespace qlibs {
                               const bool bUpdate = true ) noexcept;
 
              /**
-            * @brief Perform a numerical derivation step by using the delta rule.
+            * @brief Perform a numerical derivation step by using the specified
+            * derivation method.
             * @param[in] s The input signal
             * @param[in] dt The time-step given in seconds.
             * @param[in] bUpdate Flag to update the states ( @c true by default).
@@ -108,8 +110,11 @@ namespace qlibs {
                            const bool bUpdate = true ) noexcept;
 
             /**
-            * @brief Set integration method .
-            * @param[in] m The desired integration method. Use one of the following:
+            * @brief Sets the numerical integration method.
+            * @details Configures the method used to approximate the integral of
+            * input values. This allows the user to select from several common
+            * numerical integration techniques.
+            * @param[in] m The desired integration method. Supported options:
             *
             * @c ::INTEGRATION_RECTANGULAR : Integrate using the Rectangular rule.
             *
@@ -119,24 +124,35 @@ namespace qlibs {
             *
             * @c ::INTEGRATION_QUADRATIC : Integrate using a parabola fit to three points.
             *
-            * @return @c true on success, otherwise return @c false.
+            * @note The effectiveness and accuracy of each method depend on the
+            * signal characteristics and time step.
+            *
+            * @return @c true if the method was successfully set; @c false otherwise.
             */
             inline void setIntegrationMethod( integrationMethod m ) noexcept
             {
                 iMethod = m;
             }
 
             /**
-            * @brief Set derivation method.
-            * @param[in] m The desired derivation method. Use one of the following:
+            * @brief Sets the numerical derivation method.
+            * @details Configures the method used to compute the numerical
+            * derivative of input values. Different methods offer varying accuracy
+            * and responsiveness depending on signal characteristics.
+            *
+            * @param[in] m The desired derivation method. Supported options:
             *
-            * @c ::DERIVATION_2POINTS : (default) Derivative using two points.
+            * @c ::DERIVATION_2POINTS : (default) Uses a simple two-point
+            * (first-order backward) difference.
             *
             * @c ::DERIVATION_BACKWARD : Derivative using the three-point backward-difference.
             *
             * @c ::DERIVATION_FORWARD : Derivative using the three-point forward-difference.
             *
-            * @return @c true on success, otherwise return @c false.
+            * @note Choose the method based on the required balance between
+            * accuracy and latency.
+            *
+            * @return @c true if the method was successfully set; @c false otherwise.
             */
             inline void setDerivationMethod( derivationMethod m ) noexcept
             {
@@ -203,6 +219,88 @@ namespace qlibs {
     }
     /*! @endcond  */
 
+    /**
+    * @brief A numerical integration class.
+    * @details A numerical integration class that can be used to compute
+    * in real-time the numerical approximation of an integral for data values
+    * sampled periodically. It supports optional output saturation limits.
+    */
+    class integrator : public nState, private nonCopyable {
+        private:
+            real_t dt;
+            real_t min{ -REAL_MAX };
+            real_t max{ +REAL_MAX };
+        public:
+            virtual ~integrator() {}
+
+            /**
+            * @brief Constructs an integrator block with a given @a timeStep time
+            * and optional initial condition.
+            * @param[in] timeStep The fixed time step (dt) used to compute the
+            * integration.
+            * @param[in] initialCondition The initial output value of the
+            * integrator. Default is 0.0.
+            * @note It is assumed that input samples will be provided at regular
+            * intervals of timeStep.
+            */
+            integrator( const real_t timeStep,
+                        const real_t initialCondition = 0.0_re );
+
+            /**
+            * @brief Sets the saturation limits for the integrator output.
+            * @param[in] minV The minimum value the output can reach.
+            * @param[in] maxV The maximum value the output can reach.
+            * @return @c true if the limits are valid and applied; @c false
+            * otherwise (e.g., minV > maxV).
+            * @note If not set, the output is unbounded.
+            */
+            bool setSaturation( const real_t minV, const real_t maxV ) noexcept;
+
+            /**
+            * @brief Performs one step of numerical integration.
+            * @param[in] xDot The input value to be integrated
+            * @return The integrated value (i.e., the output of the integrator)
+            * after applying saturation.
+            * @note This should be called at intervals equal to the time step provided in the constructor.
+            */
+            real_t operator()( const real_t xDot );
+    };
+
+    /**
+    * @brief A numerical derivative class.
+    * @details A numerical derivative class that can be used to compute
+    * in real-time the numerical approximations of derivatives for data values
+    * sampled periodically.
+    */
+    class derivative : public nState, private nonCopyable {
+        private:
+            real_t dt;
+        public:
+            virtual ~derivative() {}
+
+            /**
+            * @brief Constructs a derivative block with a given @a timeStep and
+            * optional initial condition.
+            * @param[in] timeStep The fixed time step (dt) used to compute the
+            * derivative.
+            * @param[in] initialCondition The initial input value. Default is @c 0.0
+            * @note It is assumed that input samples will be provided at regular
+            * intervals of timeStep.
+            */
+            derivative( const real_t timeStep,
+                        const real_t initialCondition = 0.0_re );
+
+            /**
+            * @brief Computes the numerical derivative based on the current
+            * input value.
+            * @param[in] xt The current input value.
+            * @return The estimated derivative of the input signal.
+            * @note This should be called at intervals equal to the time step
+            * provided in the constructor.
+            */
+            real_t operator()( const real_t xt );
+    };
+
     /** @}*/
 }
 

src/include/pid.hpp

@@ -56,11 +56,37 @@ namespace qlibs {
     * @brief PID Gains structure
     */
     struct pidGains {
-        real_t Kc;  /*!< Proportional gain */
-        real_t Ki;  /*!< Integral gain */
-        real_t Kd;  /*!< Derivative gain */
+        real_t Kc{ 0.0_re };  /*!< Proportional gain */
+        real_t Ki{ 0.0_re };  /*!< Integral gain */
+        real_t Kd{ 0.0_re };  /*!< Derivative gain */
+
+        /*! @cond  */
+        constexpr pidGains() = default;
+        constexpr pidGains(real_t kc, real_t ki, real_t kd)
+            : Kc(kc), Ki(ki), Kd(kd) {}
+
+        constexpr pidGains operator+(const pidGains& other) const {
+            return pidGains{
+                this->Kc + other.Kc,
+                this->Ki + other.Ki,
+                this->Kd + other.Kd
+            };
+        }
+        /*! @endcond  */
     };
 
+    /*! @cond  */
+    constexpr pidGains operator"" _kc(long double v) {
+        return {static_cast<real_t>(v), 0.0_re, 0.0_re};
+    }
+    constexpr pidGains operator"" _ki(long double v) {
+        return {0.0_re, static_cast<real_t>(v), 0.0_re};
+    }
+    constexpr pidGains operator"" _kd(long double v) {
+        return {0.0_re, 0.0_re, static_cast<real_t>(v)};
+    }
+    /*! @endcond  */
+
     /**
     * @brief A PID Auto-tuning object
     * @details The instance should be bound to a configured PID controller by
@@ -333,6 +359,14 @@ namespace qlibs {
             real_t control( const real_t w,
                             const real_t y ) noexcept;
 
+
+            /// @copydoc control(const real_t, const real_t)
+            real_t operator()( const real_t w,
+                               const real_t y )
+            {
+                return control( w, y );
+            }
+
             /**
             * @brief Binds the specified instance to enable the PID controller auto
             * tuning algorithm.

src/numa.cpp

@@ -64,4 +64,49 @@ real_t nState::derive( const real_t s,
 
     return ds;
 }
-/*===========================================================================*/
+/*===========================================================================*/
+integrator::integrator(const real_t timeStep, const real_t initialCondition )
+    : dt( timeStep )
+{
+    init( initialCondition, initialCondition, initialCondition );
+}
+/*===========================================================================*/
+bool integrator::setSaturation( const real_t minV,
+                                const real_t maxV ) noexcept
+{
+    bool retValue = false;
+
+    if ( maxV > minV ) {
+        min = minV;
+        max = maxV;
+        retValue = true;
+    }
+    return retValue;
+}
+/*===========================================================================*/
+real_t integrator::operator()( const real_t xDot ) {
+    real_t xt;
+
+    xt = integrate( xDot, dt );
+    if ( xt > max ) {
+        xt = max;
+    }
+    else if ( xt < min ) {
+        xt = min;
+    }
+    else {
+        /*nothing to do*/
+    }
+
+    return xt;
+}
+/*===========================================================================*/
+derivative::derivative(const real_t timeStep, const real_t initialCondition )
+    : dt( timeStep )
+{
+    init( initialCondition, initialCondition, initialCondition );
+}
+/*===========================================================================*/
+real_t derivative::operator()( const real_t xt ) {
+    return derive( xt, dt );
+}