diff --git a/sphinx/doctrees/environment.pickle b/sphinx/doctrees/environment.pickle
index fd50a82..a2efad6 100644
Binary files a/sphinx/doctrees/environment.pickle and b/sphinx/doctrees/environment.pickle differ
diff --git a/sphinx/doctrees/hardware/rev_0_3/hw_description.doctree b/sphinx/doctrees/hardware/rev_0_3/hw_description.doctree
index cf74325..4cd9e9f 100644
Binary files a/sphinx/doctrees/hardware/rev_0_3/hw_description.doctree and b/sphinx/doctrees/hardware/rev_0_3/hw_description.doctree differ
diff --git a/sphinx/doctrees/hardware/rev_1_0/hw_description.doctree b/sphinx/doctrees/hardware/rev_1_0/hw_description.doctree
index 50ccf01..17a6e50 100644
Binary files a/sphinx/doctrees/hardware/rev_1_0/hw_description.doctree and b/sphinx/doctrees/hardware/rev_1_0/hw_description.doctree differ
diff --git a/sphinx/doctrees/other/getting_started.doctree b/sphinx/doctrees/other/getting_started.doctree
index e65180c..a2cd683 100644
Binary files a/sphinx/doctrees/other/getting_started.doctree and b/sphinx/doctrees/other/getting_started.doctree differ
diff --git a/sphinx/doctrees/software/header_files.doctree b/sphinx/doctrees/software/header_files.doctree
index acda21a..0ee0c37 100644
Binary files a/sphinx/doctrees/software/header_files.doctree and b/sphinx/doctrees/software/header_files.doctree differ
diff --git a/sphinx/doctrees/software/sw_description.doctree b/sphinx/doctrees/software/sw_description.doctree
index 02edb3e..98a9c9c 100644
Binary files a/sphinx/doctrees/software/sw_description.doctree and b/sphinx/doctrees/software/sw_description.doctree differ
diff --git a/sphinx/html/_images/Block_Diagram_Control.svg b/sphinx/html/_images/Block_Diagram_Control.svg
new file mode 100644
index 0000000..11a030f
--- /dev/null
+++ b/sphinx/html/_images/Block_Diagram_Control.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/sphinx/html/_images/Block_Diagram_PID.svg b/sphinx/html/_images/Block_Diagram_PID.svg
new file mode 100644
index 0000000..c9364d6
--- /dev/null
+++ b/sphinx/html/_images/Block_Diagram_PID.svg
@@ -0,0 +1,4 @@
+
+
+
+
\ No newline at end of file
diff --git a/sphinx/html/_images/adaptive_kp.svg b/sphinx/html/_images/adaptive_kp.svg
new file mode 100644
index 0000000..c3356ca
--- /dev/null
+++ b/sphinx/html/_images/adaptive_kp.svg
@@ -0,0 +1,131 @@
+
+
diff --git a/sphinx/html/_images/feed_forward.svg b/sphinx/html/_images/feed_forward.svg
new file mode 100644
index 0000000..0b53f41
--- /dev/null
+++ b/sphinx/html/_images/feed_forward.svg
@@ -0,0 +1,159 @@
+
+
diff --git a/sphinx/html/_sources/hardware/rev_0_3/hw_description.rst.txt b/sphinx/html/_sources/hardware/rev_0_3/hw_description.rst.txt
index 24585a5..c76e382 100644
--- a/sphinx/html/_sources/hardware/rev_0_3/hw_description.rst.txt
+++ b/sphinx/html/_sources/hardware/rev_0_3/hw_description.rst.txt
@@ -1,8 +1,9 @@
Overview
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/Block_Diagram_Hardware.svg
:alt: Block Diagram
+ :align: center
Harware block diagram
@@ -22,7 +23,7 @@ The above block diagram gives a general overview regarding the operation of comp
- Crystal oscillator
Electrical Characteristics
-====================
+==============================
.. table:: Electrical Characteristics & Absolute Maximum Ratings
:widths: auto
@@ -46,10 +47,11 @@ Electrical Characteristics
(2): According to: `T2N7002BK Datasheet `_
Input Stage
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/Input_Stage.svg
:alt: Input Stage
+ :align: center
Input stage
@@ -58,20 +60,22 @@ D1 Rectifies the DCC square-wave into +V, the amplitude is not critical as long
The MOSFET on the right effectively translates the rather high DCC voltage to a suitable level for the microcontroller to process. When Q1 is turned off GPIO21 is pulled high by the RP2040 internal pull-up resistor, as soon as Q1 gets turned on (V\ :sub:`GS`\ > V\ :sub:`GS,th`\), GPIO21 gets pulled to GND potential. R1 and R2 ensure that V\ :sub:`GS`\ doesn't exceed ±20V.
Motor Driver
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/Motor_Driver.svg
:alt: Motor Driver
+ :align: center
Motor driver
The Motor Driver is a special H-Bridge IC that is made for DC motors. To control the motor, it is necessary to measure the back-EMF voltage, which is directly related to the motor's speed. This is done by the ADC, which measures at Points ADC_EMF_A and ADC_EMF_B. The two resistors work together as a voltage divider.
Auxiliary Outputs
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/Aux_Outputs.svg
:alt: Auxiliary Outputs
+ :align: center
Auxiliary Outputs
@@ -79,31 +83,33 @@ Switching of loads can be done using four N-Channel MOSFETs (Q2 to Q5). The amou
GPIO
-====================
+==============================
To switch lighter loads, six GPIO soldering pads are connected to GPIO0 to GPIO5 pins. Although not yet set up in the software, they could be used as inputs as well (e.g. reed switch). GPIO0 and GPIO1 can also be used to facilitate stdio logging via UART, which can easily be set up in CMakeLists.txt.
Microcontroller
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/Microcontroller.svg
:alt: Microcontroller
+ :align: center
Microcontroller, flash memory, crystal oscillator, ...
The Microcontroller needs a crystal oscillator for its clock. External flash memory holds the configuration variables and the program itself. R3 & C14 are used to filter ADC_AVDD (ADC Reference Voltage).
Complete Schematic
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/RP2040-Decoder.svg
:alt: Complete Schematic
+ :align: center
Complete Schematic
BOM & Alternative Parts
-====================
+==============================
.. table:: BOM
:widths: auto
@@ -142,14 +148,16 @@ Alternative for HT7533S:
.. _wiring_rev_0_3:
+
Wiring the Decoder
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_0_3/Wiring_diagram.svg
- :width: 700
- :alt: Wiring Diagram
+ :align: center
+ :width: 700
+ :alt: Wiring Diagram
- Wiring Diagram
+ Wiring Diagram
The illustration above provides an example of a wiring configuration.
It supports the connection of up to 4 transistor-switched outputs and 6 GPIOs for lighter loads or custom applications.
diff --git a/sphinx/html/_sources/hardware/rev_1_0/hw_description.rst.txt b/sphinx/html/_sources/hardware/rev_1_0/hw_description.rst.txt
index dc039ef..2bf67a9 100644
--- a/sphinx/html/_sources/hardware/rev_1_0/hw_description.rst.txt
+++ b/sphinx/html/_sources/hardware/rev_1_0/hw_description.rst.txt
@@ -1,7 +1,8 @@
Overview
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/Block_Diagram_Hardware.svg
+ :align: center
:alt: Block Diagram
Harware block diagram
@@ -23,7 +24,7 @@ The above block diagram gives a general overview regarding the operation of comp
- USB Connector
Electrical Characteristics
-====================
+==============================
.. table:: Electrical Characteristics & Absolute Maximum Ratings
:widths: auto
@@ -49,9 +50,10 @@ Electrical Characteristics
(3): T\ :sub:`Case`\ = 25°C, keep power dissipation, thermal resistance the corresponding temperature rise ΔT and switching losses in PWM mode in mind!
Input Stage
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/Input_Stage.svg
+ :align: center
:alt: Input Stage
Input stage
@@ -60,9 +62,10 @@ D2 Rectifies the DCC square-wave into VDC, the amplitude is not critical as long
The MOSFET on the right effectively translates the rather high DCC voltage to a suitable level for the microcontroller to process. When Q1 is turned off GPIO21 is pulled high by the RP2040 internal pull-up resistor, as soon as Q1 gets turned on (V\ :sub:`GS`\ > V\ :sub:`GS,th`\), GPIO21 gets pulled to GND potential. R1 and R2 ensure that V\ :sub:`GS`\ doesn't exceed ±12V.
Motor Driver
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/Motor_Driver.svg
+ :align: center
:alt: Motor Driver
Motor driver
@@ -70,9 +73,10 @@ Motor Driver
The Motor Driver is a special H-Bridge IC that is made for DC motors. To control the motor, it is necessary to measure the back-EMF voltage, which is directly related to the motor's speed. This is done by the ADC, which measures at Points ADC_EMF_A and ADC_EMF_B. The two resistors work together as a voltage divider.
Auxiliary Outputs
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/Aux_Outputs.svg
+ :align: center
:alt: Auxiliary Outputs
Auxiliary Outputs
@@ -80,14 +84,15 @@ Auxiliary Outputs
Switching of loads can be done using four N-Channel MOSFETs (Q2 to Q5). The amount of current is somewhat dependend on either static R\ :sub:`DS(on)`\ losses and/or switching losses using PWM. They are switching on the low-side, which means the load effectively gets connected to GND potential as the transistor starts to conduct. GPIO24 - GPIO27 are used.
GPIO
-====================
+==============================
To switch lighter loads, six GPIO soldering pads are connected to GPIO0 to GPIO5 pins. Although not yet set up in the software, they could be used as inputs as well (e.g. reed switch). GPIO0 and GPIO1 can also be used to facilitate stdio logging via UART, which can easily be set up in CMakeLists.txt.
Microcontroller
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/Microcontroller.svg
+ :align: center
:alt: Microcontroller
Microcontroller, flash memory, crystal oscillator, USB connector, ...
@@ -95,15 +100,16 @@ Microcontroller
The Microcontroller needs a crystal oscillator for its clock. External flash memory holds the configuration variables and the program itself. The USB connector can be used to flash the software onto the decoder and also for logging via stdio (can be enabled via CMakeLists.txt). D3 is used as a status LED. R11 & C13 are used to filter ADC_AVDD (ADC Reference Voltage).
Complete Schematic
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/RP2040-Decoder.svg
+ :align: center
:alt: Complete Schematic
Complete Schematic
BOM & Alternative Parts
-====================
+==============================
.. table:: BOM
:widths: auto
@@ -142,12 +148,14 @@ Alternative for HT7533S:
.. _wiring_rev_1_0:
+
Wiring the Decoder
-====================
+==============================
.. figure:: ../../../../svg/hw/rev_1_0/Wiring_diagram.svg
:width: 700
:alt: Wiring Diagram
+ :align: center
Wiring Diagram
diff --git a/sphinx/html/_sources/index.rst.txt b/sphinx/html/_sources/index.rst.txt
index 1c9a751..3447a3d 100644
--- a/sphinx/html/_sources/index.rst.txt
+++ b/sphinx/html/_sources/index.rst.txt
@@ -15,4 +15,3 @@ RP2040-Decoder Documentation
software/index
other/index
other/troubleshooting
- other/debugging
\ No newline at end of file
diff --git a/sphinx/html/_sources/other/getting_started.rst.txt b/sphinx/html/_sources/other/getting_started.rst.txt
index 7175ebb..abcd068 100644
--- a/sphinx/html/_sources/other/getting_started.rst.txt
+++ b/sphinx/html/_sources/other/getting_started.rst.txt
@@ -1,20 +1,21 @@
Getting started
-===============
+==================================
1. Where to get the board?
---------------------------
+----------------------------------
You can choose any PCB manufacturer you like.The PCB is designed to fit with JLCPCB.com's capabilities and constraints.You can assemble the board yourself, but it's best not to do so if you're not familiar with soldering small components. Alternatively, you can order the board fully or partly assembled.Soldering the back of the PCB by hand is not too difficult. All parts are normally available at LCSC.com, who supply parts to JLCPCB.com.
2. Production files?
----------------------
+----------------------------------
In order to export the production files (Gerber/BOM/Pick and Place), you need `KiCad `_ which is open source.
In case you are ordering from JLCPCB it is recommended to use the `Fabrication-Toolkit KiCad plugin by bennymeg `_
.. _building_the_software:
+
3. Building the software
-------------------------
+----------------------------------
If you got a RP2040-Decoder with USB the easiest way to get the RP2040-Decoder up and running is to just use the precompiled .uf2 file and ignore the rest of this section.
@@ -22,8 +23,10 @@ However sometimes you might want to build by yourself, be it for debugging or to
The easiest way to do this is to just use `Visual Studio Code `_ and the Raspberry Pi Pico extension.
The `official documentation `_ of the Pi Pico does a great job of explaining this in detail.
+Note: If you are building for Hardware Rev 0.3 or below change the board defintion in your CMakeLists.txt file to: "RP2040-Decoder-board-legacy.h"
+
4. Flashing the software
-------------------------
+----------------------------------
For RP2040-Decoders with USB there is two ways of flashing the software:
@@ -37,21 +40,21 @@ For RP2040-Decoders with USB there is two ways of flashing the software:
For RP2040-Decoders without USB the only way of flashing the software is via SWD
4.1. Flashing the software via .uf2 file
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When first plugged in the RP2040 boots into Mass Storage Device mode. To flash the software, you need to drag the '.uf2' file onto the disk using any file explorer.
This will write the file to the Flash and restart the RP2040.
In case you want to repeat the flasing process, temporarily connect the solder bridge called JP1 on the back side of the board and power cycle the device.
This procedure is also described in the `Raspberry Pi Pico Datasheet Chapter 4.1 `_
4.2. Flashing the software via SWD
-^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Flashing via SWD is a little more complicated but also comes with great advantages in terms of debugging.
The book on `Getting started with Raspberry Pi Pico-series `_ does a great job of explaining how debugging works.
As already suggested in :ref:`3. ` it is recommended to use the `Visual Studio Code Extension `_.
Most relevant in the book are `Chapter 4.3. Debug `_ and `Appendix A: Debugprobe `_
5. Wiring
----------
+----------------------------------
| Please refer to the hardware section for your board:
| :ref:`Wiring Rev 1.0 `
diff --git a/sphinx/html/_sources/software/header_files.rst.txt b/sphinx/html/_sources/software/header_files.rst.txt
index a8cf886..64b3b57 100644
--- a/sphinx/html/_sources/software/header_files.rst.txt
+++ b/sphinx/html/_sources/software/header_files.rst.txt
@@ -2,27 +2,27 @@ Header files
=================
core0.h
--------
+--------------
.. doxygenfile:: core0.h
:project: RP2040-Decoder
core1.h
--------
+--------------
.. doxygenfile:: core1.h
:project: RP2040-Decoder
shared.h
--------
+--------------
.. doxygenfile:: shared.h
:project: RP2040-Decoder
CV.h
--------
+--------------
.. doxygenfile:: CV.h
:project: RP2040-Decoder
diff --git a/sphinx/html/_sources/software/sw_description.md.txt b/sphinx/html/_sources/software/sw_description.md.txt
deleted file mode 100644
index 6e243ea..0000000
--- a/sphinx/html/_sources/software/sw_description.md.txt
+++ /dev/null
@@ -1,82 +0,0 @@
-# Software Description
-
-## Overview
-
-The Software is structured as follows:
-* Core0.c
- - DCC package detection & decoding
- - Programming mode (Modify and read CVs on programming track)
- - ADC-Offset measurement
- - Feed-forward base PWM measurement
-
-* Core1.c
- - PID motor controller
-* CV.h
- - Default configuration variables
-
-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
-
-
-***
-**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 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
-
-
-
-The block diagram above shows the PID controller in the s-domain. The derivative part contains an additional digital low pass filter used to filter out high-frequency noise.
-
-Output = E * (KP + KI/s + (KD*s)/(sτ+1)) = P + I + D
-
-* P = E * KP
-* 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](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:
-
-* pn = KP * en
-* in = 0.5KI * (en + en-1) + in-1
-* dn = [ 2KD * (en - en-1) + (2τ - Ts) * dn-1 ] / [ 2τ + Ts]
-
-=> outputn = pn + in + dn
-
-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](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 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
-
-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 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 a few instructions are currently implemented, only 128 speed step instructions are supported.
-
-**Implemented instructions:**
-* 0011-1111 - (128 Speed Step Control) - 2 Byte length
-* 10XX-XXXX - (Function Group Instruction) (F0 - F12)
-* 110X-XXXX - Expansion Instruction (F13 - F31)
-
-All DCC instructions can be found in Section 9.2, 9.2.1 and 9.2.1.1 of the [NMRA Communications Standard ](https://www.nmra.org/index-nmra-standards-and-recommended-practices)
-
-
diff --git a/sphinx/html/_sources/software/sw_description.rst.txt b/sphinx/html/_sources/software/sw_description.rst.txt
new file mode 100644
index 0000000..ea8e113
--- /dev/null
+++ b/sphinx/html/_sources/software/sw_description.rst.txt
@@ -0,0 +1,151 @@
+Software Description
+==============================
+
+Overview
+------------------------------
+
+Software files high level overview:
+
+- **core0.c / core0.h**
+
+ - DCC package detection & decoding
+ - Programming mode (Modify and read CVs on programming track)
+ - ADC-Offset measurement
+
+- **core1.c / core0.h**
+
+ - PID motor controller
+ - Back-EMF voltage measurement
+
+- **shared.c / shared.h** (used by both cores)
+
+- Error handling
+- Helper functions for retrieving CV's
+
+- **CV.h**
+
+- Default configuration variables
+
+- **CMakeLists.txt**
+
+ - CMake version, SDK version, C standard version
+ - Board definitions
+ - Compile/Build options
+ - Sources files, header files
+ - Debug logging configuration (via stdio using UART/USB)
+ - Linked libraries
+
+- **RP2040-Decoder-board.h or RP2040-Decoder-board-legacy.h**
+
+ - Flash Size
+ - Pin specification
+
+ - LED pin when available
+ - UART_TX/UART_RX when used
+ - DCC input pin
+ - Motor Control PWM pins
+ - ADC pins
+
+
+
+
+Conveniently, The Raspberry Pi Foundation provides a well-documented `SDK `_ 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.
+
+Motor control
+------------------------------
+
+.. figure:: ../../../svg/sw/Block_Diagram_Control.svg
+ :alt: Block Diagram
+ :align: center
+
+ Motor control - Block diagram
+
+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 `_ 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.
+
+PID Controller
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: ../../../svg/sw/Block_Diagram_PID.svg
+ :alt: PID Controller figure
+ :align: center
+
+ PID Controller
+
+The block diagram above shows the PID controller in the s-domain. The derivative part contains an additional digital low-pass filter used to filter out high-frequency noise.
+
+.. math::
+
+ \begin{align}
+ \text{Output} &= E \cdot \left(K_P + \frac{K_I}{s} + \frac{K_D \cdot s}{s \tau + 1}\right) = P + I + D \\
+ P &= E \cdot K_P \\
+ I &= E \cdot \frac{K_I}{s} \\
+ D &= E \cdot \frac{K_D \cdot s}{s \tau + 1}
+ \end{align}
+
+With :math:`T_s` being the sampling time / controller update rate / time step of the discrete system.
+And :math:`\tau` being the filter time constant of the digital filter
+
+The continuous-time system representation can now be transformed into a discrete-time representation using `bilinear transform `_ :math:`s = \frac{2 \cdot (z - 1)}{T_s \cdot (z + 1)}`.
+
+This results in the following difference equations which are then implemented in software:
+
+.. math::
+
+ \begin{align}
+ p_n &= K_P \cdot e_n \\
+ i_n &= 0.5 \cdot K_I \cdot \left(e_n + e_{n-1}\right) + i_{n-1} \\
+ d_n &= \frac{2 K_D \cdot \left(e_n - e_{n-1}\right) + \left(2 \tau - T_s\right) \cdot d_{n-1}}{2 \tau + T_s} \\
+ \text{output}_n &= p_n + i_n + d_n
+ \end{align}
+
+
+Also note that instead of using the derivative of error, the 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. figure:: ../../../svg/sw/adaptive_kp.svg
+ :alt: Gain Scheduling figure
+ :align: center
+
+ Gain Scheduling
+
+Another aspect to consider is the implementation of `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).
+
+Feed-forward
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+.. figure:: ../../../svg/sw/feed_forward.svg
+ :alt: Feed forward figure
+ :align: center
+
+ Feed-forward
+
+
+TODO: Update this part:
+
+To achieve better control, `Feed-forward `_ 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 (y\ :sub:`1`) for both directions. The base PWM level (y\ :sub:`1`) 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, y\ :sub:`2` is corrected automatically when i\ :sub:`n` reaches 0.5i\ :sub:`min` or 0.5i\ :sub:`max`. CV_47 can be used to set how sensitive this correction is.
+
+Back-EMF voltage measurement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To provide a feedback signal proportional to the motor speed, the ADC is used to measure the `Back-EMF voltage `_. 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%.
+
+DCC signal decoding
+------------------------------
+
+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"; otherwise, "1". This value then gets shifted into a 64-Bit variable.
+
+Decoding is done after every falling edge. It starts with an error detection, which, when not passed, dismisses 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 a few instructions are currently implemented; only 128 speed step instructions are supported.
+
+**Implemented instructions:**
+
+- ``0011-1111`` - (128 Speed Step Control) - 2 Byte length
+- ``10XX-XXXX`` - (Function Group Instruction) (F0 - F12)
+- ``110X-XXXX`` - Expansion Instruction (F13 - F31)
+
+All DCC instructions can be found in Section 9.2, 9.2.1, and 9.2.1.1 of the `NMRA Communications Standard `_.
diff --git a/sphinx/html/hardware/rev_0_3/hw_description.html b/sphinx/html/hardware/rev_0_3/hw_description.html
index b5c6bda..2c73350 100644
--- a/sphinx/html/hardware/rev_0_3/hw_description.html
+++ b/sphinx/html/hardware/rev_0_3/hw_description.html
@@ -102,7 +102,7 @@
D2 Rectifies the DCC square-wave into VDC, the amplitude is not critical as long as it’s within the 25V limit. The rectified voltage VDC is then provided to the 3.3V voltage regulator and to the motor driver. The shottky diode D1 and the bridge rectifier D2 ensure a logical “or” linkage of the VBUS supply voltages and the DCC input voltage
The MOSFET on the right effectively translates the rather high DCC voltage to a suitable level for the microcontroller to process. When Q1 is turned off GPIO21 is pulled high by the RP2040 internal pull-up resistor, as soon as Q1 gets turned on (VGS> VGS,th), GPIO21 gets pulled to GND potential. R1 and R2 ensure that VGSdoesn’t exceed ±12V.
Motor Driver
-====================
-
+
diff --git a/sphinx/html/index.html b/sphinx/html/index.html
index 7b14592..bc7362e 100644
--- a/sphinx/html/index.html
+++ b/sphinx/html/index.html
@@ -18,6 +18,7 @@
+
diff --git a/sphinx/html/other/getting_started.html b/sphinx/html/other/getting_started.html
index ca3783a..f0785bf 100644
--- a/sphinx/html/other/getting_started.html
+++ b/sphinx/html/other/getting_started.html
@@ -108,6 +108,7 @@ In case you are ordering from JLCPCB it is recommended to use the Visual Studio Code and the Raspberry Pi Pico extension.
The official documentation of the Pi Pico does a great job of explaining this in detail.
+
Note: If you are building for Hardware Rev 0.3 or below change the board defintion in your CMakeLists.txt file to: “RP2040-Decoder-board-legacy.h”
Programming mode (Modify and read CVs on programming track)
ADC-Offset measurement
-
Feed-forward base PWM measurement
+
-
Core1.c
-
+
core1.c / core0.h
+
+
PID motor controller
+
Back-EMF voltage measurement
+
-
CV.h
-
+
shared.c / shared.h (used by both cores)
+
Error handling
+
Helper functions for retrieving CV’s
+
CV.h
Default configuration variables
+
CMakeLists.txt
+
+
+
CMake version, SDK version, C standard version
+
Board definitions
+
Compile/Build options
+
Sources files, header files
+
Debug logging configuration (via stdio using UART/USB)
+
Linked libraries
+
+
+
RP2040-Decoder-board.h or RP2040-Decoder-board-legacy.h
+
+
+
Flash Size
+
Pin specification
+
+
+
LED pin when available
+
UART_TX/UART_RX when used
+
DCC input pin
+
Motor Control PWM pins
+
ADC pins
+
+
-
Conveniently The Raspberry Pi Foundation provides a well documented SDK 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.
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 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.
+
+
+
+
Conveniently, The Raspberry Pi Foundation provides a well-documented SDK 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.
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 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.
The block diagram above shows the PID controller in the s-domain. The derivative part contains an additional digital low pass filter used to filter out high-frequency noise.
-
Output = E * (KP + KI/s + (KD*s)/(sτ+1)) = P + I + D
-
-
P = E * KP
-
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 block diagram above shows the PID controller in the s-domain. The derivative part contains an additional digital low-pass filter used to filter out high-frequency noise.
+
+\[\begin{split}\begin{align}
+\text{Output} &= E \cdot \left(K_P + \frac{K_I}{s} + \frac{K_D \cdot s}{s \tau + 1}\right) = P + I + D \\
+P &= E \cdot K_P \\
+I &= E \cdot \frac{K_I}{s} \\
+D &= E \cdot \frac{K_D \cdot s}{s \tau + 1}
+\end{align}\end{split}\]
+
With \(T_s\) being the sampling time / controller update rate / time step of the discrete system.
+And \(\tau\) being the filter time constant of the digital filter
+
The continuous-time system representation can now be transformed into a discrete-time representation using bilinear transform\(s = \frac{2 \cdot (z - 1)}{T_s \cdot (z + 1)}\).
This results in the following difference equations which are then implemented in software:
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.
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 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).
Also note that instead of using the derivative of error, the derivative on measurement is used. This is done to prevent a high derivative part in the event of a large change in setpoint.
-To achieve better control Feed-forward 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.
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 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).
To achieve better control, Feed-forward 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.
To provide a feedback signal which is proportional to the motor speed the ADC is used to measure the Back-EMF voltage. 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 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. 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%.
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 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 a few instructions are currently implemented, only 128 speed step instructions are supported.
+
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”; otherwise, “1”. This value then gets shifted into a 64-Bit variable.
+
Decoding is done after every falling edge. It starts with an error detection, which, when not passed, dismisses 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 a few instructions are currently implemented; only 128 speed step instructions are supported.