deploy: 3348e3a6a0
This commit is contained in:
1 parent
f1d55e4d25
commit
26ef67b84b
120 files changed
+631726
No files matched your search
@@ -0,0 +1,77 @@
|
||||
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?
|
||||
----------------------------------
|
||||
The latest release includes the production files for JLCPCB, which includes the Gerber files, BOM, and Pick and Place files. You can find the latest release `here <https://github.com/gab-k/RP2040-Decoder/releases>`_.
|
||||
|
||||
In order to manually export the production files (Gerber/BOM/Pick and Place), you need `KiCad <https://www.kicad.org/download/>`_ which is open source.
|
||||
In case you are ordering from JLCPCB it is recommended to use the `Fabrication-Toolkit KiCad plugin by bennymeg <https://github.com/bennymeg/Fabrication-Toolkit>`_
|
||||
|
||||
.. _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 in the latest `release <https://github.com/gab-k/RP2040-Decoder/releases>`_ and skip to :ref:`flashing_the_software`.
|
||||
|
||||
However sometimes you might want to build by yourself, be it for debugging or to make your own modifications to the source code.
|
||||
The easiest way to do this is to just use `Visual Studio Code <https://code.visualstudio.com/>`_ and the `Raspberry Pi Pico extension <https://marketplace.visualstudio.com/items?itemName=raspberry-pi.raspberry-pi-pico>`_.
|
||||
The `official documentation <https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf#vscode-extension>`_ of the Pi Pico does a great job of explaining this in detail.
|
||||
|
||||
.. note::
|
||||
- Make sure to choose the correct board definition file in your CMakeLists.txt file for example ``RP2040-Decoder-board-Rev-1_0`` for Hardware Rev 1.0.
|
||||
- In VSCode open the "Software" subdirectory for the extension to detect you project automatically.
|
||||
|
||||
.. _flashing_the_software:
|
||||
|
||||
4. Flashing the software
|
||||
----------------------------------
|
||||
|
||||
For RP2040-Decoders with USB there is two ways of flashing the software:
|
||||
|
||||
1. Flashing via USB using the .uf2 file by copying it with your preferred file explorer.
|
||||
2. Using Serial Wire Debug (SWD)
|
||||
|
||||
2.1. Using another RP2040/RP2350-based board with `debugprobe software <https://github.com/raspberrypi/debugprobe>`_ on it. (Could be the RP2040-Decoder itself)
|
||||
|
||||
2.2. Using any other supported SWD debug interface
|
||||
|
||||
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 flashing process, hold the button SW1 while re-plugging the decoder into your computer. The decoder should now show as a Mass Storage Device again.
|
||||
This procedure is also described in the `Raspberry Pi Pico Datasheet Chapter 4.1 <https://datasheets.raspberrypi.com/pico/pico-datasheet.pdf#_programming_the_flash>`_
|
||||
|
||||
.. _flashing_the_software_swd:
|
||||
|
||||
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 <https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf>`_ does a great job of explaining how debugging works.
|
||||
As already suggested in :ref:`building_the_software` it is recommended to use the `Visual Studio Code Extension <https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf#vscode-extension>`_.
|
||||
The most relevant sections in the book are `Chapter 4.3. Debug <https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf#_debug>`_ and `Appendix A: Debugprobe <https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf#debugprobe_section>`_
|
||||
|
||||
|
||||
5. Wiring
|
||||
----------------------------------
|
||||
|
||||
| Please refer to the hardware section for your board:
|
||||
| :ref:`Wiring Rev 1.0 <wiring_rev_1_0>`
|
||||
| :ref:`Wiring Rev 0.3 <wiring_rev_0_3>`
|
||||
|
||||
6. Resolving issues
|
||||
----------------------------------
|
||||
|
||||
If the decoder is not working as expected:
|
||||
|
||||
1. Follow the `Troubleshooting instructions <https://github.com/gab-k/RP2040-Decoder/wiki/Troubleshooting>`_
|
||||
2. If you still have trouble, create a new `discussion <https://github.com/gab-k/RP2040-Decoder/discussions>`_ or `issue <https://github.com/gab-k/RP2040-Decoder/issues>`_ and describe your question/issue.
|
||||
@@ -0,0 +1,18 @@
|
||||
Hardware
|
||||
======================
|
||||
|
||||
Revision 1.0
|
||||
------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
rev_1_0/hw_description
|
||||
|
||||
Revision 0.3
|
||||
------------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
rev_0_3/hw_description
|
||||
@@ -0,0 +1,128 @@
|
||||
Overview
|
||||
==============================
|
||||
|
||||
.. figure:: ../../../../svg/hw/rev_0_3/Block_Diagram_Hardware.svg
|
||||
:alt: Block Diagram
|
||||
:align: center
|
||||
|
||||
Harware block diagram
|
||||
|
||||
The above block diagram gives a general overview regarding the operation of components. For better illustration it has been divided into four functional blocks. Furthermore, these functional blocks can be subdivided and will be explained below.
|
||||
|
||||
- **Input Stage**
|
||||
- DCC Signal Level Shift
|
||||
- Bridge Rectifier & Voltage Regulator
|
||||
- **Motor Driver**
|
||||
- Motor Driver
|
||||
- Back EMF measurement (ADC)
|
||||
- **General Purpose**
|
||||
- GPIO
|
||||
- Auxiliary output
|
||||
- **Microcontroller**
|
||||
- Flash memory
|
||||
- Crystal oscillator
|
||||
|
||||
Electrical Characteristics
|
||||
==============================
|
||||
.. table:: Electrical Characteristics & Absolute Maximum Ratings
|
||||
:widths: auto
|
||||
|
||||
===================================================== ============================= ========= ========= =====
|
||||
Parameter Symbol Minimum Maximum Unit
|
||||
===================================================== ============================= ========= ========= =====
|
||||
Absolute max. DCC Input Voltage difference V\ :sub:`DCC`\ 0 +24 V
|
||||
Absolute max. GPIO Voltage\ :sup:`(0)`\ V\ :sub:`PIN`\ -0.5 3.3+0.5 V
|
||||
Input Voltage High\ :sup:`(0)`\ V\ :sub:`IH`\ 2.145 3.6 V
|
||||
Input Voltage Low\ :sup:`(0)`\ V\ :sub:`IL`\ 0 1.155 V
|
||||
Total GPIO Current\ :sup:`(0)`\ I\ :sub:`IOVDD`\ 50 mA
|
||||
Absolute max. motor output current\ :sup:`(1)`\ I\ :sub:`MOTOR`\ 2.8 A
|
||||
Absolute max. auxiliary output current \ :sup:`(2)`\ I\ :sub:`AUX`\ 400 mA
|
||||
===================================================== ============================= ========= ========= =====
|
||||
|
||||
|
||||
(0): According to: `RP2040 Datasheet <https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf>`_ (assuming V\ :sub:`DD`\ = 3.3V)
|
||||
|
||||
(1): According to: `BDR6133 Datasheet <https://www.lcsc.com/datasheet/lcsc_datasheet_2409291808_Bardeen-Micro--BDR6133_C2687793.pdf>`_
|
||||
|
||||
(2): According to: `T2N7002BK Datasheet <https://toshiba.semicon-storage.com/info/T2N7002BK_datasheet_en_20191025.pdf?did=30376&prodName=T2N7002BK>`_
|
||||
|
||||
.. note:: Keep in mind that realistically these maximum ratings can't be reached in practice due to thermal limitations. For example the motor current can probably not exceed 1.5A for continuous operation.
|
||||
|
||||
Input Stage
|
||||
==============================
|
||||
|
||||
.. figure:: ../../../../svg/hw/rev_0_3/Input_Stage.svg
|
||||
:alt: Input Stage
|
||||
:align: center
|
||||
|
||||
Input stage
|
||||
|
||||
D1 Rectifies the DCC square-wave into +V, the amplitude is not critical as long as it's within the 25V limit. The rectified voltage +V is then provided to the 3.3V voltage regulator (U1) and to the motor driver (U2).
|
||||
|
||||
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
|
||||
|
||||
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_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
|
||||
|
||||
|
||||
.. _wiring_rev_0_3:
|
||||
|
||||
Wiring the Decoder
|
||||
==============================
|
||||
|
||||
.. figure:: ../../../../svg/hw/rev_0_3/Wiring_diagram.svg
|
||||
:align: center
|
||||
:width: 700
|
||||
:alt: 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.
|
||||
When switching inductive loads, always include a free-wheeling diode to protect the circuit.
|
||||
@@ -0,0 +1,130 @@
|
||||
Overview
|
||||
==============================
|
||||
|
||||
.. figure:: ../../../../svg/hw/rev_1_0/Block_Diagram_Hardware.svg
|
||||
:align: center
|
||||
:alt: Block Diagram
|
||||
|
||||
Harware block diagram
|
||||
|
||||
The above block diagram gives a general overview regarding the operation of components. For better illustration it has been divided into four functional blocks. Furthermore, these functional blocks can be subdivided and will be explained below.
|
||||
|
||||
- **Input Stage**
|
||||
- DCC Signal Level Shift
|
||||
- Bridge Rectifier & Voltage Regulator
|
||||
- **Motor Driver**
|
||||
- Motor Driver
|
||||
- Back EMF measurement (ADC)
|
||||
- **General Purpose**
|
||||
- GPIO
|
||||
- Auxiliary output
|
||||
- **Microcontroller**
|
||||
- Flash memory
|
||||
- Crystal oscillator
|
||||
- USB Connector
|
||||
|
||||
Electrical Characteristics
|
||||
==============================
|
||||
.. table:: Electrical Characteristics & Absolute Maximum Ratings
|
||||
:widths: auto
|
||||
|
||||
======================================================== ============================= ========= ========= =====
|
||||
Parameter Symbol Minimum Maximum Unit
|
||||
======================================================== ============================= ========= ========= =====
|
||||
Absolute max. DCC input voltage difference V\ :sub:`DCC`\ +24 V
|
||||
Absolute max. GPIO voltage\ :sup:`(0)`\ V\ :sub:`PIN`\ -0.5 3.3+0.5 V
|
||||
Input voltage high\ :sup:`(0)`\ V\ :sub:`IH`\ 2.145 3.6 V
|
||||
Input voltage low\ :sup:`(0)`\ V\ :sub:`IL`\ 0 1.155 V
|
||||
Total GPIO Current\ :sup:`(0)`\ I\ :sub:`IOVDD`\ 50 mA
|
||||
Absolute max. motor output current\ :sup:`(1)`\ I\ :sub:`MOTOR`\ 2.8 A
|
||||
Absolute max. auxiliary output current \ :sup:`(2)(3)`\ I\ :sub:`AUX`\ 1.4 A
|
||||
======================================================== ============================= ========= ========= =====
|
||||
|
||||
|
||||
(0): According to: `RP2040 Datasheet <https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf>`_ (assuming V\ :sub:`DD`\ = 3.3V)
|
||||
|
||||
(1): According to: `BDR6133 Datasheet <https://www.lcsc.com/datasheet/lcsc_datasheet_2409291808_Bardeen-Micro--BDR6133_C2687793.pdf>`_
|
||||
|
||||
(2): According to: `Si1308EDL Datasheet <https://www.vishay.com/docs/63399/si1308edl.pdf>`_
|
||||
|
||||
(3): T\ :sub:`Case`\ = 25°C, keep power dissipation, thermal resistance the corresponding temperature rise ΔT and switching losses in PWM mode in mind!
|
||||
|
||||
.. note:: Keep in mind that realistically these maximum ratings can't be reached in practice due to thermal limitations. For example the motor current can probably not exceed 1.5A for continuous operation.
|
||||
|
||||
|
||||
Input Stage
|
||||
==============================
|
||||
|
||||
.. figure:: ../../../../svg/hw/rev_1_0/Input_Stage.svg
|
||||
:align: center
|
||||
:alt: Input Stage
|
||||
|
||||
Input stage
|
||||
|
||||
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, meaning that the decoder can be powered either by the DCC track signal or by the VBUS supply voltage which is supplied via USB connector.
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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, ...
|
||||
|
||||
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
|
||||
|
||||
|
||||
.. _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
|
||||
|
||||
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.
|
||||
When switching inductive loads, always include a free-wheeling diode to protect the circuit.
|
||||
@@ -0,0 +1,16 @@
|
||||
.. RP2040-Decoder documentation master file, created by
|
||||
sphinx-quickstart on Wed Nov 27 08:19:47 2024.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
RP2040-Decoder Documentation
|
||||
============================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:caption: Contents:
|
||||
|
||||
gs/getting_started
|
||||
hardware/index
|
||||
software/index
|
||||
other/index
|
||||
@@ -0,0 +1,126 @@
|
||||
Configuration Variables (CV)
|
||||
============================
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
- ``CV.h`` contains default values for every CV. When your board is still "factory new" these values are automatically written into flash. ``CV_65 == 255`` indicates a factory condition and resets all CVs to default.
|
||||
|
||||
- Index 0 in the CV array corresponds with ``CV_1``, index 1 corresponds with ``CV_2`` and so forth.
|
||||
|
||||
Reset all CVs
|
||||
------------------------
|
||||
|
||||
To reset all CVs to default, a value of ``8`` can be written to ``CV8``. Alternatively write a value of ``255`` to ``CV_65`` this will also reset all CVs to default, but only after power cycling the decoder.
|
||||
|
||||
Speed step configuration
|
||||
------------------------
|
||||
|
||||
.. figure:: ../../../svg/sw/speed_table.svg
|
||||
:alt: Speed Table
|
||||
:align: center
|
||||
|
||||
Speed Table
|
||||
|
||||
* :math:`v_{min} = CV_{2}`
|
||||
* :math:`v_{mid} = 16 \cdot CV_{6}`
|
||||
* :math:`v_{max} = 16 \cdot CV_{5}`
|
||||
|
||||
The figure above shows how the speed steps can be configured using the corresponding CVs. The red * represents :math:`v_{min}` which is always at speed step 1, the green * shows :math:`v_{mid}` at speed step 63, and the blue * shows :math:`v_{max}` at speed step 126.
|
||||
|
||||
CV List
|
||||
-------
|
||||
|
||||
:math:`CV_{1}` - Basic address
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Short DCC address
|
||||
|
||||
:math:`CV_{2}` - :math:`v_{min}`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Min motor voltage/speed is: :math:`v_{min} = CV_{2}`
|
||||
|
||||
:math:`CV_{3}` - Acceleration rate
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The time for one discrete acceleration time step can be calculated as :math:`CV_{3} \cdot CV_{175}`.
|
||||
|
||||
.. note:: Base speed steps are always 128/126 steps.
|
||||
|
||||
:math:`CV_{4}` - Deceleration rate
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
The time for one discrete deceleration time step can be calculated as :math:`CV_{4} \cdot CV_{175}`.
|
||||
|
||||
.. note:: Base speed steps are always 128/126 steps.
|
||||
|
||||
:math:`CV_{5}` - :math:`v_{max}`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Max motor voltage/speed is calculated as: :math:`v_{max} = 16 \cdot CV_{5}`
|
||||
|
||||
:math:`CV_{6}` - :math:`v_{mid}`
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Mid motor voltage/speed is calculated as: :math:`v_{mid} = 16 \cdot CV_{6}`
|
||||
|
||||
:math:`CV_{7}` - Version No. (Read-Only)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Writing a value of ``7`` triggers an ADC offset adjustment.
|
||||
|
||||
:math:`CV_{8}` - Manufacturer (Read-Only)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Default = ``13`` = Public Domain & Do-It-Yourself Decoders
|
||||
|
||||
Even though :math:`CV_{8}` is defined as a Read-only CV, writing a value of ``8`` resets all CV values to the default values in ``CV.h``.
|
||||
|
||||
:math:`CV_{9}` - Motor PWM Frequency
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
:math:`f_{PWM_{MOTOR}} = (CV_9 \cdot 100 + 10000) \, Hz`
|
||||
|
||||
:math:`CV_{11}` - Packet timeout
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
If no package is received for :math:`x = CV_{11}` seconds the decoder will automatically stop the motor (Emergency Stop).
|
||||
|
||||
:math:`CV_{12}` - Permitted operating modes
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Currently, DCC Digital mode is the only supported mode.
|
||||
|
||||
:math:`CV_{17}` & :math:`CV_{18}` - 14-Bit extended/long address
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Address is only used if bit5 of :math:`CV_{29}` has a value of ``1``.
|
||||
|
||||
.. image:: ../../../svg/sw/Long_address.svg
|
||||
:alt: Long Address
|
||||
:align: center
|
||||
|
||||
Bit15 and bit14 which correspond to bit7 and bit6 of :math:`CV_{17}` are always ``1``. :math:`CV_{17} = 192` & :math:`CV_{18} = 0` is also not a valid address.
|
||||
Otherwise, the valid value range of :math:`CV_{17}` ranges from ``192`` to ``231`` and ``0`` to ``255`` for :math:`CV_{18}` respectively.
|
||||
|
||||
:math:`CV_{29}` - Decoder Configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Bit0 is can be used to reverse motor direction, i.e., ``0`` = normal, ``1`` = reverse.
|
||||
Bit5 switches between basic and extended addressing modes, i.e., ``0`` = basic address, ``1`` = extended address.
|
||||
The other 6 bits are currently not in use and therefore irrelevant.
|
||||
|
||||
:math:`CV_{31}` & :math:`CV_{32}` - Extended CV pointer (Read-Only)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Not in use.
|
||||
|
||||
|
||||
:math:`CV_{116}` to :math:`CV_{171}` - PWM Slice configuration
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
.. image:: ../../../svg/sw/GPIO_slices.svg
|
||||
:alt: GPIO Slices
|
||||
:align: center
|
||||
|
||||
Every slice controls two independent output channels, duty cycle from 0% to 100% inclusive, and can be configured with several parameters:
|
||||
|
||||
* Wrap (16Bit): Sets the slice time period of x cycles - effectively determining the frequency
|
||||
* Clock Divider: Additional clock divider
|
||||
* Level Channel A / Level Channel B (16Bit each): Determining how many of the x cycles the signal is at a high level - effectively determining the duty cycle
|
||||
|
||||
To see which CVs correspond to which slice and channel, it is advisable to use ``CV.h`` as a reference.
|
||||
|
||||
The PWM frequency is calculated as follows: :math:`f_{PWM} = \frac{125 \, \text{MHz}}{(CV_{\text{clk_div}} + 1) \cdot (CV_{\text{wrap}} + 1)}`
|
||||
|
||||
The duty-cycle can be calculated as follows: :math:`D = \frac{CV_{\text{Level}}}{CV_{\text{wrap}} + 1}`
|
||||
|
||||
|
||||
A more detailed explanation regarding PWM can be found in the `RP2040-Datasheet - Chapter 4.5 <https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf>`_.
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
Debugging and Logging
|
||||
==================================
|
||||
|
||||
For logging and debugging you have to build the software yourself. This is explained here: :ref:`building_the_software`
|
||||
|
||||
.. _debugging_via_swd:
|
||||
|
||||
Debugging via SWD
|
||||
----------------------------------
|
||||
Please refer to :ref:`flashing_the_software_swd`.
|
||||
|
||||
|
||||
.. _logging:
|
||||
|
||||
Logging
|
||||
----------------------------------
|
||||
|
||||
Logging can be enabled in ``CMakeLists.txt``, and is available with two interfaces:
|
||||
|
||||
- Logging via UART RX/TX pins (GPIO0/GPIO1 by default)
|
||||
- Logging via USB CDC/ACM
|
||||
|
||||
Additionally you can make the decoder wait for input via serial port by setting LOG_WAIT to 1. For more details please see comments inside ``CMakeLists.txt``.
|
||||
@@ -0,0 +1,10 @@
|
||||
Other
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
troubleshooting
|
||||
debug_logging
|
||||
CV_list
|
||||
@@ -0,0 +1,27 @@
|
||||
Troubleshooting
|
||||
================
|
||||
|
||||
To narrow down the issue when your decoder is not working as expected, you can do the following (in no particular order):
|
||||
|
||||
Enable logging and or debug via SWD
|
||||
------------------------------------
|
||||
Log messages can be enabled and output via either UART or USB please see :ref:`logging` for details.
|
||||
For more advanced users it might also be beneficial to :ref:`debug with SWD <debugging_via_swd>`
|
||||
|
||||
Checking the power supply:
|
||||
--------------------------------------
|
||||
|
||||
* **+3V3 to GND** should be 3.3V ± 1%
|
||||
* **VDC/+V to GND** should be somewhere in the range of at least 6V to 23V depending on your track voltage.
|
||||
|
||||
If you don't measure the correct voltages, try to `measure your track voltage <https://dccwiki.com/Measuring_Track_Voltage>`_
|
||||
|
||||
Check your motor:
|
||||
-----------------
|
||||
|
||||
Desolder your motor and try the motor with an appropriate power supply and DC voltage, to check if the motor is working or not.
|
||||
|
||||
CV Reset:
|
||||
------------
|
||||
|
||||
Try to reset the decoder by writing a value of ``8`` to ``CV8`` (beware, this will reset the complete CV memory!)
|
||||
@@ -0,0 +1,22 @@
|
||||
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
|
||||
|
||||
@@ -0,0 +1,9 @@
|
||||
Software
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:caption: Contents:
|
||||
|
||||
sw_description
|
||||
header_files
|
||||
@@ -0,0 +1,190 @@
|
||||
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-Rev-X_Y.h**
|
||||
|
||||
- Flash Size
|
||||
- Pin definitions
|
||||
|
||||
- LED pin when available
|
||||
- UART_TX/UART_RX pins when used for logging
|
||||
- DCC input pin
|
||||
- Motor Control PWM pins
|
||||
- ADC pins
|
||||
|
||||
- **post_build.cmake**
|
||||
|
||||
- Post build script for checking whether the size of the binary is within the limits of the flash size minus one sector (used for storing CVs).
|
||||
|
||||
- **pico_sdk_import.cmake**
|
||||
|
||||
- Helps to locate and import the Pico SDK
|
||||
|
||||
The `Raspberry Pi Pico SDK <https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf>`_ is a dependency of the decoder software. The SDK provides abstraction to a higher level, so hopefully, in combination with the comments included in header and source files, the code is easy enough to understand.
|
||||
|
||||
Control Loop & Digital Controller
|
||||
------------------------------------
|
||||
|
||||
.. figure:: ../../../svg/sw/Block_Diagram_Control_Loop.svg
|
||||
:alt: Block Diagram - Control Loop
|
||||
:align: center
|
||||
|
||||
Control Loop - Block diagram
|
||||
|
||||
The block diagram above shows the (simplified) control loop. The actual digital controller block is explained below.
|
||||
|
||||
The *Speed Helper* block effectively sets the setpoint of the controller according to the CV configured acceleration and deceleration rates and actual target speedstep.
|
||||
|
||||
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.
|
||||
|
||||
.. figure:: ../../../svg/sw/Block_Diagram_Digital_Controller.svg
|
||||
:alt: Block Diagram - Digital Controller
|
||||
:align: center
|
||||
|
||||
Digital Controller - Block diagram
|
||||
|
||||
The controller is divided into two parts, depending on whether the motor is stationary or in motion.
|
||||
At all times either the startup controller or the PID controller is active.
|
||||
|
||||
The startup controller handles overcoming friction of the motor, and finding a base PWM level for overcoming friction.
|
||||
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 :ref:`feed forward <feed_forward>` 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.
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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 <https://en.wikipedia.org/wiki/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}
|
||||
|
||||
|
||||
.. note::
|
||||
- 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.
|
||||
- The previously explained base PWM is added to the actual output as well, meaning the formula above only shows the actual PID control part without feed forward.
|
||||
|
||||
|
||||
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 <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).
|
||||
|
||||
|
||||
.. _feed_forward:
|
||||
|
||||
Feed-forward
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
As previously mentioned, to achieve better control, `Feed-forward <https://en.wikipedia.org/wiki/Feed_forward_(control)>`_ is used.
|
||||
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.
|
||||
|
||||
|
||||
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%.
|
||||
|
||||
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 <https://www.nmra.org/index-nmra-standards-and-recommended-practices>`_.
|
||||
Reference in new issue
Block a user