This commit is contained in:
gab-k committed 2025-11-29 17:42:16 +00:00
1 parent 947d212be5
commit 2e458079f4
6 files changed
+74 -17

No files matched your search

Binary file not shown.
Binary file not shown.
@@ -72,7 +72,7 @@ The *Speed Helper* block effectively sets the setpoint of the controller accordi
For feedback the back EMF voltage *V_EMF* is measured via voltage divider and ADC. *V_EMF* is proportional to the motor speed.
While the central component is the PID controller, there is an additional block called `Feed-forward <https://en.wikipedia.org/wiki/Feed_forward_(control)>`_ that has an impact on the control output variable. The Feed-forward block adds an additional offset to the output depending on the setpoint; this is done to achieve better control. A more detailed explanation regarding Feed-forward can be found below. The speed helper block corresponds to the ``speed_helper()`` function, which delays changing the setpoint according to the configured deceleration/acceleration rates.
While the central component is the PID controller, there is an additional block called `Feed-forward <https://en.wikipedia.org/wiki/Feed_forward_(control)>`_ that has an impact on the control output variable. The Feed-forward block adds an additional offset to the output depending on the setpoint; this is done to achieve better control. A more detailed explanation regarding Feed-forward can be found below. The speed helper block corresponds to the :c:func:`speed_helper()` function, which delays changing the setpoint according to the configured deceleration/acceleration rates.
.. figure:: ../../../svg/sw/Block_Diagram_Digital_Controller.svg
:alt: Block Diagram - Digital Controller
@@ -90,16 +90,35 @@ 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 :c:func:`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 :c:func:`speed_helper` function then uses this table to gradually adjust the setpoint based on the configured acceleration and deceleration rates.
Startup Controller
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Used on startup, meaning when the motor is not moving. First the startup controller retrieves the last `BASE_PWM_ARR_LEN` base PWM levels.
The base pwm levels are not retained on a power cycle. That means when there is no previous base PWM level saved, the startup controller will start ramping up from 0.
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.
The startup controller is used when the motor is stationary to find the minimum PWM level required to overcome static friction. This process is not retained on a power cycle.
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.
The initial PWM level for the startup sequence is determined as follows:
- If previous successful startup levels are saved in memory, the controller calculates their average, :math:`\bar{b}`, and sets the initial PWM level to :math:`\frac{2}{3} \cdot \bar{b}`.
- If no previous levels are saved, the ramp-up starts from a PWM level of 0.
From this starting point, the controller progressively ramps up the duty cycle until motor movement is detected. The ramp-up is not smooth but occurs in steps, with the step size determined by the maximum PWM level (which is a function of the PWM frequency).
If the PWM level reaches its maximum without motor movement, the controller reduces the starting level by half and retries, preventing excessive power to a stalled motor.
Once movement is detected (via back-EMF voltage), the current PWM `level` is saved as a new base value for future startups. This value is also multiplied by `K_FF` (from CV47) and used as the feed-forward term for the PID controller.
@@ -156,6 +175,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 :c:func:`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 :c:func:`init_controller` function based on the corresponding CV values.
.. _feed_forward:
@@ -167,10 +190,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 :c:func:`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 :c:func:`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 :c:func:`speed_helper` are needed for a single speed step change. For example, if the acceleration rate is set to 5, the :c:func:`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_61). 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
------------------------------
+1 -1
View File
@@ -1 +1 @@
Search.setIndex({"alltitles":{"1. Where to get the board?":[[0,"where-to-get-the-board"]],"2. Production files?":[[0,"production-files"]],"3. Building the software":[[0,"building-the-software"]],"4. Flashing the software":[[0,"flashing-the-software"]],"4.1. Flashing the software via .uf2 file":[[0,"flashing-the-software-via-uf2-file"]],"4.2. Flashing the software via SWD":[[0,"flashing-the-software-via-swd"]],"5. Wiring":[[0,"wiring"]],"6. Resolving issues":[[0,"resolving-issues"]],"Auxiliary Outputs":[[1,"auxiliary-outputs"],[2,"auxiliary-outputs"]],"Back-EMF voltage measurement":[[11,"back-emf-voltage-measurement"]],"CV List":[[5,"cv-list"]],"CV Reset:":[[8,"cv-reset"]],"CV.h":[[9,"cv-h"]],"CV_{116} to CV_{171} - PWM Slice configuration":[[5,"cv-116-to-cv-171-pwm-slice-configuration"]],"CV_{11} - Packet timeout":[[5,"cv-11-packet-timeout"]],"CV_{12} - Permitted operating modes":[[5,"cv-12-permitted-operating-modes"]],"CV_{17} & CV_{18} - 14-Bit extended/long address":[[5,"cv-17-cv-18-14-bit-extended-long-address"]],"CV_{1} - Basic address":[[5,"cv-1-basic-address"]],"CV_{29} - Decoder Configuration":[[5,"cv-29-decoder-configuration"]],"CV_{2} - v_{min}":[[5,"cv-2-v-min"]],"CV_{31} & CV_{32} - Extended CV pointer (Read-Only)":[[5,"cv-31-cv-32-extended-cv-pointer-read-only"]],"CV_{3} - Acceleration rate":[[5,"cv-3-acceleration-rate"]],"CV_{4} - Deceleration rate":[[5,"cv-4-deceleration-rate"]],"CV_{5} - v_{max}":[[5,"cv-5-v-max"]],"CV_{6} - v_{mid}":[[5,"cv-6-v-mid"]],"CV_{7} - Version No. (Read-Only)":[[5,"cv-7-version-no-read-only"]],"CV_{8} - Manufacturer (Read-Only)":[[5,"cv-8-manufacturer-read-only"]],"CV_{9} - Motor PWM Frequency":[[5,"cv-9-motor-pwm-frequency"]],"Check your motor:":[[8,"check-your-motor"]],"Checking the power supply:":[[8,"checking-the-power-supply"]],"Complete Schematic":[[1,"complete-schematic"],[2,"complete-schematic"]],"Configuration Variables (CV)":[[5,null]],"Contents:":[[4,null],[7,null],[10,null]],"Control Loop & Digital Controller":[[11,"control-loop-digital-controller"]],"DCC signal decoding":[[11,"dcc-signal-decoding"]],"Debugging and Logging":[[6,null]],"Debugging via SWD":[[6,"debugging-via-swd"]],"Electrical Characteristics":[[1,"electrical-characteristics"],[2,"electrical-characteristics"]],"Electrical Characteristics & Absolute Maximum Ratings":[[1,"id2"],[2,"id2"]],"Enable logging and or debug via SWD":[[8,"enable-logging-and-or-debug-via-swd"]],"Feed-forward":[[11,"id2"]],"GPIO":[[1,"gpio"],[2,"gpio"]],"Gain Scheduling":[[11,"gain-scheduling"]],"Getting started":[[0,null]],"Hardware":[[3,null]],"Input Stage":[[1,"input-stage"],[2,"input-stage"]],"Legacy":[[3,"legacy"]],"Logging":[[6,"logging"]],"Microcontroller":[[1,"microcontroller"],[2,"microcontroller"]],"Motor Driver":[[1,"motor-driver"],[2,"motor-driver"]],"Other":[[7,null]],"Overview":[[1,null],[2,null],[11,"overview"]],"PID Controller":[[11,"pid-controller"]],"RP2040-Decoder Documentation":[[4,null]],"Reset all CVs":[[5,"reset-all-cvs"]],"Software":[[10,null]],"Software Description":[[11,null]],"Speed step configuration":[[5,"speed-step-configuration"]],"Startup Controller":[[11,"startup-controller"]],"Troubleshooting":[[8,null]],"USB":[[3,"usb"]],"Wiring the Decoder":[[1,"wiring-the-decoder"],[2,"wiring-the-decoder"]],"core0.h":[[9,null]],"core1.h":[[9,"core1-h"]],"shared.h":[[9,"shared-h"]]},"docnames":["gs/getting_started","hardware/Legacy/hw_description","hardware/USB/hw_description","hardware/index","index","other/CV_list","other/debug_logging","other/index","other/troubleshooting","software/header_files","software/index","software/sw_description"],"envversion":{"sphinx":65,"sphinx.domains.c":3,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":9,"sphinx.domains.index":1,"sphinx.domains.javascript":3,"sphinx.domains.math":2,"sphinx.domains.python":4,"sphinx.domains.rst":2,"sphinx.domains.std":2},"filenames":["gs/getting_started.rst","hardware/Legacy/hw_description.rst","hardware/USB/hw_description.rst","hardware/index.rst","index.rst","other/CV_list.rst","other/debug_logging.rst","other/index.rst","other/troubleshooting.rst","software/header_files.rst","software/index.rst","software/sw_description.rst"],"indexentries":{"_125m (c macro)":[[9,"c._125M",false]],"absolute_val (c++ function)":[[9,"_CPPv412absolute_vali",false]],"acknowledge (c++ function)":[[9,"_CPPv411acknowledgev",false]],"adc_calibration_iterations (c macro)":[[9,"c.ADC_CALIBRATION_ITERATIONS",false]],"adc_offset_adjustment (c++ function)":[[9,"_CPPv421adc_offset_adjustment8uint32_t",false]],"address_evaluation (c++ function)":[[9,"_CPPv418address_evaluation6size_tA_K7uint8_t",false]],"adjust_pwm_level (c++ function)":[[9,"_CPPv416adjust_pwm_level8uint16_t",false]],"base_pwm_arr_len (c macro)":[[9,"c.BASE_PWM_ARR_LEN",false]],"bits_to_dcc_packet_data (c++ function)":[[9,"_CPPv423bits_to_dcc_packet_dataP12dcc_packet_t",false]],"call_flash_do_cmd (c++ function)":[[9,"_CPPv417call_flash_do_cmdPv",false]],"call_flasLine truncated
Search.setIndex({"alltitles":{"1. Where to get the board?":[[0,"where-to-get-the-board"]],"2. Production files?":[[0,"production-files"]],"3. Building the software":[[0,"building-the-software"]],"4. Flashing the software":[[0,"flashing-the-software"]],"4.1. Flashing the software via .uf2 file":[[0,"flashing-the-software-via-uf2-file"]],"4.2. Flashing the software via SWD":[[0,"flashing-the-software-via-swd"]],"5. Wiring":[[0,"wiring"]],"6. Resolving issues":[[0,"resolving-issues"]],"Auxiliary Outputs":[[1,"auxiliary-outputs"],[2,"auxiliary-outputs"]],"Back-EMF voltage measurement":[[11,"back-emf-voltage-measurement"]],"CV List":[[5,"cv-list"]],"CV Reset:":[[8,"cv-reset"]],"CV.h":[[9,"cv-h"]],"CV_{116} to CV_{171} - PWM Slice configuration":[[5,"cv-116-to-cv-171-pwm-slice-configuration"]],"CV_{11} - Packet timeout":[[5,"cv-11-packet-timeout"]],"CV_{12} - Permitted operating modes":[[5,"cv-12-permitted-operating-modes"]],"CV_{17} & CV_{18} - 14-Bit extended/long address":[[5,"cv-17-cv-18-14-bit-extended-long-address"]],"CV_{1} - Basic address":[[5,"cv-1-basic-address"]],"CV_{29} - Decoder Configuration":[[5,"cv-29-decoder-configuration"]],"CV_{2} - v_{min}":[[5,"cv-2-v-min"]],"CV_{31} & CV_{32} - Extended CV pointer (Read-Only)":[[5,"cv-31-cv-32-extended-cv-pointer-read-only"]],"CV_{3} - Acceleration rate":[[5,"cv-3-acceleration-rate"]],"CV_{4} - Deceleration rate":[[5,"cv-4-deceleration-rate"]],"CV_{5} - v_{max}":[[5,"cv-5-v-max"]],"CV_{6} - v_{mid}":[[5,"cv-6-v-mid"]],"CV_{7} - Version No. (Read-Only)":[[5,"cv-7-version-no-read-only"]],"CV_{8} - Manufacturer (Read-Only)":[[5,"cv-8-manufacturer-read-only"]],"CV_{9} - Motor PWM Frequency":[[5,"cv-9-motor-pwm-frequency"]],"Check your motor:":[[8,"check-your-motor"]],"Checking the power supply:":[[8,"checking-the-power-supply"]],"Complete Schematic":[[1,"complete-schematic"],[2,"complete-schematic"]],"Configuration Variables (CV)":[[5,null]],"Contents:":[[4,null],[7,null],[10,null]],"Control Loop & Digital Controller":[[11,"control-loop-digital-controller"]],"DCC signal decoding":[[11,"dcc-signal-decoding"]],"Debugging and Logging":[[6,null]],"Debugging via SWD":[[6,"debugging-via-swd"]],"Electrical Characteristics":[[1,"electrical-characteristics"],[2,"electrical-characteristics"]],"Electrical Characteristics & Absolute Maximum Ratings":[[1,"id2"],[2,"id2"]],"Enable logging and or debug via SWD":[[8,"enable-logging-and-or-debug-via-swd"]],"Feed-forward":[[11,"id2"]],"GPIO":[[1,"gpio"],[2,"gpio"]],"Gain Scheduling":[[11,"gain-scheduling"]],"Getting started":[[0,null]],"Hardware":[[3,null]],"Input Stage":[[1,"input-stage"],[2,"input-stage"]],"Legacy":[[3,"legacy"]],"Logging":[[6,"logging"]],"Microcontroller":[[1,"microcontroller"],[2,"microcontroller"]],"Motor Driver":[[1,"motor-driver"],[2,"motor-driver"]],"Other":[[7,null]],"Overview":[[1,null],[2,null],[11,"overview"]],"PID Controller":[[11,"pid-controller"]],"RP2040-Decoder Documentation":[[4,null]],"Reset all CVs":[[5,"reset-all-cvs"]],"Software":[[10,null]],"Software Description":[[11,null]],"Speed Helper":[[11,"speed-helper"]],"Speed Table Initialization":[[11,"speed-table-initialization"]],"Speed step configuration":[[5,"speed-step-configuration"]],"Startup Controller":[[11,"startup-controller"]],"Troubleshooting":[[8,null]],"USB":[[3,"usb"]],"Wiring the Decoder":[[1,"wiring-the-decoder"],[2,"wiring-the-decoder"]],"core0.h":[[9,null]],"core1.h":[[9,"core1-h"]],"shared.h":[[9,"shared-h"]]},"docnames":["gs/getting_started","hardware/Legacy/hw_description","hardware/USB/hw_description","hardware/index","index","other/CV_list","other/debug_logging","other/index","other/troubleshooting","software/header_files","software/index","software/sw_description"],"envversion":{"sphinx":65,"sphinx.domains.c":3,"sphinx.domains.changeset":1,"sphinx.domains.citation":1,"sphinx.domains.cpp":9,"sphinx.domains.index":1,"sphinx.domains.javascript":3,"sphinx.domains.math":2,"sphinx.domains.python":4,"sphinx.domains.rst":2,"sphinx.domains.std":2},"filenames":["gs/getting_started.rst","hardware/Legacy/hw_description.rst","hardware/USB/hw_description.rst","hardware/index.rst","index.rst","other/CV_list.rst","other/debug_logging.rst","other/index.rst","other/troubleshooting.rst","software/header_files.rst","software/index.rst","software/sw_description.rst"],"indexentries":{"_125m (c macro)":[[9,"c._125M",false]],"absolute_val (c++ function)":[[9,"_CPPv412absolute_vali",false]],"acknowledge (c++ function)":[[9,"_CPPv411acknowledgev",false]],"adc_calibration_iterations (c macro)":[[9,"c.ADC_CALIBRATION_ITERATIONS",false]],"adc_offset_adjustment (c++ function)":[[9,"_CPPv421adc_offset_adjustment8uint32_t",false]],"address_evaluation (c++ function)":[[9,"_CPPv418address_evaluation6size_tA_K7uint8_t",false]],"adjust_pwm_level (c++ function)":[[9,"_CPPv416adjust_pwm_level8uint16_t",false]],"base_pwm_arr_len (c macro)":[[9,"c.BASE_PWM_ARR_LEN",false]],"bits_to_dcc_packet_data (c++ function)":[[9,"_CPPv423bits_to_dcc_packet_dataP12dcc_pacLine truncated
+1
View File
@@ -89,6 +89,7 @@
<li class="toctree-l1"><a class="reference internal" href="sw_description.html">Software Description</a><ul>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html#control-loop-digital-controller">Control Loop &amp; Digital Controller</a><ul>
<li class="toctree-l3"><a class="reference internal" href="sw_description.html#speed-table-initialization">Speed Table Initialization</a></li>
<li class="toctree-l3"><a class="reference internal" href="sw_description.html#startup-controller">Startup Controller</a></li>
<li class="toctree-l3"><a class="reference internal" href="sw_description.html#pid-controller">PID Controller</a></li>
<li class="toctree-l3"><a class="reference internal" href="sw_description.html#back-emf-voltage-measurement">Back-EMF voltage measurement</a></li>
+31 -8
View File
@@ -51,6 +51,7 @@
<li class="toctree-l2 current"><a class="current reference internal" href="#">Software Description</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#control-loop-digital-controller">Control Loop &amp; Digital Controller</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#speed-table-initialization">Speed Table Initialization</a></li>
<li class="toctree-l4"><a class="reference internal" href="#startup-controller">Startup Controller</a></li>
<li class="toctree-l4"><a class="reference internal" href="#pid-controller">PID Controller</a></li>
<li class="toctree-l4"><a class="reference internal" href="#back-emf-voltage-measurement">Back-EMF voltage measurement</a></li>
@@ -189,7 +190,7 @@
<p>The block diagram above shows the (simplified) control loop. The actual digital controller block is explained below.</p>
<p>The <em>Speed Helper</em> block effectively sets the setpoint of the controller according to the CV configured acceleration and deceleration rates and actual target speedstep.</p>
<p>For feedback the back EMF voltage <em>V_EMF</em> is measured via voltage divider and ADC. <em>V_EMF</em> is proportional to the motor speed.</p>
<p>While the central component is the PID controller, there is an additional block called <a class="reference external" href="https://en.wikipedia.org/wiki/Feed_forward_(control)">Feed-forward</a> that has an impact on the control output variable. The Feed-forward block adds an additional offset to the output depending on the setpoint; this is done to achieve better control. A more detailed explanation regarding Feed-forward can be found below. The speed helper block corresponds to the <code class="docutils literal notranslate"><span class="pre">speed_helper()</span></code> function, which delays changing the setpoint according to the configured deceleration/acceleration rates.</p>
<p>While the central component is the PID controller, there is an additional block called <a class="reference external" href="https://en.wikipedia.org/wiki/Feed_forward_(control)">Feed-forward</a> that has an impact on the control output variable. The Feed-forward block adds an additional offset to the output depending on the setpoint; this is done to achieve better control. A more detailed explanation regarding Feed-forward can be found below. The speed helper block corresponds to the <code class="xref c c-func docutils literal notranslate"><span class="pre">speed_helper()</span></code> function, which delays changing the setpoint according to the configured deceleration/acceleration rates.</p>
<figure class="align-center" id="id6">
<img alt="Block Diagram - Digital Controller" src="../_images/Block_Diagram_Digital_Controller.svg" />
<figcaption>
@@ -203,14 +204,28 @@ The base PWM level is equivalent to a certain PWM duty cycle.
The base level gets saved and added to the output of the PID controller which handles motor control when the motor is in motion.
This means the actual output of the PID controller is the sum of the PID output and the base PWM level. This is referred to as the <a class="reference internal" href="#id2"><span class="std std-ref">feed forward</span></a> block.
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.</p>
<section id="speed-table-initialization">
<h3>Speed Table Initialization<a class="headerlink" href="#speed-table-initialization" title="Link to this heading"></a></h3>
<p>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 <code class="xref c c-func docutils literal notranslate"><span class="pre">init_controller()</span></code> function. The shape of the speed curve can be configured using three CV values: <cite>V_min</cite> (CV2), <cite>V_mid</cite> (CV6), and <cite>V_max</cite> (CV5).</p>
<ul class="simple">
<li><p><strong>V_min (CV2):</strong> Defines the starting voltage (setpoint) for the first speed step.</p></li>
<li><p><strong>V_mid (CV6):</strong> Sets the voltage at the midpoint of the speed range (speed step 64).</p></li>
<li><p><strong>V_max (CV5):</strong> Determines the maximum voltage at the highest speed step (126).</p></li>
</ul>
<p>The speed table is calculated with two linear interpolations: one from <cite>V_min</cite> to <cite>V_mid</cite> and another from <cite>V_mid</cite> to <cite>V_max</cite>. 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.</p>
<p>The <code class="xref c c-func docutils literal notranslate"><span class="pre">speed_helper()</span></code> function then uses this table to gradually adjust the setpoint based on the configured acceleration and deceleration rates.</p>
</section>
<section id="startup-controller">
<h3>Startup Controller<a class="headerlink" href="#startup-controller" title="Link to this heading"></a></h3>
<p>Used on startup, meaning when the motor is not moving. First the startup controller retrieves the last <cite>BASE_PWM_ARR_LEN</cite> base PWM levels.
The base pwm levels are not retained on a power cycle. That means when there is no previous base PWM level saved, the startup controller will start ramping up from 0.
When there is less than <cite>BASE_PWM_ARR_LEN</cite> base PWM levels saved, the startup controller will ramp up from the average of the saved base PWM levels.</p>
<p>After the startup controller retrieved the average of the last base pwm levels <span class="math notranslate nohighlight">\(\bar{b}\)</span> it sets a PWM duty cycle level of <span class="math notranslate nohighlight">\(\frac{2}{3} \cdot \bar{b}\)</span> 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 <cite>K_FF</cite> and used as a reference for the <a class="reference internal" href="#id2"><span class="std std-ref">feed forward</span></a> block.</p>
<p>The startup controller is used when the motor is stationary to find the minimum PWM level required to overcome static friction. This process is not retained on a power cycle.</p>
<p>The initial PWM level for the startup sequence is determined as follows:</p>
<ul class="simple">
<li><p>If previous successful startup levels are saved in memory, the controller calculates their average, <span class="math notranslate nohighlight">\(\bar{b}\)</span>, and sets the initial PWM level to <span class="math notranslate nohighlight">\(\frac{2}{3} \cdot \bar{b}\)</span>.</p></li>
<li><p>If no previous levels are saved, the ramp-up starts from a PWM level of 0.</p></li>
</ul>
<p>From this starting point, the controller progressively ramps up the duty cycle until motor movement is detected. The ramp-up is not smooth but occurs in steps, with the step size determined by the maximum PWM level (which is a function of the PWM frequency).</p>
<p>If the PWM level reaches its maximum without motor movement, the controller reduces the starting level by half and retries, preventing excessive power to a stalled motor.</p>
<p>Once movement is detected (via back-EMF voltage), the current PWM <cite>level</cite> is saved as a new base value for future startups. This value is also multiplied by <cite>K_FF</cite> (from CV47) and used as the feed-forward term for the PID controller.</p>
</section>
<section id="pid-controller">
<h3>PID Controller<a class="headerlink" href="#pid-controller" title="Link to this heading"></a></h3>
@@ -255,6 +270,8 @@ d_n &amp;= \frac{2 K_D \cdot \left(e_n - e_{n-1}\right) + \left(2 \tau - T_s\rig
</figcaption>
</figure>
<p>Another aspect to consider is the implementation of <a class="reference external" href="https://en.wikipedia.org/wiki/Gain_scheduling">gain scheduling</a>. K<sub>P</sub> is a function of the current setpoint. Often it is favorable to have a higher proportional gain K<sub>P</sub> for slow speeds, achieving better control results. The illustration above shows the default setting for K<sub>P</sub>. CV_54 &amp; CV_55 are used to set K<sub>P</sub> &#64; x<sub>0</sub>, CV_56 &amp; CV_57 for K<sub>P</sub> &#64; x<sub>1</sub>, and CV_58 &amp; CV_59 for K<sub>P</sub> &#64; x<sub>2</sub>. Additionally, CV_60 is used to shift x<sub>1</sub> from the leftmost point (0% = 0/255) to the rightmost point (100% = 255/255).</p>
<p>The <code class="xref c c-func docutils literal notranslate"><span class="pre">get_kp()</span></code> function implements this gain scheduling. It calculates the proportional gain <cite>K_p</cite> based on the current setpoint <cite>sp</cite>. The function uses two different linear equations to determine <cite>K_p</cite>, depending on whether the setpoint is above or below the <cite>k_p_x_1</cite> threshold. This creates a piecewise linear function for <cite>K_p</cite>, allowing for different gain characteristics at different speed ranges.</p>
<p>The parameters for these linear equations (<cite>k_p_m_1</cite>, <cite>k_p_m_2</cite>, <cite>k_p_y_0</cite>, <cite>k_p_y_1</cite>) are pre-calculated in the <code class="xref c c-func docutils literal notranslate"><span class="pre">init_controller()</span></code> function based on the corresponding CV values.</p>
</section>
<section id="id2">
<span id="id3"></span><h4>Feed-forward<a class="headerlink" href="#id2" title="Link to this heading"></a></h4>
@@ -262,10 +279,16 @@ d_n &amp;= \frac{2 K_D \cdot \left(e_n - e_{n-1}\right) + \left(2 \tau - T_s\rig
In essence this means that the output of the PID controller is not only the sum of the proportional, integral, and derivative parts, but also the base PWM level.
The base PWM level is set by the startup controller and is the PWM level at which the motor starts moving.</p>
</section>
<section id="speed-helper">
<h4>Speed Helper<a class="headerlink" href="#speed-helper" title="Link to this heading"></a></h4>
<p>The <code class="xref c c-func docutils literal notranslate"><span class="pre">speed_helper()</span></code> 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.</p>
<p>Instead of instantly changing the motor’s setpoint to the new target speed step, the <code class="xref c c-func docutils literal notranslate"><span class="pre">speed_helper()</span></code> function gradually increments or decrements the current setpoint based on the acceleration (CV3) and deceleration (CV4) rates. These CVs determine how many calls to <code class="xref c c-func docutils literal notranslate"><span class="pre">speed_helper()</span></code> are needed for a single speed step change. For example, if the acceleration rate is set to 5, the <code class="xref c c-func docutils literal notranslate"><span class="pre">speed_helper()</span></code> must be called 5 times before the setpoint is incremented to the next speed step. This creates a time-based acceleration/deceleration curve.</p>
<p>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.</p>
</section>
</section>
<section id="back-emf-voltage-measurement">
<h3>Back-EMF voltage measurement<a class="headerlink" href="#back-emf-voltage-measurement" title="Link to this heading"></a></h3>
<p>To provide a feedback signal proportional to the motor speed, the ADC is used to measure the <a class="reference external" href="https://en.wikipedia.org/wiki/Counter-electromotive_force">Back-EMF voltage</a>. 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%.</p>
<p>To provide a feedback signal proportional to the motor speed, the ADC is used to measure the <a class="reference external" href="https://en.wikipedia.org/wiki/Counter-electromotive_force">Back-EMF voltage</a>. 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_61). 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%.</p>
</section>
</section>
<section id="dcc-signal-decoding">