docs: Add detailed motor control feature descriptions

Adds in-detail descriptions of the features used in the motor control to the documentation.

This includes:
- Speed Table Initialization
- Startup Controller logic
- Gain Scheduling (`get_kp` function)
- Speed Helper (acceleration/deceleration)
- Back-EMF voltage measurement details
This commit is contained in:
chatelao authored and gab-k committed 2025-11-29 18:16:47 +01:00
1 parent 24c01a0d7c
commit d4b2a7a69e
1 file changed
+34 -3
+34 -3
View File
@@ -90,6 +90,20 @@ This means the actual output of the PID controller is the sum of the PID output
The benefit of doing this is that the PID controller does not have to work in the non linear friction region of the motor, improving control performance.
Speed Table Initialization
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The speed table is a crucial component of the motor control system, as it translates the 128 speed steps received from the DCC controller into specific setpoints for the PID controller. This table is initialized once at startup in the `init_controller` function. The shape of the speed curve can be configured using three CV values: `V_min` (CV2), `V_mid` (CV6), and `V_max` (CV5).
- **V_min (CV2):** Defines the starting voltage (setpoint) for the first speed step.
- **V_mid (CV6):** Sets the voltage at the midpoint of the speed range (speed step 64).
- **V_max (CV5):** Determines the maximum voltage at the highest speed step (126).
The speed table is calculated with two linear interpolations: one from `V_min` to `V_mid` and another from `V_mid` to `V_max`. This creates a two-segment linear speed curve, which allows for a non-linear relationship between the speed step and the motor voltage. For example, you can have a gentle acceleration at low speeds and a more aggressive one at higher speeds.
The `speed_helper` function then uses this table to gradually adjust the setpoint based on the configured acceleration and deceleration rates.
Startup Controller
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -98,8 +112,11 @@ The base pwm levels are not retained on a power cycle. That means when there is
When there is less than `BASE_PWM_ARR_LEN` base PWM levels saved, the startup controller will ramp up from the average of the saved base PWM levels.
After the startup controller retrieved the average of the last base pwm levels :math:`\bar{b}` it sets a PWM duty cycle level of :math:`\frac{2}{3} \cdot \bar{b}` and then ramps up the duty cycle/PWM level until the motor starts moving.
When no previous startup PWM levels are saved the startup controller begins ramping up from 0.
The actual value at which the motor started moving is multiplied by `K_FF` and used as a reference for the :ref:`feed forward <feed_forward>` block.
When no previous startup PWM levels are saved the startup controller begins ramping up from 0. The ramp-up is not a smooth, linear increase. Instead, the PWM level is incremented in steps, with the size of each step determined by the maximum possible PWM level (`max_level`) divided by 250. This `max_level` is a function of the PWM frequency.
If the PWM level reaches `max_level` and the motor still hasn't moved, the startup controller will try again with a lower starting PWM level (half of the initial `get_initial_level()` value). This prevents the motor from receiving excessive power if it's stalled.
Once the motor starts moving (detected by a back-EMF voltage greater than 7.5), the current PWM `level` is saved as a new base PWM value. This value is then multiplied by `K_FF` (a configurable factor from CV47) and used as the feed-forward term for the PID controller.
@@ -156,6 +173,10 @@ Gain Scheduling
Another aspect to consider is the implementation of `gain scheduling <https://en.wikipedia.org/wiki/Gain_scheduling>`_. K\ :sub:`P` is a function of the current setpoint. Often it is favorable to have a higher proportional gain K\ :sub:`P` for slow speeds, achieving better control results. The illustration above shows the default setting for K\ :sub:`P`. CV_54 & CV_55 are used to set K\ :sub:`P` @ x\ :sub:`0`, CV_56 & CV_57 for K\ :sub:`P` @ x\ :sub:`1`, and CV_58 & CV_59 for K\ :sub:`P` @ x\ :sub:`2`. Additionally, CV_60 is used to shift x\ :sub:`1` from the leftmost point (0% = 0/255) to the rightmost point (100% = 255/255).
The `get_kp()` function implements this gain scheduling. It calculates the proportional gain `K_p` based on the current setpoint `sp`. The function uses two different linear equations to determine `K_p`, depending on whether the setpoint is above or below the `k_p_x_1` threshold. This creates a piecewise linear function for `K_p`, allowing for different gain characteristics at different speed ranges.
The parameters for these linear equations (`k_p_m_1`, `k_p_m_2`, `k_p_y_0`, `k_p_y_1`) are pre-calculated in the `init_controller` function based on the corresponding CV values.
.. _feed_forward:
@@ -167,10 +188,20 @@ In essence this means that the output of the PID controller is not only the sum
The base PWM level is set by the startup controller and is the PWM level at which the motor starts moving.
Speed Helper
^^^^^^^^^^^^^^^^^^
The `speed_helper` function is responsible for implementing smooth acceleration and deceleration. It is called by a repeating timer, with the interval configured by CV175. This function acts as a temporal filter for the speed setpoint.
Instead of instantly changing the motor's setpoint to the new target speed step, the `speed_helper` function gradually increments or decrements the current setpoint based on the acceleration (CV3) and deceleration (CV4) rates. These CVs determine how many calls to `speed_helper` are needed for a single speed step change. For example, if the acceleration rate is set to 5, the `speed_helper` must be called 5 times before the setpoint is incremented to the next speed step. This creates a time-based acceleration/deceleration curve.
The function also handles direction changes. If a direction change is detected, it will immediately jump to the new target speed without any delay, ensuring a responsive change in direction.
Back-EMF voltage measurement
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To provide a feedback signal proportional to the motor speed, the ADC is used to measure the `Back-EMF voltage <https://en.wikipedia.org/wiki/Counter-electromotive_force>`_. The measurement works by setting the PWM duty cycle to 0%, waiting for a certain delay time (CV_62), and then measuring x times (x = CV_63). While measuring, the array with measurement values is sorted using insertion sort. Afterwards, y elements (y = CV_63) from the left (lowest values) and z elements (z = CV_64) from the right (highest values) will be dismissed to mitigate the impact of potential outliers in measurement. The average value of the remaining values will be computed and fed back into the control algorithm. Considering default settings (100us delay, 100 samples, ~2µs sampling time), the complete measurement run, including averaging, takes about 0.3ms to 0.35ms, which effectively reduces the maximum possible duty cycle to about 93% to 94%.
To provide a feedback signal proportional to the motor speed, the ADC is used to measure the `Back-EMF voltage <https://en.wikipedia.org/wiki/Counter-electromotive_force>`_. The measurement works by setting the PWM duty cycle to 0%, waiting for a certain delay time (CV_62), and then measuring x times (x = CV_63). The ADC input channel is selected based on the motor's direction (forward or reverse). While measuring, the array with measurement values is sorted using insertion sort. Afterwards, y elements (y = CV_63) from the left (lowest values) and z elements (z = CV_64) from the right (highest values) will be dismissed to mitigate the impact of potential outliers in measurement. The average value of the remaining values will be computed and fed back into the control algorithm. Considering default settings (100us delay, 100 samples, ~2µs sampling time), the complete measurement run, including averaging, takes about 0.3ms to 0.35ms, which effectively reduces the maximum possible duty cycle to about 93% to 94%.
DCC signal decoding
------------------------------