This commit is contained in:
gab-k committed 2025-01-04 13:36:00 +00:00
1 parent 9cc2596f5f
commit 42624d163b
42 files changed
+1019 -269

No files matched your search

+126
View File
@@ -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``.
@@ -1,69 +0,0 @@
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 <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 and ignore the rest of this section.
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.
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: 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:
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 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 <https://datasheets.raspberrypi.com/pico/pico-datasheet.pdf#_programming_the_flash>`_
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:`3. <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>`_.
Most relevant 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.
+3 -2
View File
@@ -5,5 +5,6 @@ Other
:maxdepth: 2
:caption: Contents:
CV_list
troubleshooting
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!)