From f160a598117c4789f321b86d45f51d0074d41a04 Mon Sep 17 00:00:00 2001
From: Gabriel Koppenstein <82903393+gab-k@users.noreply.github.com>
Date: Tue, 2 Aug 2022 10:54:07 +0200
Subject: [PATCH] Updated Software description (markdown)
---
Software-description.md | 28 +++++++++++++++++++---------
1 file changed, 19 insertions(+), 9 deletions(-)
diff --git a/Software-description.md b/Software-description.md
index 04c9c7b..e735dd8 100644
--- a/Software-description.md
+++ b/Software-description.md
@@ -4,14 +4,15 @@ The Software is structured as follows:
* Core0.c
- DCC package detection & decoding
- Programming mode (Modify and read CVs on programming track)
- - Function management
+ - ADC-Offset measurement
+ - Feed-forward base PWM measurement
+
* Core1.c
- PID motor controller
- - ADC measurements
* CV.h
- Default configuration variables
-Conveniently The Raspberry Pi Foundation provides a complete and well documented [SDK](https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf) for the RP2040. The SDK provides abstraction to a higher level and therefore there is no need to directly access any Registers directly. Everything is written using the SDK so hopefully the code is easier to understand. In the following, the motor control and the decoding of the DCC signals will be explained in particular.
+Conveniently The Raspberry Pi Foundation provides a well documented [SDK](https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf) for the RP2040. The SDK provides abstraction to a higher level and therefore there is no need to access any registers directly. Everything is written using the SDK so hopefully the code is easier to understand. In the following, the motor control and the decoding of the DCC signals will be explained.
Motor control overview
-------------------------------------
@@ -19,7 +20,7 @@ Motor control overview
***
**Block diagram - Motor control**
-The above block diagram in essence describes the functionality of the control loop. While the central component is the PID controller, there are two other blocks that have an impact on the control output variable(pid.output). Firstly there is an additional block to counteract initial friction of the motor, this block only contributes to pid.output when the desired motor speed is very low. The second additional block establishes a baseline PWM offset which is necessary due to the motor having a certain threshold PWM level after which it starts spinning. The offset is adjusted when the absolute value of pid.e_sum reaches half of its limit. The speed helper block is corresponding to the speed_helper() function which sets the current target speed according to the configured deceleration/acceleration rates.
+The above block diagram in essence describes the functionality of the control loop. 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 is corresponding to the speed_helper() function which delays changing the setpoint according to the configured deceleration/acceleration rates.
PID Controller
@@ -34,7 +35,7 @@ Output = E * (KP + KI/s + (KD*s)/(sτ+1)) = P +
* I = E * KI/s
* D = E * (KD*s)/(sτ+1)
-The continuous-time system representation can now be transformed into a discrete-time representation using bilinear transform [ s = 2*(z-1) / Ts*(z+1) ].
+The continuous-time system representation can now be transformed into a discrete-time representation using [bilinear transform](https://en.wikipedia.org/wiki/Bilinear_transform) [ s = 2*(z-1) / Ts*(z+1) ].
This results in the following difference equations which are then implemented in software:
@@ -46,19 +47,28 @@ This results in the following difference equations which are then implemented in
Also note that instead of using derivative of error, derivative on measurement is used. This is done to prevent a high derivative part in the event of a large change in setpoint.
+Gain scheduling
+-------------------------------------

-Another aspect to consider is the implementation of gain scheduling. KP is a function of the current setpoint. Often it is favorable to have a higher proportional gain KP for slow speed. The illustration above shows the default setting. CV_54 & CV_55 are used to set KP @ x0, CV_56 & CV_57 for KP @ x1 and CV_58 & CV_59 for KP @ x2. Additionally CV_60 is used to shift x1 from the leftmost point (0% = 0/255) to the rightmost point (100% = 255/255).
+Another aspect to consider is the implementation of [gain scheduling](https://en.wikipedia.org/wiki/Gain_scheduling). KP is a function of the current setpoint. Often it is favorable to have a higher proportional gain KP for slow speeds, achieving better control results. The illustration above shows the default setting for KP. CV_54 & CV_55 are used to set KP @ x0, CV_56 & CV_57 for KP @ x1 and CV_58 & CV_59 for KP @ x2. Additionally CV_60 is used to shift x1 from the leftmost point (0% = 0/255) to the rightmost point (100% = 255/255).
+Feed-forward
+-------------------------------------
+
+To achieve better control [Feed-forward](https://en.wikipedia.org/wiki/Feed_forward_(control)) is used. On startup the decoder will check for a configuration regarding Feed-forward control - when no configuration is found the decoder automatically runs a calibration to establish a base pwm level (y1) for both directions. The base pwm level (y1) will vary depending on load, motor and voltage on the tracks and can be configured with CV_176 - CV_179. If the setpoint is greater than the threshold, y2 is corrected automatically when in reaches 0.5imin or 0.5imax. CV_47 can be used to set how sensitive this correction is.
+Back-EMF voltage measurement
+-------------------------------------
+To provide a feedback signal which is 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 are being 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 measurement iterations, 5ms 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
-------------------------------------
-The detection of the DCC is very simple, it works by looking at every rising and falling edge and calculating the time between them. When the time between rising and falling edge is greater than 87μs then this is equivalent to "0", else "1".
+The detection of the DCC signal works by looking at every rising and falling edge and calculating the time between them. When the time between rising and falling edge is greater than 87μs then this is equivalent to "0", else "1" - This value then gets shifted into a 64-Bit variable.
-Decoding is done in after every falling edge. It starts with an error detection which when not passed will dismiss the received command. Then the address will be decoded and compared to the address stored in the configuration. If the address matches the command/instruction will be decoded.
+Decoding is done after every falling edge. It starts with an error detection which when not passed will dismiss the received command. Then the address will be decoded and compared to the address stored in the configuration. If the address matches the command/instruction will be decoded.
-Only the most basic instructions is are currently implemented, for example only 126 speed step instructions are supported.
+Only a few instructions are currently implemented, only 128 speed step instructions are supported.
**Implemented instructions:**
* 0011-1111 - (128 Speed Step Control) - 2 Byte length