This commit is contained in:
gab-k committed 2024-11-27 22:13:44 +00:00
1 parent e14c77e919
commit 46ffb95c57
93 files changed
+9513

No files matched your search

Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
@@ -0,0 +1,8 @@
Hardware
=================
.. toctree::
:maxdepth: 2
:caption: Contents:
hw_description
@@ -0,0 +1,133 @@
Hardware Description
====================
Overview
--------
.. image:: https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Block_Diagram.svg
:alt: 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
Characteristics
---------------
.. table:: Characteristics table
:widths: auto
===================================================== ============================= ========= ========= =====
Parameter Symbol Minimum Maximum Unit
===================================================== ============================= ========= ========= =====
Absolute max. DCC Input Voltage V\ :sub:`DCC`\ -25 +25 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://datasheet.lcsc.com/lcsc/2101211904_Bardeen-Micro--BDR6133_C2687793.pdf>`_
(2): According to: `T2N7002BK Datasheet <https://datasheet.lcsc.com/lcsc/1810271831_TOSHIBA-T2N7002BK-LM_C146372.pdf>`_
Input Stage
-----------
.. image:: https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Input_Stage.svg
:alt: 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</sub> > V<sub>GS,th</sub>), GPIO21 gets pulled to GND potential. R1 and R2 ensure that V<sub>GS</sub> doesn't exceed ±20V.
Motor Driver
------------
.. image:: https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Motor_Driver.svg
:alt: Motor Driver
The Motor Driver is a complete H-Bridge IC specifically made for DC-Motors.
In order to control the motor, it is necessary to measure the back-EMF. This is done by the ADC, which measures at Points ADC_EMF_A and ADC_EMF_B respectively. The two resistors are used as a voltage divider.
Auxiliary Output
----------------
.. image:: https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Aux_Outputs.svg
:alt: Auxiliary Output
Switching of loads up to a maximum of about ~400mA can be done using four N-Channel MOSFETs. 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 soldering pads on the back side of the PCB are connected to GPIO0 - GPIO5 pins. Although not implemented yet, they could theoretically be used as inputs as well (e.g., Reed switch).
Microcontroller
---------------
.. image:: https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Microcontroller.svg
:alt: Microcontroller
The Microcontroller needs a crystal oscillator to function properly. External flash memory is also needed as it holds the configuration variables and the program itself. R3 & C14 are used to filter ADC_AVDD (ADC Reference Voltage).
Complete Schematic
------------------
.. image:: https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/RP2040-Decoder.svg
:alt: Complete Schematic
BOM & Alternative Parts
------------------------
.. table:: BOM
:widths: auto
===================================================== ============================= ==================================== ============================= ===================== =========================
Ref Quantity Value Component Type Component Name Footprint
===================================================== ============================= ==================================== ============================= ===================== =========================
C1, C2, C5, C6, C14 5 10u Ceramic Capacitor / 0603_1608Metric
C3, C4, C7, C8, C9, C10, C11, C12, C13, C15 10 100n Ceramic Capacitor / 0603_1608Metric
C16, C17 2 33p Ceramic Capacitor / 0603_1608Metric
D1 1 V\ :sub:`RMS`\=40V, I\ :sub:`F`\=2A Bridge Rectifier KMB24F MBS (TO-269AA)
Q1, Q2, Q3, Q4, Q5 5 V\ :sub:`DS`\=60V, I\ :sub:`D`\=0.4A N-Channel MOSFET T2N7002BK SOT-23
R1, R2, R5, R6 4 6k8 Resistor / 0603_1608Metric
R3 1 200 Resistor / 0603_1608Metric
R7, R8, R9 3 1k Resistor / 0603_1608Metric
U1 1 V\ :sub:`OUT`\=3.3V Low Dropout Voltage Regulator HT7533S SOT-23
U2 1 I=2.8A H-Bridge Driver BDR6133 SOIC-8
U3 1 64Mb Flash Memory W25Q64JVSSIQ SOIC-8
U4 1 / Microcontroller RP2040 QFN-56-1EP_7x7mm_P0.4mm
Y1 1 f=12MHz Crystal Oscillator X322512MSB4SI Crystal_SMD_3225-4Pin_3.2x2.5mm
===================================================== ============================= ==================================== ============================= ===================== =========================
NOTE: Keep capacitor V\ :sub:`max`\ in mind!
Alternatives for BDR6133:
--------------------------
* `PT5126A-S-TP <https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT5126A-S-TP_C162093.html>`_
* `PT2476 <https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT2476_C481903.html>`_
Alternative for HT7533S:
------------------------
* `GS7533-33TR3 <https://www.lcsc.com/product-detail/Linear-Voltage-Regulators-LDO_Gainsil-GS7533-33TR3_C7427372.html>`_
@@ -0,0 +1,108 @@
# Hardware Description
## Overview
![Block Diagram](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Block_Diagram.svg)
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
- Auxillary output
* Microcontroller
- Flash memory
- Crystal oscillator
## Characteristics
| Parameter | Symbol | Minimum | Maximum | Unit |
| ----------------------------------------------------- | -------------- | ------- | -------- | ---- |
| Absolute max. DCC Input Voltage | V<sub>DCC</sub> | -25 | +25 | V |
| Absolute max. GPIO Voltage<sup>(0)</sup> | V<sub>PIN</sub> | -0.5 | 3.3+0.5 | V |
| Input Voltage High<sup>(0)</sup> | V<sub>IH</sub> | 2.145 | 3.6 | V |
| Input Voltage Low<sup>(0)</sup> | V<sub>IL</sub> | 0 | 1.155 | V |
| Total GPIO Current<sup>(0)</sup> | I<sub>IOVDD_MAX</sub>| | 50 | mA |
| Absolute max. motor output current<sup>(1)</sup> | I<sub>MOTOR</sub> | | 2.8 | A |
| Absolute max. auxillary output current<sup>(2)</sup> | I<sub>AUX</sub> | | 400 | mA |
(0): According to: [RP2040 Datasheet](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf) (assuming V<sub>DD</sub> = 3.3V)
(1): According to: [BDR6133 Datasheet](https://datasheet.lcsc.com/lcsc/2101211904_Bardeen-Micro--BDR6133_C2687793.pdf)
(2): According to: [T2N7002BK Datasheet](https://datasheet.lcsc.com/lcsc/1810271831_TOSHIBA-T2N7002BK-LM_C146372.pdf)
## Input Stage
![Input Stage](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Input_Stage.svg)
D1 Rectifies the DCC square-wave into +V, the amplitude is not critical as long as its 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</sub> > V<sub>GS,th</sub>), GPIO21 gets pulled to GND potential. R1 and R2 ensure that V<sub>GS</sub> doesnt exceed ±20V.
## Motor Driver
![Motor Driver](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Motor_Driver.svg)
The Motor Driver is a complete H-Bridge IC specifically made for DC-Motors.
In order to control the motor, it is necessary to measure the back-EMF. This is done by the ADC which measures at Points ADC_EMF_A and ADC_EMF_B respectively. The two resistors are used as a voltage divider.
## Auxillary Output
![Auxillary Output](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Aux_Outputs.svg)
Switching of loads up to a maximum of about ~400mA can be done using four N-Channel MOSFETS. 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 soldering pads on the back side of the PCB are connected to GPIO0 - GPIO5 pins . Although not implemented yet they could theoretically be used as inputs as well (e.g. Reed switch).
## Microcontroller
![Microcontroller](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Microcontroller.svg)
The Microcontroller needs a crystal oscillator to function properly. External flash memory is also needed as it holds the configuration variables and the program itself. R3 & C14 are used to filter ADC_AVDD (ADC Reference Voltage).
## Complete Schematic
![Complete schematic](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/RP2040-Decoder.svg)
BOM & Alternative Parts
--------------------------
| Ref | Quantity | Value | Component Type | Component Name | Footprint |
| ----------------------------------------------------- | -------------- | ------- | -------- | ---- |---- |
| C1, C2, C5, C6, C14 | 5 | 10u | Ceramic Capacitor | / | 0603_1608Metric |
| C3, C4, C7, C8, C9, C10, C11, C12, C13, C15 | 10 | 100n | Ceramic Capacitor | / | 0603_1608Metric |
| C16, C17 | 2 | 33p | Ceramic Capacitor | / | 0603_1608Metric |
| D1 | 1 | V<sub>RMS</sub> = 40V , I<sub>F</sub> = 2A | Bridge Rectifier | KMB24F | MBS (TO-269AA) |
| Q1, Q2, Q3, Q4, Q5 | 5 | V<sub>DS</sub> = 60V , I<sub>D</sub> = 0.4A | N-Channel MOSFET |T2N7002BK | SOT-23 |
| R1, R2, R5, R6 | 4 | 6k8 | Resistor | / | 0603_1608Metric |
| R3 | 1 | 200 | Resistor | / | 0603_1608Metric |
| R7, R8, R9 | 3 | 1k | Resistor | / | 0603_1608Metric |
| U1 | 1 | V<sub>OUT</sub> = 3.3V | Low Dropout Voltage Regulator | HT7533S | SOT-23 |
| U2 | 1 | I = 2.8A | H-Bridge driver | BDR6133 | SOIC-8 |
| U3 | 1 | 64Mb | Serial Flash Memory | W25Q64JVSSIQ | SOIC-8 |
| U4 | 1 | / | Raspberry Pi RP2040 Microcontroller | RP2040 | QFN-56-1EP_7x7mm_P0.4mm |
| Y1 | 1 | f = 12MHz | Crystal Oscillator | X322512MSB4SI | Crystal_SMD_3225-4Pin_3.2x2.5mm |
NOTE: Keep capacitor V<sub>max</sub> in mind!
Alternatives for BDR6133:
[PT5126A-S-TP](https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT5126A-S-TP_C162093.html)
[PT2476](https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT2476_C481903.html)
Alternative for HT7533S:
[GS7533-33TR3](https://www.lcsc.com/product-detail/Linear-Voltage-Regulators-LDO_Gainsil-GS7533-33TR3_C7427372.html)
@@ -0,0 +1,17 @@
.. 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: 2
:caption: Contents:
other/getting_started
hardware/hw
software/sw
other/CV_list
other/troubleshooting
@@ -0,0 +1,202 @@
# 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. Alternatively to reset all CVs to default a value of 8 can be written to CV8. Also note that index 0 in the CV array corresponds with CV_1, index 1 corresponds with CV_2 and so forth. This list only contains CVs that are in use.
## Speed step configuration
![Speed Table](https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/speed_table.svg)
* V_min = CV_2
* V_mid = CV_6 * 16
* V_max = CV_5 * 16
The illustration above shows how the speed steps can be configured using the corresponding CVs. The red * represents V_min which is always at speed step 1, the green * shows V_mid at speed step 64 and the blue * shows V_max at speed step 126.
## CV List
### CV_1 - Basic address
Short DCC address
### CV_2 - V_min
Min motor voltage/speed
### CV_3 - Acceleration rate
CV_3*CV_175 = Time for one discrete speed step change in ms
### CV_4 - Deceleration rate
CV_4*CV_175 = Time for one discrete speed step change in ms
### CV_5 - V_max
Max motor voltage/speed - V_max = CV_5 * 16
### CV_6 - V_mid
Mid motor voltage/speed - V_max = CV_6 * 16
### CV_7 - Version No. (Read-Only)
Rev 0.3 = 1
Writing a value of 7 triggers am ADC offset adjustment.
### CV_8 - Manufacturer (Read-Only)
Default = "13" = Public Domain & Do-It-Yourself Decoders
Writing a value of 8 resets all CV values to the default values in CV.h.
This will also happen if CV_65 == "255" == "0xFF".
### CV_9 - Motor PWM Frequency
f in Hz = CV_9 * 100 + 10000
### CV_11 - Packet timeout
If no package is received for x seconds (x = CV_11) the decoder will automatically stop the motor (Emergency Stop).
### CV_12 - Permitted operating modes
Currently DCC Digital mode is the only supported mode.
### CV_17 & CV_18 - 14-Bit extended/long address
Address is only used if bit5 has a value of "1" in CV_29.
![Long Address](https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Long_address.svg)
Bit15 and bit14 which correspond to bit7 and bit6 of CV_17 are always "1". CV_17 = "192" & CV_18 = "0" is also not a valid address. Otherwise the valid value range of CV_17 ranges from "192" to "231" and "0" to "255" for CV_18 respectively.
### CV_29 - Decoder Configuration
Bit0 is used to reverse 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.
### CV_31 & CV_32 - Extended CV pointer (Read-Only)
Not in use.
### CV_47 - Feed-forward gain k_ff
k_ff defines the correction behavior with regard to the y2 variable. High values for k_ff lead to a faster change in the variable. Values for k_ff that are too high can lead to oscillations.
k_ff = CV_47/10000
### CV_48 - Filter time constant (tau) in ms
The time constant tau characterizes the low-pass filter which is connected downstream in the D component of the PID controller
### CV_49 - PID Control sampling time t in ms
Every t seconds the pid_control() function gets called to compute the new control output
### CV_50 - PID Control I Factor
Integral gain factor of the PID-Controller
### CV_51 - PID Control D Factor
Derivative gain factor of the PID-Controller
### CV_52 & CV_53 - PID Integral Limits
Maximum and minimum integral part values
### CV_54 & CV_55 - Gain scheduling config k_p @ x0
CV_54 - High Byte -- CV_55 - Low Byte
### CV_56 & CV_57 - Gain scheduling config k_p @ x1
CV_56 - High Byte -- CV_57 - Low Byte
### CV_58 & CV_59 - Gain scheduling config k_p @ x2
CV_58 - High Byte -- CV_59 - Low Byte
### CV_60 - Gain scheduling config x1 shift percentage
Determines position of x1 in percent -> x1 shift in % ≙ CV_60/255
### CV_61 - Measurement Iterations
Total amount of BEMF-Voltage measurement iterations
### CV_62 - Measurement Delay
BEMF-Voltage measurement delay
### CV_63 & CV_64 - Measurement array cutoffs
CV_63 determines how many elements from the left side (beginning with index 0) of the array will be discarded while CV_64 determines how many elements from the right side (beginning from highest index) will be discarded.
### CV_65 - New flash variable
Each Byte of the factory new flash chip should have a inital state of "0xFF". This will be checked for in the beginning of core0.c (see cv_setup_check()). When CV_65 == "255" == "0xFF" the default config (CV.h) will be written to flash. Alternatively a reset to default can be done by either writing "8" to CV_8 or writing "255" to CV_65 which then triggers a reset on startup.
### CV_112, CV_113, CV_114, CV_115 - GPIO PWM Configuration
PWM enabled "1" - PWM disabled "0"
### CV_116 to CV_171 - PWM Slice configuration
![GPIO Slices](https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/GPIO_slices.svg)
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: f<sub>PWM</sub> = 125 MHz / [ (CV<sub>clk_div</sub> + 1) * (CV<sub>wrap</sub> + 1) ]
The duty-cycle can be calculated as follows: D = CV<sub>Level</sub> / CV<sub>wrap</sub> + 1
**Example configuration - (AUX2: PWM-Frequency f<sub>PWM</sub> = 10kHz; Duty-cycle D = 20%):**
AUX1 => GPIO25 => Slice 4 / Channel B => Wrap: CV_144 & CV_145; Clock-divider: CV_146; Level(B): CV_149 & CV_150
=> f<sub>PWM</sub> = 10kHz = 125 MHz / [ (0 + 1) * (12499 + 1) ];
=> CV_144 = 110000, CV_145 = 11010011, CV_146 = 0; --- (Note: "12499<sub>dec</sub>" = "11000011010011<sub>bin</sub>")
=> CV<sub>Level</sub> = CV_149 & CV_150 = D * (CV<sub>wrap</sub> + 1) = 0.2 * 12500 = 2500
=> CV_149 = 1001, CV_150 = 11000100; --- (Note: "2500<sub>dec</sub>" = "100111000100<sub>bin</sub>")
Another configuration which also achieves 10kHz and D = 20% would be CV<sub>clk_div</sub> = 10, CV<sub>wrap</sub> = 1249, CV<sub>Level</sub> = 250.
A more detailed explanation regarding PWM can be found in the [RP2040-Datasheet - Chapter 4.5](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf).
### CV_172 - ADC Offset
If CV_172 = "0xFF" = "255" there will be a measurement procedure on startup
### CV_173 - ADC offset measurement cycles
Determines how many ADC offset measurement iterations are done.
### CV_174 - Additional motor-PWM clock divider.
Additional Clock Divider - works the same as any GPIO clock divider
### CV_175 - speed_helper timer delay
This timer delay can be used to change the time between two speed steps. So basically an additional option to adjust the deceleration and acceleration rate.
### CV_176, CV_177, CV_178, CV_179 - Base PWM Level used in feed-forward control
CV_176 - High Byte forward -- CV_177 - Low Byte forward -- CV_178 - High Byte reverse -- CV_179 - Low Byte reverse
These values are equivalent to y1(forward) and y1(reverse) mentioned [here](https://github.com/gab-k/RP2040-Decoder/wiki/Software-description#feed-forward). Writing "0" to all four CVs schedules a new calibration on startup.
### CV_257 to CV_512 - Function Mapping CVs
The switching status of the outputs depends both on the function instruction received and on the current direction of travel. That means you can, for example, use a function to switch two or more outputs or, as is usual with headlights, switch them depending on the direction of travel. For configuration, 32 bits (corresponding to the GPIOs) are available for each function in each direction of travel.
@@ -0,0 +1,75 @@
# Getting started
In order to make use of this project, you will need the following:
- The RP2040-Decoder board itself
- Raspberry Pi Pico or another multi-drop SWD debug interfaces might work as well
- Micro-USB cable
## 1. Where to get the board?
You can of course choose any preferred PCB manufacturer, the PCB is designed to be compliant with JLCPCB.com 2 layer board capabilities (hole diameter/clearence/etc.). Regarding assembly, you can of course assemble the board yourself but I would not recommend it (especially the RP2040 QFN Package is not easy to solder). Alternatively you can order the board fully or partly assembled. All parts are normally available at LCSC.com who supply parts to JLCPCB.com.
## 2. Production files?
In order to generate export the production files (Gerber/BOM/Pick and Place) you need [KiCad](https://www.kicad.org/download/) 6 which is open source.
[How to do this?](https://jlcpcb.com/help/article/362-how-to-generate-gerber-and-drill-files-in-kicad-7)
## 3. Building and flashing
To build the software and run it on the Controller we need to interface the RP2040 using Serial Wire Debug. This can be done using a Raspberry Pi Pico board.
### Windows
1. Connect Raspberry Pi Pico via USB while holding the reset button. Your Pi Pico should now be visible in Windows explorer as a mass storage device.
2. Download the latest prebuilt "picoprobe.uf2" release binary from [here](https://github.com/raspberrypi/picoprobe/releases) or download it from the [Raspberry Pi Website](https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#debugging-using-another-raspberry-pi-pico).
3. Copy "picoprobe.uf2" to your Pi Pico. The Pi Pico onboard LED should now light up.
4. Connect GND to GND, GPIO2 to SWCLK, GPIO3 to SWDIO, VBUS to +V, as shown in the picture below .
<img src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Debug_Connections.svg" width="700"/>
5. Download and install [Pico setup for Windows](https://github.com/raspberrypi/pico-setup-windows)
6. Download and install [MSYS2](https://www.msys2.org/)
7. Open a MSYS2 MINGW64 shell window
8. Update all pacman packages
```sh
pacman -Syu
```
9. Install mingw-w64-x86_64-toolchain (choose to install all)
```sh
pacman -S mingw-w64-x86_64-toolchain
```
10. Add "C:\msys64\mingw64\bin" to your users PATH environment variable. If you have choosen to not use the default directory for MSYS2 add the one you have choosen. [How to do this?](https://www.computerhope.com/issues/ch000549.htm)
11. Open the Pico - Developer Powershell
12. Navigate to a folder you like and clone the project repository
```sh
git clone https://github.com/gab-k/RP2040-Decoder
```
13. Enter cloned repository, create and enter build directory
```sh
cd RP2040-Decoder
mkdir build
cd build
```
14. Run CMake and the mingw32-make to build
```sh
cmake -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Debug ..
mingw32
```
15. Flash the decoders software using openocd
```sh
openocd -f interface/cmsis-dap.cfg -f target/rp2040.cfg -c "adapter speed 5000" -c"program rp2040-decoder.elf verify reset exit"
```
### Other OS
The first four steps are identical to the steps described above for windows users. Regarding building and flashing, please refer to [Getting started - Pico](https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf). Chapter 3 & 5 and Appendix A are the most relevant but you might also refer to chapter 9.1 if you are using macOS.
## 4. Wiring and initial startup
<img src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Wiring_diagram.svg" width="700"/>
The illustration above shows an example wiring configuration, you can connect up to 4 outputs(up to 400mA) and 6 GPIOs for lighter loads or custom applications. A Free-wheeling diode should be used when switching inductive loads!
Another important note is that when the decoder is put into operation for the first time, it automatically performs a motor calibration, which is required for feedforward control. The calibration takes about one to two minutes.
## 5. If it's 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,14 @@
# Troubleshooting
To narrow down the issue when your decoder is not working as expected, you can do the following:
Check the power supply of the decoder:
* +3V3 to GND should be 3.3V
* +V to GND should be somewhere in the range of around +10V to +20V
* If you dont measure the correct voltages, try to [measure Track Voltage](https://dccwiki.com/Measuring_Track_Voltage)
Check your motor:
* Desolder your motor and try the motor with a analog power supply 0...+-16V to check if the motor is working or not (desolder the wires because the decoder doesn't like voltage on these pins!)
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,29 @@
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
@@ -0,0 +1,9 @@
Software
=================
.. toctree::
:maxdepth: 2
:caption: Contents:
sw_description
header_files
@@ -0,0 +1,82 @@
# 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](https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Block_Diagram_Control.svg)
***
**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
![PID Controller](https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Block_Diagram_PID.svg)
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 * (K<sub>P</sub> + K<sub>I</sub>/s + (K<sub>D</sub>*s)/(sτ+1)) = P + I + D
* P = E * K<sub>P</sub>
* I = E * K<sub>I</sub>/s
* D = E * (K<sub>D</sub>*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) / T<sub>s</sub>*(z+1) ].
This results in the following difference equations which are then implemented in software:
* p<sub>n</sub> = K<sub>P</sub> * e<sub>n</sub>
* i<sub>n</sub> = 0.5K<sub>I</sub> * (e<sub>n</sub> + e<sub>n-1</sub>) + i<sub>n-1</sub>
* d<sub>n</sub> = [ 2K<sub>D</sub> * (e<sub>n</sub> - e<sub>n-1</sub>) + (2τ - T<sub>s</sub>) * d<sub>n-1</sub> ] / [ 2τ + T<sub>s</sub>]
=> output<sub>n</sub> = p<sub>n</sub> + i<sub>n</sub> + d<sub>n</sub>
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
![K_P](https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/adaptive_kp.svg)
Another aspect to consider is the implementation of [gain scheduling](https://en.wikipedia.org/wiki/Gain_scheduling). K<sub>P</sub> is a function of the current setpoint. Often it is favorable to have a higher proportional gain K<sub>P</sub> for slow speeds, achieving better control results. The illustration above shows the default setting for K<sub>P</sub>. CV_54 & CV_55 are used to set K<sub>P</sub> @ x<sub>0</sub>, CV_56 & CV_57 for K<sub>P</sub> @ x<sub>1</sub> and CV_58 & CV_59 for K<sub>P</sub> @ x<sub>2</sub>. Additionally CV_60 is used to shift x<sub>1</sub> from the leftmost point (0% = 0/255) to the rightmost point (100% = 255/255).
### Feed-forward
![Feed-forward](https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/feed_forward.svg)
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 (y<sub>1</sub>) for both directions. The base pwm level (y<sub>1</sub>) 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</sub> is corrected automatically when i<sub>n</sub> reaches 0.5i<sub>min</sub> or 0.5i<sub>max</sub>. 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)
@@ -0,0 +1,123 @@
/* Compatability shim for jQuery and underscores.js.
*
* Copyright Sphinx contributors
* Released under the two clause BSD licence
*/
/**
* small helper function to urldecode strings
*
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
*/
jQuery.urldecode = function(x) {
if (!x) {
return x
}
return decodeURIComponent(x.replace(/\+/g, ' '));
};
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
var bbox = node.parentElement.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}
+914
View File
@@ -0,0 +1,914 @@
/*
* Sphinx stylesheet -- basic theme.
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
div.section::after {
display: block;
content: '';
clear: left;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox form.search {
overflow: hidden;
}
div.sphinxsidebar #searchbox input[type="text"] {
float: left;
width: 80%;
padding: 0.25em;
box-sizing: border-box;
}
div.sphinxsidebar #searchbox input[type="submit"] {
float: left;
width: 20%;
border-left: none;
padding: 0.25em;
box-sizing: border-box;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin-top: 10px;
}
ul.search li {
padding: 5px 0;
}
ul.search li a {
font-weight: bold;
}
ul.search li p.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body {
min-width: 360px;
max-width: 800px;
}
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
a:visited {
color: #551A8B;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, figure.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, figure.align-right, .figure.align-right, object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
img.align-center, figure.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
img.align-default, figure.align-default, .figure.align-default {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-default {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar,
aside.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px;
background-color: #ffe;
width: 40%;
float: right;
clear: right;
overflow-x: auto;
}
p.sidebar-title {
font-weight: bold;
}
nav.contents,
aside.topic,
div.admonition, div.topic, blockquote {
clear: left;
}
/* -- topics ---------------------------------------------------------------- */
nav.contents,
aside.topic,
div.topic {
border: 1px solid #ccc;
padding: 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- content of sidebars/topics/admonitions -------------------------------- */
div.sidebar > :last-child,
aside.sidebar > :last-child,
nav.contents > :last-child,
aside.topic > :last-child,
div.topic > :last-child,
div.admonition > :last-child {
margin-bottom: 0;
}
div.sidebar::after,
aside.sidebar::after,
nav.contents::after,
aside.topic::after,
div.topic::after,
div.admonition::after,
blockquote::after {
display: block;
content: '';
clear: both;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
margin-top: 10px;
margin-bottom: 10px;
border: 0;
border-collapse: collapse;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
table.align-default {
margin-left: auto;
margin-right: auto;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
th > :first-child,
td > :first-child {
margin-top: 0px;
}
th > :last-child,
td > :last-child {
margin-bottom: 0px;
}
/* -- figures --------------------------------------------------------------- */
div.figure, figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption, figcaption {
padding: 0.3em;
}
div.figure p.caption span.caption-number,
figcaption span.caption-number {
font-style: italic;
}
div.figure p.caption span.caption-text,
figcaption span.caption-text {
}
/* -- field list styles ----------------------------------------------------- */
table.field-list td, table.field-list th {
border: 0 !important;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
/* -- hlist styles ---------------------------------------------------------- */
table.hlist {
margin: 1em 0;
}
table.hlist td {
vertical-align: top;
}
/* -- object description styles --------------------------------------------- */
.sig {
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
}
.sig-name, code.descname {
background-color: transparent;
font-weight: bold;
}
.sig-name {
font-size: 1.1em;
}
code.descname {
font-size: 1.2em;
}
.sig-prename, code.descclassname {
background-color: transparent;
}
.optional {
font-size: 1.3em;
}
.sig-paren {
font-size: larger;
}
.sig-param.n {
font-style: italic;
}
/* C++ specific styling */
.sig-inline.c-texpr,
.sig-inline.cpp-texpr {
font-family: unset;
}
.sig.c .k, .sig.c .kt,
.sig.cpp .k, .sig.cpp .kt {
color: #0033B3;
}
.sig.c .m,
.sig.cpp .m {
color: #1750EB;
}
.sig.c .s, .sig.c .sc,
.sig.cpp .s, .sig.cpp .sc {
color: #067D17;
}
/* -- other body styles ----------------------------------------------------- */
ol.arabic {
list-style: decimal;
}
ol.loweralpha {
list-style: lower-alpha;
}
ol.upperalpha {
list-style: upper-alpha;
}
ol.lowerroman {
list-style: lower-roman;
}
ol.upperroman {
list-style: upper-roman;
}
:not(li) > ol > li:first-child > :first-child,
:not(li) > ul > li:first-child > :first-child {
margin-top: 0px;
}
:not(li) > ol > li:last-child > :last-child,
:not(li) > ul > li:last-child > :last-child {
margin-bottom: 0px;
}
ol.simple ol p,
ol.simple ul p,
ul.simple ol p,
ul.simple ul p {
margin-top: 0;
}
ol.simple > li:not(:first-child) > p,
ul.simple > li:not(:first-child) > p {
margin-top: 0;
}
ol.simple p,
ul.simple p {
margin-bottom: 0;
}
aside.footnote > span,
div.citation > span {
float: left;
}
aside.footnote > span:last-of-type,
div.citation > span:last-of-type {
padding-right: 0.5em;
}
aside.footnote > p {
margin-left: 2em;
}
div.citation > p {
margin-left: 4em;
}
aside.footnote > p:last-of-type,
div.citation > p:last-of-type {
margin-bottom: 0em;
}
aside.footnote > p:last-of-type:after,
div.citation > p:last-of-type:after {
content: "";
clear: both;
}
dl.field-list {
display: grid;
grid-template-columns: fit-content(30%) auto;
}
dl.field-list > dt {
font-weight: bold;
word-break: break-word;
padding-left: 0.5em;
padding-right: 5px;
}
dl.field-list > dd {
padding-left: 0.5em;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0em;
}
dl {
margin-bottom: 15px;
}
dd > :first-child {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
.sig dd {
margin-top: 0px;
margin-bottom: 0px;
}
.sig dl {
margin-top: 0px;
margin-bottom: 0px;
}
dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
}
dt:target, span.highlighted {
background-color: #fbe54e;
}
rect.highlighted {
fill: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
.guilabel, .menuselection {
font-family: sans-serif;
}
.accelerator {
text-decoration: underline;
}
.classifier {
font-style: oblique;
}
.classifier:before {
font-style: normal;
margin: 0 0.5em;
content: ":";
display: inline-block;
}
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
.translated {
background-color: rgba(207, 255, 207, 0.2)
}
.untranslated {
background-color: rgba(255, 207, 207, 0.2)
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
pre, div[class*="highlight-"] {
clear: both;
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
-webkit-hyphens: none;
hyphens: none;
white-space: nowrap;
}
div[class*="highlight-"] {
margin: 1em 0;
}
td.linenos pre {
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
display: block;
}
table.highlighttable tbody {
display: block;
}
table.highlighttable tr {
display: flex;
}
table.highlighttable td {
margin: 0;
padding: 0;
}
table.highlighttable td.linenos {
padding-right: 0.5em;
}
table.highlighttable td.code {
flex: 1;
overflow: hidden;
}
.highlight .hll {
display: block;
}
div.highlight pre,
table.highlighttable pre {
margin: 0;
}
div.code-block-caption + div {
margin-top: 0;
}
div.code-block-caption {
margin-top: 1em;
padding: 2px 5px;
font-size: small;
}
div.code-block-caption code {
background-color: transparent;
}
table.highlighttable td.linenos,
span.linenos,
div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none;
-webkit-user-select: text; /* Safari fallback only */
-webkit-user-select: none; /* Chrome/Safari */
-moz-user-select: none; /* Firefox */
-ms-user-select: none; /* IE10+ */
}
div.code-block-caption span.caption-number {
padding: 0.1em 0.3em;
font-style: italic;
}
div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
margin: 1em 0;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.viewcode-link {
float: right;
}
.viewcode-back {
float: right;
font-family: sans-serif;
}
div.viewcode-block:target {
margin: -1px -10px;
padding: 0 10px;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
span.eqno a.headerlink {
position: absolute;
z-index: 1;
}
div.math:hover a.headerlink {
visibility: visible;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}
@@ -0,0 +1 @@
.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions .rst-other-versions .rtd-current-item{font-weight:700}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}#flyout-search-form{padding:6px}
File diff suppressed because it is too large. Load diff

After

Width:  |  Height:  |  Size: 434 KiB

@@ -0,0 +1,4 @@
html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .eqno .headerlink:before,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content p .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a button.toctree-expand:before,.wy-menu-vertical li.on a button.toctree-expand:before,.wy-menu-vertical li button.toctree-expand:before,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*!
* Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
* License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
*/@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content .eqno .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content p .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a button.toctree-expand,.wy-menu-vertical li.on a button.toctree-expand,.wy-menu-vertical li button.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .eqno .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a button.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-left.toctree-expand,.wy-menu-vertical li button.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .eqno .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a button.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a button.fa-pull-right.toctree-expand,.wy-menu-vertical li button.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .eqno .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a button.pull-left.toctree-expand,.wy-menu-vertical li.on a button.pull-left.toctree-expand,.wy-menu-vertical li button.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .eqno .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-coLine truncated
+149
View File
@@ -0,0 +1,149 @@
/*
* Base JavaScript utilities for all Sphinx HTML documentation.
*/
"use strict";
const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
"TEXTAREA",
"INPUT",
"SELECT",
"BUTTON",
]);
const _ready = (callback) => {
if (document.readyState !== "loading") {
callback();
} else {
document.addEventListener("DOMContentLoaded", callback);
}
};
/**
* Small JavaScript module for the documentation.
*/
const Documentation = {
init: () => {
Documentation.initDomainIndexTable();
Documentation.initOnKeyListeners();
},
/**
* i18n support
*/
TRANSLATIONS: {},
PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
LOCALE: "unknown",
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
gettext: (string) => {
const translated = Documentation.TRANSLATIONS[string];
switch (typeof translated) {
case "undefined":
return string; // no translation
case "string":
return translated; // translation exists
default:
return translated[0]; // (singular, plural) translation tuple exists
}
},
ngettext: (singular, plural, n) => {
const translated = Documentation.TRANSLATIONS[singular];
if (typeof translated !== "undefined")
return translated[Documentation.PLURAL_EXPR(n)];
return n === 1 ? singular : plural;
},
addTranslations: (catalog) => {
Object.assign(Documentation.TRANSLATIONS, catalog.messages);
Documentation.PLURAL_EXPR = new Function(
"n",
`return (${catalog.plural_expr})`
);
Documentation.LOCALE = catalog.locale;
},
/**
* helper function to focus on search bar
*/
focusSearchBar: () => {
document.querySelectorAll("input[name=q]")[0]?.focus();
},
/**
* Initialise the domain index toggle buttons
*/
initDomainIndexTable: () => {
const toggler = (el) => {
const idNumber = el.id.substr(7);
const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
if (el.src.substr(-9) === "minus.png") {
el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
toggledRows.forEach((el) => (el.style.display = "none"));
} else {
el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
toggledRows.forEach((el) => (el.style.display = ""));
}
};
const togglerElements = document.querySelectorAll("img.toggler");
togglerElements.forEach((el) =>
el.addEventListener("click", (event) => toggler(event.currentTarget))
);
togglerElements.forEach((el) => (el.style.display = ""));
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
},
initOnKeyListeners: () => {
// only install a listener if it is really needed
if (
!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
)
return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.altKey || event.ctrlKey || event.metaKey) return;
if (!event.shiftKey) {
switch (event.key) {
case "ArrowLeft":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const prevLink = document.querySelector('link[rel="prev"]');
if (prevLink && prevLink.href) {
window.location.href = prevLink.href;
event.preventDefault();
}
break;
case "ArrowRight":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const nextLink = document.querySelector('link[rel="next"]');
if (nextLink && nextLink.href) {
window.location.href = nextLink.href;
event.preventDefault();
}
break;
}
}
// some keyboard layouts may need Shift to get /
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
event.preventDefault();
}
});
},
};
// quick alias for translations
const _ = Documentation.gettext;
_ready(Documentation.init);
@@ -0,0 +1,13 @@
const DOCUMENTATION_OPTIONS = {
VERSION: '0.3, 1.0',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
NAVIGATION_WITH_KEYS: false,
SHOW_SEARCH_SUMMARY: true,
ENABLE_SEARCH_SHORTCUTS: true,
};
Binary file not shown.

After

Width:  |  Height:  |  Size: 286 B

+2
View File
@@ -0,0 +1,2 @@
/*! jQuery v3.6.0 | (c) OpenJS Foundation and other contributors | jquery.org/license */
!function(e,t){"use strict";"object"==typeof module&&"object"==typeof module.exports?module.exports=e.document?t(e,!0):function(e){if(!e.document)throw new Error("jQuery requires a window with a document");return t(e)}:t(e)}("undefined"!=typeof window?window:this,function(C,e){"use strict";var t=[],r=Object.getPrototypeOf,s=t.slice,g=t.flat?function(e){return t.flat.call(e)}:function(e){return t.concat.apply([],e)},u=t.push,i=t.indexOf,n={},o=n.toString,v=n.hasOwnProperty,a=v.toString,l=a.call(Object),y={},m=function(e){return"function"==typeof e&&"number"!=typeof e.nodeType&&"function"!=typeof e.item},x=function(e){return null!=e&&e===e.window},E=C.document,c={type:!0,src:!0,nonce:!0,noModule:!0};function b(e,t,n){var r,i,o=(n=n||E).createElement("script");if(o.text=e,t)for(r in c)(i=t[r]||t.getAttribute&&t.getAttribute(r))&&o.setAttribute(r,i);n.head.appendChild(o).parentNode.removeChild(o)}function w(e){return null==e?e+"":"object"==typeof e||"function"==typeof e?n[o.call(e)]||"object":typeof e}var f="3.6.0",S=function(e,t){return new S.fn.init(e,t)};function p(e){var t=!!e&&"length"in e&&e.length,n=w(e);return!m(e)&&!x(e)&&("array"===n||0===t||"number"==typeof t&&0<t&&t-1 in e)}S.fn=S.prototype={jquery:f,constructor:S,length:0,toArray:function(){return s.call(this)},get:function(e){return null==e?s.call(this):e<0?this[e+this.length]:this[e]},pushStack:function(e){var t=S.merge(this.constructor(),e);return t.prevObject=this,t},each:function(e){return S.each(this,e)},map:function(n){return this.pushStack(S.map(this,function(e,t){return n.call(e,t,e)}))},slice:function(){return this.pushStack(s.apply(this,arguments))},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},even:function(){return this.pushStack(S.grep(this,function(e,t){return(t+1)%2}))},odd:function(){return this.pushStack(S.grep(this,function(e,t){return t%2}))},eq:function(e){var t=this.length,n=+e+(e<0?t:0);return this.pushStack(0<=n&&n<t?[this[n]]:[])},end:function(){return this.prevObject||this.constructor()},push:u,sort:t.sort,splice:t.splice},S.extend=S.fn.extend=function(){var e,t,n,r,i,o,a=arguments[0]||{},s=1,u=arguments.length,l=!1;for("boolean"==typeof a&&(l=a,a=arguments[s]||{},s++),"object"==typeof a||m(a)||(a={}),s===u&&(a=this,s--);s<u;s++)if(null!=(e=arguments[s]))for(t in e)r=e[t],"__proto__"!==t&&a!==r&&(l&&r&&(S.isPlainObject(r)||(i=Array.isArray(r)))?(n=a[t],o=i&&!Array.isArray(n)?[]:i||S.isPlainObject(n)?n:{},i=!1,a[t]=S.extend(l,o,r)):void 0!==r&&(a[t]=r));return a},S.extend({expando:"jQuery"+(f+Math.random()).replace(/\D/g,""),isReady:!0,error:function(e){throw new Error(e)},noop:function(){},isPlainObject:function(e){var t,n;return!(!e||"[object Object]"!==o.call(e))&&(!(t=r(e))||"function"==typeof(n=v.call(t,"constructor")&&t.constructor)&&a.call(n)===l)},isEmptyObject:function(e){var t;for(t in e)return!1;return!0},globalEval:function(e,t,n){b(e,{nonce:t&&t.nonce},n)},each:function(e,t){var n,r=0;if(p(e)){for(n=e.length;r<n;r++)if(!1===t.call(e[r],r,e[r]))break}else for(r in e)if(!1===t.call(e[r],r,e[r]))break;return e},makeArray:function(e,t){var n=t||[];return null!=e&&(p(Object(e))?S.merge(n,"string"==typeof e?[e]:e):u.call(n,e)),n},inArray:function(e,t,n){return null==t?-1:i.call(t,e,n)},merge:function(e,t){for(var n=+t.length,r=0,i=e.length;r<n;r++)e[i++]=t[r];return e.length=i,e},grep:function(e,t,n){for(var r=[],i=0,o=e.length,a=!n;i<o;i++)!t(e[i],i)!==a&&r.push(e[i]);return r},map:function(e,t,n){var r,i,o=0,a=[];if(p(e))for(r=e.length;o<r;o++)null!=(i=t(e[o],o,n))&&a.push(i);else for(o in e)null!=(i=t(e[o],o,n))&&a.push(i);return g(a)},guid:1,support:y}),"function"==typeof Symbol&&(S.fn[Symbol.iterator]=t[Symbol.iterator]),S.each("Boolean Number String Function Array Date RegExp Object Error Symbol".split(" "),function(e,t){n["[object "+t+"]"]=t.toLowerCase()});var d=function(n){var e,d,b,o,i,h,f,g,w,u,l,T,C,a,E,v,s,c,y,S="sizzle"+1*new Date,p=n.document,k=0,r=0,m=ue(),x=ue(),A=ue(),N=ue(),j=function(e,t){return e===t&&(l=!0),0},D={}.hasOwnProperty,t=[],q=t.pop,L=t.push,H=t.push,O=t.slice,P=function(e,t){for(var n=0,r=e.length;n<r;n++)if(e[n]===t)return n;return-1},R="checked|selected|async|autofocus|autoplay|controls|defer|disabled|hidden|ismap|loop|multiple|open|readonly|required|scoped",M="[\\x20\\t\\r\\n\\f]",I="(?:\\\\[\\da-fA-F]{1,6}"+M+"?|\\\\[^\\r\\n\\f]|[\\w-]|[^\0-\\x7f])+",W="\\["+M+"*("+I+")(?:"+M+"*([*^$|!~]?=)"+M+"*(?:'((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\"|("+I+"))|)"+M+"*\\]",F=":("+I+")(?:\\((('((?:\\\\.|[^\\\\'])*)'|\"((?:\\\\.|[^\\\\\"])*)\")|((?:\\\\.|[^\\\\()[\\]]|"+W+")*)|.*)\\)|)",B=new RegExp(M+"+","g"),$=new RegExp("^"+M+"+|((?:^|[^\\\\])(?:\\\\.)*)"+M+"+$","g"),_=new RegExp("^"+M+"*,"+M+"*"),z=new RegExp("^"+M+"*([>+~]|"+M+")"+M+"*"),U=new RegExp(M+"|>"),X=new RegExp(F),V=new RegExp("^"+I+"$"),G={ID:new RegExp("^#("+I+")"),CLASS:new RegExp("^\\.("+I+")"),TAG:new RegExp("^("+I+"|[*])"),ATTR:new RegExp("^"+W),PSEUDO:new RegExp("^"+F),CHILD:new RegExp("^Line truncated
@@ -0,0 +1 @@
!function(e){var t={};function r(n){if(t[n])return t[n].exports;var o=t[n]={i:n,l:!1,exports:{}};return e[n].call(o.exports,o,o.exports,r),o.l=!0,o.exports}r.m=e,r.c=t,r.d=function(e,t,n){r.o(e,t)||Object.defineProperty(e,t,{enumerable:!0,get:n})},r.r=function(e){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})},r.t=function(e,t){if(1&t&&(e=r(e)),8&t)return e;if(4&t&&"object"==typeof e&&e&&e.__esModule)return e;var n=Object.create(null);if(r.r(n),Object.defineProperty(n,"default",{enumerable:!0,value:e}),2&t&&"string"!=typeof e)for(var o in e)r.d(n,o,function(t){return e[t]}.bind(null,o));return n},r.n=function(e){var t=e&&e.__esModule?function(){return e.default}:function(){return e};return r.d(t,"a",t),t},r.o=function(e,t){return Object.prototype.hasOwnProperty.call(e,t)},r.p="",r(r.s=4)}({4:function(e,t,r){}});
@@ -0,0 +1 @@
!function(n){var e={};function t(i){if(e[i])return e[i].exports;var o=e[i]={i:i,l:!1,exports:{}};return n[i].call(o.exports,o,o.exports,t),o.l=!0,o.exports}t.m=n,t.c=e,t.d=function(n,e,i){t.o(n,e)||Object.defineProperty(n,e,{enumerable:!0,get:i})},t.r=function(n){"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(n,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(n,"__esModule",{value:!0})},t.t=function(n,e){if(1&e&&(n=t(n)),8&e)return n;if(4&e&&"object"==typeof n&&n&&n.__esModule)return n;var i=Object.create(null);if(t.r(i),Object.defineProperty(i,"default",{enumerable:!0,value:n}),2&e&&"string"!=typeof n)for(var o in n)t.d(i,o,function(e){return n[e]}.bind(null,o));return i},t.n=function(n){var e=n&&n.__esModule?function(){return n.default}:function(){return n};return t.d(e,"a",e),e},t.o=function(n,e){return Object.prototype.hasOwnProperty.call(n,e)},t.p="",t(t.s=0)}([function(n,e,t){t(1),n.exports=t(3)},function(n,e,t){(function(){var e="undefined"!=typeof window?window.jQuery:t(2);n.exports.ThemeNav={navBar:null,win:null,winScroll:!1,winResize:!1,linkScroll:!1,winPosition:0,winHeight:null,docHeight:null,isRunning:!1,enable:function(n){var t=this;void 0===n&&(n=!0),t.isRunning||(t.isRunning=!0,e((function(e){t.init(e),t.reset(),t.win.on("hashchange",t.reset),n&&t.win.on("scroll",(function(){t.linkScroll||t.winScroll||(t.winScroll=!0,requestAnimationFrame((function(){t.onScroll()})))})),t.win.on("resize",(function(){t.winResize||(t.winResize=!0,requestAnimationFrame((function(){t.onResize()})))})),t.onResize()})))},enableSticky:function(){this.enable(!0)},init:function(n){n(document);var e=this;this.navBar=n("div.wy-side-scroll:first"),this.win=n(window),n(document).on("click","[data-toggle='wy-nav-top']",(function(){n("[data-toggle='wy-nav-shift']").toggleClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift")})).on("click",".wy-menu-vertical .current ul li a",(function(){var t=n(this);n("[data-toggle='wy-nav-shift']").removeClass("shift"),n("[data-toggle='rst-versions']").toggleClass("shift"),e.toggleCurrent(t),e.hashChange()})).on("click","[data-toggle='rst-current-version']",(function(){n("[data-toggle='rst-versions']").toggleClass("shift-up")})),n("table.docutils:not(.field-list,.footnote,.citation)").wrap("<div class='wy-table-responsive'></div>"),n("table.docutils.footnote").wrap("<div class='wy-table-responsive footnote'></div>"),n("table.docutils.citation").wrap("<div class='wy-table-responsive citation'></div>"),n(".wy-menu-vertical ul").not(".simple").siblings("a").each((function(){var t=n(this);expand=n('<button class="toctree-expand" title="Open/close menu"></button>'),expand.on("click",(function(n){return e.toggleCurrent(t),n.stopPropagation(),!1})),t.prepend(expand)}))},reset:function(){var n=encodeURI(window.location.hash)||"#";try{var e=$(".wy-menu-vertical"),t=e.find('[href="'+n+'"]');if(0===t.length){var i=$('.document [id="'+n.substring(1)+'"]').closest("div.section");0===(t=e.find('[href="#'+i.attr("id")+'"]')).length&&(t=e.find('[href="#"]'))}if(t.length>0){$(".wy-menu-vertical .current").removeClass("current").attr("aria-expanded","false"),t.addClass("current").attr("aria-expanded","true"),t.closest("li.toctree-l1").parent().addClass("current").attr("aria-expanded","true");for(let n=1;n<=10;n++)t.closest("li.toctree-l"+n).addClass("current").attr("aria-expanded","true");t[0].scrollIntoView()}}catch(n){console.log("Error expanding nav for anchor",n)}},onScroll:function(){this.winScroll=!1;var n=this.win.scrollTop(),e=n+this.winHeight,t=this.navBar.scrollTop()+(n-this.winPosition);n<0||e>this.docHeight||(this.navBar.scrollTop(t),this.winPosition=n)},onResize:function(){this.winResize=!1,this.winHeight=this.win.height(),this.docHeight=$(document).height()},hashChange:function(){this.linkScroll=!0,this.win.one("hashchange",(function(){this.linkScroll=!1}))},toggleCurrent:function(n){var e=n.closest("li");e.siblings("li.current").removeClass("current").attr("aria-expanded","false"),e.siblings().find("li.current").removeClass("current").attr("aria-expanded","false");var t=e.find("> ul li");t.length&&(t.removeClass("current").attr("aria-expanded","false"),e.toggleClass("current").attr("aria-expanded",(function(n,e){return"true"==e?"false":"true"})))}},"undefined"!=typeof window&&(window.SphinxRtdTheme={Navigation:n.exports.ThemeNav,StickyNav:n.exports.ThemeNav}),function(){for(var n=0,e=["ms","moz","webkit","o"],t=0;t<e.length&&!window.requestAnimationFrame;++t)window.requestAnimationFrame=window[e[t]+"RequestAnimationFrame"],window.cancelAnimationFrame=window[e[t]+"CancelAnimationFrame"]||window[e[t]+"CancelRequestAnimationFrame"];window.requestAnimationFrame||(window.requestAnimationFrame=function(e,t){var i=(new Date).getTime(),o=Math.max(0,16-(i-n)),r=window.setTimeout((function(){e(i+o)}),o);return n=i+o,r}),window.cancelAnimationFrame||(window.cancelAnimationFrame=function(n){clearTimeout(n)})}()}).call(window)},function(n,e){n.exports=jQueLine truncated
@@ -0,0 +1,228 @@
const themeFlyoutDisplay = "hidden";
const themeVersionSelector = true;
const themeLanguageSelector = true;
if (themeFlyoutDisplay === "attached") {
function renderLanguages(config) {
if (!config.projects.translations.length) {
return "";
}
// Insert the current language to the options on the selector
let languages = config.projects.translations.concat(config.projects.current);
languages = languages.sort((a, b) => a.language.name.localeCompare(b.language.name));
const languagesHTML = `
<dl>
<dt>Languages</dt>
${languages
.map(
(translation) => `
<dd ${translation.slug == config.projects.current.slug ? 'class="rtd-current-item"' : ""}>
<a href="${translation.urls.documentation}">${translation.language.code}</a>
</dd>
`,
)
.join("\n")}
</dl>
`;
return languagesHTML;
}
function renderVersions(config) {
if (!config.versions.active.length) {
return "";
}
const versionsHTML = `
<dl>
<dt>Versions</dt>
${config.versions.active
.map(
(version) => `
<dd ${version.slug === config.versions.current.slug ? 'class="rtd-current-item"' : ""}>
<a href="${version.urls.documentation}">${version.slug}</a>
</dd>
`,
)
.join("\n")}
</dl>
`;
return versionsHTML;
}
function renderDownloads(config) {
if (!Object.keys(config.versions.current.downloads).length) {
return "";
}
const downloadsNameDisplay = {
pdf: "PDF",
epub: "Epub",
htmlzip: "HTML",
};
const downloadsHTML = `
<dl>
<dt>Downloads</dt>
${Object.entries(config.versions.current.downloads)
.map(
([name, url]) => `
<dd>
<a href="${url}">${downloadsNameDisplay[name]}</a>
</dd>
`,
)
.join("\n")}
</dl>
`;
return downloadsHTML;
}
document.addEventListener("readthedocs-addons-data-ready", function (event) {
const config = event.detail.data();
const flyout = `
<div class="rst-versions" data-toggle="rst-versions" role="note">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> Read the Docs</span>
v: ${config.versions.current.slug}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<div class="injected">
${renderLanguages(config)}
${renderVersions(config)}
${renderDownloads(config)}
<dl>
<dt>On Read the Docs</dt>
<dd>
<a href="${config.projects.current.urls.home}">Project Home</a>
</dd>
<dd>
<a href="${config.projects.current.urls.builds}">Builds</a>
</dd>
<dd>
<a href="${config.projects.current.urls.downloads}">Downloads</a>
</dd>
</dl>
<dl>
<dt>Search</dt>
<dd>
<form id="flyout-search-form">
<input
class="wy-form"
type="text"
name="q"
aria-label="Search docs"
placeholder="Search docs"
/>
</form>
</dd>
</dl>
<hr />
<small>
<span>Hosted by <a href="https://about.readthedocs.org/?utm_source=&utm_content=flyout">Read the Docs</a></span>
</small>
</div>
</div>
`;
// Inject the generated flyout into the body HTML element.
document.body.insertAdjacentHTML("beforeend", flyout);
// Trigger the Read the Docs Addons Search modal when clicking on the "Search docs" input from inside the flyout.
document
.querySelector("#flyout-search-form")
.addEventListener("focusin", () => {
const event = new CustomEvent("readthedocs-search-show");
document.dispatchEvent(event);
});
})
}
if (themeLanguageSelector || themeVersionSelector) {
function onSelectorSwitch(event) {
const option = event.target.selectedIndex;
const item = event.target.options[option];
window.location.href = item.dataset.url;
}
document.addEventListener("readthedocs-addons-data-ready", function (event) {
const config = event.detail.data();
const versionSwitch = document.querySelector(
"div.switch-menus > div.version-switch",
);
if (themeVersionSelector) {
let versions = config.versions.active;
if (config.versions.current.hidden || config.versions.current.type === "external") {
versions.unshift(config.versions.current);
}
const versionSelect = `
<select>
${versions
.map(
(version) => `
<option
value="${version.slug}"
${config.versions.current.slug === version.slug ? 'selected="selected"' : ""}
data-url="${version.urls.documentation}">
${version.slug}
</option>`,
)
.join("\n")}
</select>
`;
versionSwitch.innerHTML = versionSelect;
versionSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
}
const languageSwitch = document.querySelector(
"div.switch-menus > div.language-switch",
);
if (themeLanguageSelector) {
if (config.projects.translations.length) {
// Add the current language to the options on the selector
let languages = config.projects.translations.concat(
config.projects.current,
);
languages = languages.sort((a, b) =>
a.language.name.localeCompare(b.language.name),
);
const languageSelect = `
<select>
${languages
.map(
(language) => `
<option
value="${language.language.code}"
${config.projects.current.slug === language.slug ? 'selected="selected"' : ""}
data-url="${language.urls.documentation}">
${language.language.name}
</option>`,
)
.join("\n")}
</select>
`;
languageSwitch.innerHTML = languageSelect;
languageSwitch.firstElementChild.addEventListener("change", onSelectorSwitch);
}
else {
languageSwitch.remove();
}
}
});
}
document.addEventListener("readthedocs-addons-data-ready", function (event) {
// Trigger the Read the Docs Addons Search modal when clicking on "Search docs" input from the topnav.
document
.querySelector("[role='search'] input")
.addEventListener("focusin", () => {
const event = new CustomEvent("readthedocs-search-show");
document.dispatchEvent(event);
});
});
@@ -0,0 +1,192 @@
/*
* This script contains the language-specific data used by searchtools.js,
* namely the list of stopwords, stemmer, scorer and splitter.
*/
var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
/* Non-minified version is copied as a separate JS file, if available */
/**
* Porter Stemmer
*/
var Stemmer = function() {
var step2list = {
ational: 'ate',
tional: 'tion',
enci: 'ence',
anci: 'ance',
izer: 'ize',
bli: 'ble',
alli: 'al',
entli: 'ent',
eli: 'e',
ousli: 'ous',
ization: 'ize',
ation: 'ate',
ator: 'ate',
alism: 'al',
iveness: 'ive',
fulness: 'ful',
ousness: 'ous',
aliti: 'al',
iviti: 'ive',
biliti: 'ble',
logi: 'log'
};
var step3list = {
icate: 'ic',
ative: '',
alize: 'al',
iciti: 'ic',
ical: 'ic',
ful: '',
ness: ''
};
var c = "[^aeiou]"; // consonant
var v = "[aeiouy]"; // vowel
var C = c + "[^aeiouy]*"; // consonant sequence
var V = v + "[aeiou]*"; // vowel sequence
var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
var s_v = "^(" + C + ")?" + v; // vowel in stem
this.stemWord = function (w) {
var stem;
var suffix;
var firstch;
var origword = w;
if (w.length < 3)
return w;
var re;
var re2;
var re3;
var re4;
firstch = w.substr(0,1);
if (firstch == "y")
w = firstch.toUpperCase() + w.substr(1);
// Step 1a
re = /^(.+?)(ss|i)es$/;
re2 = /^(.+?)([^s])s$/;
if (re.test(w))
w = w.replace(re,"$1$2");
else if (re2.test(w))
w = w.replace(re2,"$1$2");
// Step 1b
re = /^(.+?)eed$/;
re2 = /^(.+?)(ed|ing)$/;
if (re.test(w)) {
var fp = re.exec(w);
re = new RegExp(mgr0);
if (re.test(fp[1])) {
re = /.$/;
w = w.replace(re,"");
}
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1];
re2 = new RegExp(s_v);
if (re2.test(stem)) {
w = stem;
re2 = /(at|bl|iz)$/;
re3 = new RegExp("([^aeiouylsz])\\1$");
re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re2.test(w))
w = w + "e";
else if (re3.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
else if (re4.test(w))
w = w + "e";
}
}
// Step 1c
re = /^(.+?)y$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(s_v);
if (re.test(stem))
w = stem + "i";
}
// Step 2
re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step2list[suffix];
}
// Step 3
re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step3list[suffix];
}
// Step 4
re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
re2 = /^(.+?)(s|t)(ion)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
if (re.test(stem))
w = stem;
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1] + fp[2];
re2 = new RegExp(mgr1);
if (re2.test(stem))
w = stem;
}
// Step 5
re = /^(.+?)e$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
re2 = new RegExp(meq1);
re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
w = stem;
}
re = /ll$/;
re2 = new RegExp(mgr1);
if (re.test(w) && re2.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
// and turn initial Y back to y
if (firstch == "y")
w = firstch.toLowerCase() + w.substr(1);
return w;
}
}
Binary file not shown.

After

Width:  |  Height:  |  Size: 90 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 B

@@ -0,0 +1,75 @@
pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight { background: #f8f8f8; }
.highlight .c { color: #3D7B7B; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #008000; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .ch { color: #3D7B7B; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #3D7B7B; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #9C6500 } /* Comment.Preproc */
.highlight .cpf { color: #3D7B7B; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #3D7B7B; font-style: italic } /* Comment.Single */
.highlight .cs { color: #3D7B7B; font-style: italic } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #E40000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #008400 } /* Generic.Inserted */
.highlight .go { color: #717171 } /* Generic.Output */
.highlight .gp { color: #000080; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .kc { color: #008000; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #008000; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #008000; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #008000 } /* Keyword.Pseudo */
.highlight .kr { color: #008000; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #B00040 } /* Keyword.Type */
.highlight .m { color: #666666 } /* Literal.Number */
.highlight .s { color: #BA2121 } /* Literal.String */
.highlight .na { color: #687822 } /* Name.Attribute */
.highlight .nb { color: #008000 } /* Name.Builtin */
.highlight .nc { color: #0000FF; font-weight: bold } /* Name.Class */
.highlight .no { color: #880000 } /* Name.Constant */
.highlight .nd { color: #AA22FF } /* Name.Decorator */
.highlight .ni { color: #717171; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #CB3F38; font-weight: bold } /* Name.Exception */
.highlight .nf { color: #0000FF } /* Name.Function */
.highlight .nl { color: #767600 } /* Name.Label */
.highlight .nn { color: #0000FF; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #008000; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #19177C } /* Name.Variable */
.highlight .ow { color: #AA22FF; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #666666 } /* Literal.Number.Bin */
.highlight .mf { color: #666666 } /* Literal.Number.Float */
.highlight .mh { color: #666666 } /* Literal.Number.Hex */
.highlight .mi { color: #666666 } /* Literal.Number.Integer */
.highlight .mo { color: #666666 } /* Literal.Number.Oct */
.highlight .sa { color: #BA2121 } /* Literal.String.Affix */
.highlight .sb { color: #BA2121 } /* Literal.String.Backtick */
.highlight .sc { color: #BA2121 } /* Literal.String.Char */
.highlight .dl { color: #BA2121 } /* Literal.String.Delimiter */
.highlight .sd { color: #BA2121; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #BA2121 } /* Literal.String.Double */
.highlight .se { color: #AA5D1F; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #BA2121 } /* Literal.String.Heredoc */
.highlight .si { color: #A45A77; font-weight: bold } /* Literal.String.Interpol */
.highlight .sx { color: #008000 } /* Literal.String.Other */
.highlight .sr { color: #A45A77 } /* Literal.String.Regex */
.highlight .s1 { color: #BA2121 } /* Literal.String.Single */
.highlight .ss { color: #19177C } /* Literal.String.Symbol */
.highlight .bp { color: #008000 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #0000FF } /* Name.Function.Magic */
.highlight .vc { color: #19177C } /* Name.Variable.Class */
.highlight .vg { color: #19177C } /* Name.Variable.Global */
.highlight .vi { color: #19177C } /* Name.Variable.Instance */
.highlight .vm { color: #19177C } /* Name.Variable.Magic */
.highlight .il { color: #666666 } /* Literal.Number.Integer.Long */
@@ -0,0 +1,632 @@
/*
* Sphinx JavaScript utilities for the full-text search.
*/
"use strict";
/**
* Simple result scoring code.
*/
if (typeof Scorer === "undefined") {
var Scorer = {
// Implement the following function to further tweak the score for each result
// The function takes a result array [docname, title, anchor, descr, score, filename]
// and returns the new score.
/*
score: result => {
const [docname, title, anchor, descr, score, filename, kind] = result
return score
},
*/
// query matches the full name of an object
objNameMatch: 11,
// or matches in the last dotted part of the object name
objPartialMatch: 6,
// Additive scores depending on the priority of the object
objPrio: {
0: 15, // used to be importantResults
1: 5, // used to be objectResults
2: -5, // used to be unimportantResults
},
// Used when the priority is not in the mapping.
objPrioDefault: 0,
// query found in title
title: 15,
partialTitle: 7,
// query found in terms
term: 5,
partialTerm: 2,
};
}
// Global search result kind enum, used by themes to style search results.
class SearchResultKind {
static get index() { return "index"; }
static get object() { return "object"; }
static get text() { return "text"; }
static get title() { return "title"; }
}
const _removeChildren = (element) => {
while (element && element.lastChild) element.removeChild(element.lastChild);
};
/**
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
*/
const _escapeRegExp = (string) =>
string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
const _displayItem = (item, searchTerms, highlightTerms) => {
const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
const contentRoot = document.documentElement.dataset.content_root;
const [docName, title, anchor, descr, score, _filename, kind] = item;
let listItem = document.createElement("li");
// Add a class representing the item's type:
// can be used by a theme's CSS selector for styling
// See SearchResultKind for the class names.
listItem.classList.add(`kind-${kind}`);
let requestUrl;
let linkUrl;
if (docBuilder === "dirhtml") {
// dirhtml builder
let dirname = docName + "/";
if (dirname.match(/\/index\/$/))
dirname = dirname.substring(0, dirname.length - 6);
else if (dirname === "index/") dirname = "";
requestUrl = contentRoot + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = contentRoot + docName + docFileSuffix;
linkUrl = docName + docLinkSuffix;
}
let linkEl = listItem.appendChild(document.createElement("a"));
linkEl.href = linkUrl + anchor;
linkEl.dataset.score = score;
linkEl.innerHTML = title;
if (descr) {
listItem.appendChild(document.createElement("span")).innerHTML =
" (" + descr + ")";
// highlight search terms in the description
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
}
else if (showSearchSummary)
fetch(requestUrl)
.then((responseData) => responseData.text())
.then((data) => {
if (data)
listItem.appendChild(
Search.makeSearchSummary(data, searchTerms, anchor)
);
// highlight search terms in the summary
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
});
Search.output.appendChild(listItem);
};
const _finishSearch = (resultCount) => {
Search.stopPulse();
Search.title.innerText = _("Search Results");
if (!resultCount)
Search.status.innerText = Documentation.gettext(
"Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
);
else
Search.status.innerText = Documentation.ngettext(
"Search finished, found one page matching the search query.",
"Search finished, found ${resultCount} pages matching the search query.",
resultCount,
).replace('${resultCount}', resultCount);
};
const _displayNextItem = (
results,
resultCount,
searchTerms,
highlightTerms,
) => {
// results left, load the summary and display it
// this is intended to be dynamic (don't sub resultsCount)
if (results.length) {
_displayItem(results.pop(), searchTerms, highlightTerms);
setTimeout(
() => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
5
);
}
// search finished, update title and status message
else _finishSearch(resultCount);
};
// Helper function used by query() to order search results.
// Each input is an array of [docname, title, anchor, descr, score, filename, kind].
// Order the results by score (in opposite order of appearance, since the
// `_displayNextItem` function uses pop() to retrieve items) and then alphabetically.
const _orderResultsByScoreThenName = (a, b) => {
const leftScore = a[4];
const rightScore = b[4];
if (leftScore === rightScore) {
// same score: sort alphabetically
const leftTitle = a[1].toLowerCase();
const rightTitle = b[1].toLowerCase();
if (leftTitle === rightTitle) return 0;
return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
}
return leftScore > rightScore ? 1 : -1;
};
/**
* Default splitQuery function. Can be overridden in ``sphinx.search`` with a
* custom function per language.
*
* The regular expression works by splitting the string on consecutive characters
* that are not Unicode letters, numbers, underscores, or emoji characters.
* This is the same as ``\W+`` in Python, preserving the surrogate pair area.
*/
if (typeof splitQuery === "undefined") {
var splitQuery = (query) => query
.split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
.filter(term => term) // remove remaining empty strings
}
/**
* Search Module
*/
const Search = {
_index: null,
_queued_query: null,
_pulse_status: -1,
htmlToText: (htmlString, anchor) => {
const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
for (const removalQuery of [".headerlink", "script", "style"]) {
htmlElement.querySelectorAll(removalQuery).forEach((el) => { el.remove() });
}
if (anchor) {
const anchorContent = htmlElement.querySelector(`[role="main"] ${anchor}`);
if (anchorContent) return anchorContent.textContent;
console.warn(
`Anchored content block not found. Sphinx search tries to obtain it via DOM query '[role=main] ${anchor}'. Check your theme or template.`
);
}
// if anchor not specified or not found, fall back to main content
const docContent = htmlElement.querySelector('[role="main"]');
if (docContent) return docContent.textContent;
console.warn(
"Content block not found. Sphinx search tries to obtain it via DOM query '[role=main]'. Check your theme or template."
);
return "";
},
init: () => {
const query = new URLSearchParams(window.location.search).get("q");
document
.querySelectorAll('input[name="q"]')
.forEach((el) => (el.value = query));
if (query) Search.performSearch(query);
},
loadIndex: (url) =>
(document.body.appendChild(document.createElement("script")).src = url),
setIndex: (index) => {
Search._index = index;
if (Search._queued_query !== null) {
const query = Search._queued_query;
Search._queued_query = null;
Search.query(query);
}
},
hasIndex: () => Search._index !== null,
deferQuery: (query) => (Search._queued_query = query),
stopPulse: () => (Search._pulse_status = -1),
startPulse: () => {
if (Search._pulse_status >= 0) return;
const pulse = () => {
Search._pulse_status = (Search._pulse_status + 1) % 4;
Search.dots.innerText = ".".repeat(Search._pulse_status);
if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
};
pulse();
},
/**
* perform a search for something (or wait until index is loaded)
*/
performSearch: (query) => {
// create the required interface elements
const searchText = document.createElement("h2");
searchText.textContent = _("Searching");
const searchSummary = document.createElement("p");
searchSummary.classList.add("search-summary");
searchSummary.innerText = "";
const searchList = document.createElement("ul");
searchList.setAttribute("role", "list");
searchList.classList.add("search");
const out = document.getElementById("search-results");
Search.title = out.appendChild(searchText);
Search.dots = Search.title.appendChild(document.createElement("span"));
Search.status = out.appendChild(searchSummary);
Search.output = out.appendChild(searchList);
const searchProgress = document.getElementById("search-progress");
// Some themes don't use the search progress node
if (searchProgress) {
searchProgress.innerText = _("Preparing search...");
}
Search.startPulse();
// index already loaded, the browser was quick!
if (Search.hasIndex()) Search.query(query);
else Search.deferQuery(query);
},
_parseQuery: (query) => {
// stem the search terms and add them to the correct list
const stemmer = new Stemmer();
const searchTerms = new Set();
const excludedTerms = new Set();
const highlightTerms = new Set();
const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
splitQuery(query.trim()).forEach((queryTerm) => {
const queryTermLower = queryTerm.toLowerCase();
// maybe skip this "word"
// stopwords array is from language_data.js
if (
stopwords.indexOf(queryTermLower) !== -1 ||
queryTerm.match(/^\d+$/)
)
return;
// stem the word
let word = stemmer.stemWord(queryTermLower);
// select the correct list
if (word[0] === "-") excludedTerms.add(word.substr(1));
else {
searchTerms.add(word);
highlightTerms.add(queryTermLower);
}
});
if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js
localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
}
// console.debug("SEARCH: searching for:");
// console.info("required: ", [...searchTerms]);
// console.info("excluded: ", [...excludedTerms]);
return [query, searchTerms, excludedTerms, highlightTerms, objectTerms];
},
/**
* execute search (requires search index to be loaded)
*/
_performSearch: (query, searchTerms, excludedTerms, highlightTerms, objectTerms) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const allTitles = Search._index.alltitles;
const indexEntries = Search._index.indexentries;
// Collect multiple result groups to be sorted separately and then ordered.
// Each is an array of [docname, title, anchor, descr, score, filename, kind].
const normalResults = [];
const nonMainIndexResults = [];
_removeChildren(document.getElementById("search-progress"));
const queryLower = query.toLowerCase().trim();
for (const [title, foundTitles] of Object.entries(allTitles)) {
if (title.toLowerCase().trim().includes(queryLower) && (queryLower.length >= title.length/2)) {
for (const [file, id] of foundTitles) {
const score = Math.round(Scorer.title * queryLower.length / title.length);
const boost = titles[file] === title ? 1 : 0; // add a boost for document titles
normalResults.push([
docNames[file],
titles[file] !== title ? `${titles[file]} > ${title}` : title,
id !== null ? "#" + id : "",
null,
score + boost,
filenames[file],
SearchResultKind.title,
]);
}
}
}
// search for explicit entries in index directives
for (const [entry, foundEntries] of Object.entries(indexEntries)) {
if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
for (const [file, id, isMain] of foundEntries) {
const score = Math.round(100 * queryLower.length / entry.length);
const result = [
docNames[file],
titles[file],
id ? "#" + id : "",
null,
score,
filenames[file],
SearchResultKind.index,
];
if (isMain) {
normalResults.push(result);
} else {
nonMainIndexResults.push(result);
}
}
}
}
// lookup as object
objectTerms.forEach((term) =>
normalResults.push(...Search.performObjectSearch(term, objectTerms))
);
// lookup as search terms in fulltext
normalResults.push(...Search.performTermsSearch(searchTerms, excludedTerms));
// let the scorer override scores with a custom scoring function
if (Scorer.score) {
normalResults.forEach((item) => (item[4] = Scorer.score(item)));
nonMainIndexResults.forEach((item) => (item[4] = Scorer.score(item)));
}
// Sort each group of results by score and then alphabetically by name.
normalResults.sort(_orderResultsByScoreThenName);
nonMainIndexResults.sort(_orderResultsByScoreThenName);
// Combine the result groups in (reverse) order.
// Non-main index entries are typically arbitrary cross-references,
// so display them after other results.
let results = [...nonMainIndexResults, ...normalResults];
// remove duplicate search results
// note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
let seen = new Set();
results = results.reverse().reduce((acc, result) => {
let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(',');
if (!seen.has(resultStr)) {
acc.push(result);
seen.add(resultStr);
}
return acc;
}, []);
return results.reverse();
},
query: (query) => {
const [searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms] = Search._parseQuery(query);
const results = Search._performSearch(searchQuery, searchTerms, excludedTerms, highlightTerms, objectTerms);
// for debugging
//Search.lastresults = results.slice(); // a copy
// console.info("search results:", Search.lastresults);
// print the results
_displayNextItem(results, results.length, searchTerms, highlightTerms);
},
/**
* search for object names
*/
performObjectSearch: (object, objectTerms) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const objects = Search._index.objects;
const objNames = Search._index.objnames;
const titles = Search._index.titles;
const results = [];
const objectSearchCallback = (prefix, match) => {
const name = match[4]
const fullname = (prefix ? prefix + "." : "") + name;
const fullnameLower = fullname.toLowerCase();
if (fullnameLower.indexOf(object) < 0) return;
let score = 0;
const parts = fullnameLower.split(".");
// check for different match types: exact matches of full name or
// "last name" (i.e. last dotted part)
if (fullnameLower === object || parts.slice(-1)[0] === object)
score += Scorer.objNameMatch;
else if (parts.slice(-1)[0].indexOf(object) > -1)
score += Scorer.objPartialMatch; // matches in last name
const objName = objNames[match[1]][2];
const title = titles[match[0]];
// If more than one term searched for, we require other words to be
// found in the name/title/description
const otherTerms = new Set(objectTerms);
otherTerms.delete(object);
if (otherTerms.size > 0) {
const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
if (
[...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
)
return;
}
let anchor = match[3];
if (anchor === "") anchor = fullname;
else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
const descr = objName + _(", in ") + title;
// add custom score for some objects according to scorer
if (Scorer.objPrio.hasOwnProperty(match[2]))
score += Scorer.objPrio[match[2]];
else score += Scorer.objPrioDefault;
results.push([
docNames[match[0]],
fullname,
"#" + anchor,
descr,
score,
filenames[match[0]],
SearchResultKind.object,
]);
};
Object.keys(objects).forEach((prefix) =>
objects[prefix].forEach((array) =>
objectSearchCallback(prefix, array)
)
);
return results;
},
/**
* search for full-text terms in the index
*/
performTermsSearch: (searchTerms, excludedTerms) => {
// prepare search
const terms = Search._index.terms;
const titleTerms = Search._index.titleterms;
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const scoreMap = new Map();
const fileMap = new Map();
// perform the search on the required terms
searchTerms.forEach((word) => {
const files = [];
const arr = [
{ files: terms[word], score: Scorer.term },
{ files: titleTerms[word], score: Scorer.title },
];
// add support for partial matches
if (word.length > 2) {
const escapedWord = _escapeRegExp(word);
if (!terms.hasOwnProperty(word)) {
Object.keys(terms).forEach((term) => {
if (term.match(escapedWord))
arr.push({ files: terms[term], score: Scorer.partialTerm });
});
}
if (!titleTerms.hasOwnProperty(word)) {
Object.keys(titleTerms).forEach((term) => {
if (term.match(escapedWord))
arr.push({ files: titleTerms[term], score: Scorer.partialTitle });
});
}
}
// no match but word was a required one
if (arr.every((record) => record.files === undefined)) return;
// found search word in contents
arr.forEach((record) => {
if (record.files === undefined) return;
let recordFiles = record.files;
if (recordFiles.length === undefined) recordFiles = [recordFiles];
files.push(...recordFiles);
// set score for the word in each file
recordFiles.forEach((file) => {
if (!scoreMap.has(file)) scoreMap.set(file, {});
scoreMap.get(file)[word] = record.score;
});
});
// create the mapping
files.forEach((file) => {
if (!fileMap.has(file)) fileMap.set(file, [word]);
else if (fileMap.get(file).indexOf(word) === -1) fileMap.get(file).push(word);
});
});
// now check if the files don't contain excluded terms
const results = [];
for (const [file, wordList] of fileMap) {
// check if all requirements are matched
// as search terms with length < 3 are discarded
const filteredTermCount = [...searchTerms].filter(
(term) => term.length > 2
).length;
if (
wordList.length !== searchTerms.size &&
wordList.length !== filteredTermCount
)
continue;
// ensure that none of the excluded terms is in the search result
if (
[...excludedTerms].some(
(term) =>
terms[term] === file ||
titleTerms[term] === file ||
(terms[term] || []).includes(file) ||
(titleTerms[term] || []).includes(file)
)
)
break;
// select one (max) score for the file.
const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
// add result to the result list
results.push([
docNames[file],
titles[file],
"",
null,
score,
filenames[file],
SearchResultKind.text,
]);
}
return results;
},
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words.
*/
makeSearchSummary: (htmlText, keywords, anchor) => {
const text = Search.htmlToText(htmlText, anchor);
if (text === "") return null;
const textLower = text.toLowerCase();
const actualStartPosition = [...keywords]
.map((k) => textLower.indexOf(k.toLowerCase()))
.filter((i) => i > -1)
.slice(-1)[0];
const startWithContext = Math.max(actualStartPosition - 120, 0);
const top = startWithContext === 0 ? "" : "...";
const tail = startWithContext + 240 < text.length ? "..." : "";
let summary = document.createElement("p");
summary.classList.add("context");
summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
return summary;
},
};
_ready(Search.init);
@@ -0,0 +1,154 @@
/* Highlighting utilities for Sphinx HTML documentation. */
"use strict";
const SPHINX_HIGHLIGHT_ENABLED = true
/**
* highlight a given string on a node by wrapping it in
* span elements with the given class name.
*/
const _highlight = (node, addItems, text, className) => {
if (node.nodeType === Node.TEXT_NODE) {
const val = node.nodeValue;
const parent = node.parentNode;
const pos = val.toLowerCase().indexOf(text);
if (
pos >= 0 &&
!parent.classList.contains(className) &&
!parent.classList.contains("nohighlight")
) {
let span;
const closestNode = parent.closest("body, svg, foreignObject");
const isInSVG = closestNode && closestNode.matches("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.classList.add(className);
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
const rest = document.createTextNode(val.substr(pos + text.length));
parent.insertBefore(
span,
parent.insertBefore(
rest,
node.nextSibling
)
);
node.nodeValue = val.substr(0, pos);
/* There may be more occurrences of search term in this node. So call this
* function recursively on the remaining fragment.
*/
_highlight(rest, addItems, text, className);
if (isInSVG) {
const rect = document.createElementNS(
"http://www.w3.org/2000/svg",
"rect"
);
const bbox = parent.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute("class", className);
addItems.push({ parent: parent, target: rect });
}
}
} else if (node.matches && !node.matches("button, select, textarea")) {
node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
}
};
const _highlightText = (thisNode, text, className) => {
let addItems = [];
_highlight(thisNode, addItems, text, className);
addItems.forEach((obj) =>
obj.parent.insertAdjacentElement("beforebegin", obj.target)
);
};
/**
* Small JavaScript module for the documentation.
*/
const SphinxHighlight = {
/**
* highlight the search words provided in localstorage in the text
*/
highlightSearchWords: () => {
if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
// get and clear terms from localstorage
const url = new URL(window.location);
const highlight =
localStorage.getItem("sphinx_highlight_terms")
|| url.searchParams.get("highlight")
|| "";
localStorage.removeItem("sphinx_highlight_terms")
url.searchParams.delete("highlight");
window.history.replaceState({}, "", url);
// get individual terms from highlight string
const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
if (terms.length === 0) return; // nothing to do
// There should never be more than one element matching "div.body"
const divBody = document.querySelectorAll("div.body");
const body = divBody.length ? divBody[0] : document.querySelector("body");
window.setTimeout(() => {
terms.forEach((term) => _highlightText(body, term, "highlighted"));
}, 10);
const searchBox = document.getElementById("searchbox");
if (searchBox === null) return;
searchBox.appendChild(
document
.createRange()
.createContextualFragment(
'<p class="highlight-link">' +
'<a href="javascript:SphinxHighlight.hideSearchWords()">' +
_("Hide Search Matches") +
"</a></p>"
)
);
},
/**
* helper function to hide the search marks again
*/
hideSearchWords: () => {
document
.querySelectorAll("#searchbox .highlight-link")
.forEach((el) => el.remove());
document
.querySelectorAll("span.highlighted")
.forEach((el) => el.classList.remove("highlighted"));
localStorage.removeItem("sphinx_highlight_terms")
},
initEscapeListener: () => {
// only install a listener if it is really needed
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
SphinxHighlight.hideSearchWords();
event.preventDefault();
}
});
},
};
_ready(() => {
/* Do not call highlightSearchWords() when we are on the search page.
* It will highlight words from the *previous* search query.
*/
if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
SphinxHighlight.initEscapeListener();
});
+495
View File
@@ -0,0 +1,495 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Index &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=6bd3bce2"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="#" />
<link rel="search" title="Search" href="search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="other/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware/hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Index</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<h1 id="index">Index</h1>
<div class="genindex-jumpbox">
<a href="#_"><strong>_</strong></a>
| <a href="#A"><strong>A</strong></a>
| <a href="#B"><strong>B</strong></a>
| <a href="#C"><strong>C</strong></a>
| <a href="#D"><strong>D</strong></a>
| <a href="#E"><strong>E</strong></a>
| <a href="#F"><strong>F</strong></a>
| <a href="#G"><strong>G</strong></a>
| <a href="#I"><strong>I</strong></a>
| <a href="#L"><strong>L</strong></a>
| <a href="#M"><strong>M</strong></a>
| <a href="#P"><strong>P</strong></a>
| <a href="#R"><strong>R</strong></a>
| <a href="#S"><strong>S</strong></a>
| <a href="#T"><strong>T</strong></a>
| <a href="#U"><strong>U</strong></a>
| <a href="#V"><strong>V</strong></a>
| <a href="#W"><strong>W</strong></a>
</div>
<h2 id="_">_</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c._125M">_125M (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="A">A</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv411acknowledgev">acknowledge (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv421adc_offset_adjustment8uint32_t">adc_offset_adjustment (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv418address_evaluation7uint8_tA_K7uint8_t">address_evaluation (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv416adjust_pwm_level8uint16_t">adjust_pwm_level (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="B">B</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.BASE_PWM_ARR_LEN">BASE_PWM_ARR_LEN (C macro)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv418bits_to_byte_array6int8_tA_7uint8_t">bits_to_byte_array (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="C">C</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv411clr_bit_arr">clr_bit_arr (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv418controller_generalP15repeating_timer">controller_general (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv417controller_mode_t">controller_mode_t (C++ enum)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N17controller_mode_t8PID_MODEE">controller_mode_t::PID_MODE (C++ enumerator)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N17controller_mode_t12STARTUP_MODEE">controller_mode_t::STARTUP_MODE (C++ enumerator)</a>
</li>
<li><a href="software/header_files.html#_CPPv422controller_parameter_t">controller_parameter_t (C++ struct)</a>
<ul>
<li><a href="software/header_files.html#_CPPv422controller_parameter_t">(C++ type)</a>
</li>
</ul></li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t10adc_offsetE">controller_parameter_t::adc_offset (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t8feed_fwdE">controller_parameter_t::feed_fwd (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t17l_side_arr_cutoffE">controller_parameter_t::l_side_arr_cutoff (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t11measurementE">controller_parameter_t::measurement (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t21measurement_correctedE">controller_parameter_t::measurement_corrected (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t16measurement_prevE">controller_parameter_t::measurement_prev (C++ member)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t4modeE">controller_parameter_t::mode (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t15msr_delay_in_usE">controller_parameter_t::msr_delay_in_us (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t20msr_total_iterationsE">controller_parameter_t::msr_total_iterations (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t3pidE">controller_parameter_t::pid (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t17r_side_arr_cutoffE">controller_parameter_t::r_side_arr_cutoff (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t8setpointE">controller_parameter_t::setpoint (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t11speed_tableE">controller_parameter_t::speed_table (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N22controller_parameter_t7startupE">controller_parameter_t::startup (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv423controller_startup_modeP22controller_parameter_t">controller_startup_mode (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv411core1_entryv">core1_entry (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv414CV_ARRAY_FLASH">CV_ARRAY_FLASH (C++ member)</a>
</li>
<li><a href="software/header_files.html#c.CV_ARRAY_SIZE">CV_ARRAY_SIZE (C macro)</a>
</li>
<li><a href="software/header_files.html#_CPPv414cv_setup_checkv">cv_setup_check (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="D">D</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.DCC_INPUT_PIN">DCC_INPUT_PIN (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="E">E</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv415error_detection6int8_tPK7uint8_t">error_detection (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv416evaluate_messagev">evaluate_message (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="F">F</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.FLASH_TARGET_OFFSET">FLASH_TARGET_OFFSET (C macro)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.FWD_V_EMF_ADC_PIN">FWD_V_EMF_ADC_PIN (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="G">G</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv412get_16bit_CV8uint16_t">get_16bit_CV (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv412get_32bit_CV8uint16_t">get_32bit_CV (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv427get_direction_of_speed_step7uint8_t">get_direction_of_speed_step (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv417get_initial_levelP22controller_parameter_t">get_initial_level (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv46get_kpPK22controller_parameter_t">get_kp (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv440get_speed_step_table_index_of_speed_step7uint8_t">get_speed_step_table_index_of_speed_step (C++ function)</a>
</li>
<li><a href="software/header_files.html#c.GPIO_ALLOWED_OUTPUTS">GPIO_ALLOWED_OUTPUTS (C macro)</a>
</li>
<li><a href="software/header_files.html#c.GPIO_ILLEGAL_MASK">GPIO_ILLEGAL_MASK (C macro)</a>
</li>
<li><a href="software/header_files.html#c.GPIO_OUTPUT_PIN_MASK">GPIO_OUTPUT_PIN_MASK (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="I">I</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv48init_adcv">init_adc (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv415init_controllerP22controller_parameter_t">init_controller (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv414init_motor_pwm7uint8_t">init_motor_pwm (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv412init_outputsv">init_outputs (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv422instruction_evaluation7uint8_tA_K7uint8_t">instruction_evaluation (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv415is_long_address7uint8_tA_K7uint8_t">is_long_address (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="L">L</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.LOG">LOG (C macro)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.LOGLEVEL">LOGLEVEL (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="M">M</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv47measure7uint8_t7uint8_t7uint8_t7uint8_tb">measure (C++ function)</a>
</li>
<li><a href="software/header_files.html#c.MESSAGE_3_BYTES">MESSAGE_3_BYTES (C macro)</a>
</li>
<li><a href="software/header_files.html#c.MESSAGE_4_BYTES">MESSAGE_4_BYTES (C macro)</a>
</li>
<li><a href="software/header_files.html#c.MESSAGE_5_BYTES">MESSAGE_5_BYTES (C macro)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.MESSAGE_MASK_3_BYTES">MESSAGE_MASK_3_BYTES (C macro)</a>
</li>
<li><a href="software/header_files.html#c.MESSAGE_MASK_4_BYTES">MESSAGE_MASK_4_BYTES (C macro)</a>
</li>
<li><a href="software/header_files.html#c.MESSAGE_MASK_5_BYTES">MESSAGE_MASK_5_BYTES (C macro)</a>
</li>
<li><a href="software/header_files.html#c.MOTOR_FWD_PIN">MOTOR_FWD_PIN (C macro)</a>
</li>
<li><a href="software/header_files.html#c.MOTOR_REV_PIN">MOTOR_REV_PIN (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="P">P</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv417pid_control_timer">pid_control_timer (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv415pid_parameter_t">pid_parameter_t (C++ type)</a>
</li>
<li><a href="software/header_files.html#_CPPv416pid_parameters_t">pid_parameters_t (C++ struct)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t4cd_0E">pid_parameters_t::cd_0 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t4cd_1E">pid_parameters_t::cd_1 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t4ci_0E">pid_parameters_t::ci_0 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t6d_prevE">pid_parameters_t::d_prev (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t1eE">pid_parameters_t::e (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t6e_prevE">pid_parameters_t::e_prev (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t6i_prevE">pid_parameters_t::i_prev (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t11int_lim_maxE">pid_parameters_t::int_lim_max (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t11int_lim_minE">pid_parameters_t::int_lim_min (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t3k_dE">pid_parameters_t::k_d (C++ member)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t3k_iE">pid_parameters_t::k_i (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t3k_pE">pid_parameters_t::k_p (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_m_1E">pid_parameters_t::k_p_m_1 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_m_2E">pid_parameters_t::k_p_m_2 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_x_1E">pid_parameters_t::k_p_x_1 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t13k_p_x_1_shiftE">pid_parameters_t::k_p_x_1_shift (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_x_2E">pid_parameters_t::k_p_x_2 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_y_0E">pid_parameters_t::k_p_y_0 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_y_1E">pid_parameters_t::k_p_y_1 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t7k_p_y_2E">pid_parameters_t::k_p_y_2 (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t10max_outputE">pid_parameters_t::max_output (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t1tE">pid_parameters_t::t (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N16pid_parameters_t3tauE">pid_parameters_t::tau (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv412program_mode7uint8_tA_K7uint8_t">program_mode (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="R">R</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv419reset_message_check7uint8_tPCK7uint8_t">reset_message_check (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#c.REV_V_EMF_ADC_PIN">REV_V_EMF_ADC_PIN (C macro)</a>
</li>
</ul></td>
</tr></table>
<h2 id="S">S</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv411set_outputs8uint32_t">set_outputs (C++ function)</a>
</li>
<li><a href="software/header_files.html#c.SIZE_BYTE_ARRAY">SIZE_BYTE_ARRAY (C macro)</a>
</li>
<li><a href="software/header_files.html#_CPPv412speed_helperP15repeating_timer">speed_helper (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv418speed_helper_timer">speed_helper_timer (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv417speed_step_target">speed_step_target (C++ member)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv422speed_step_target_prev">speed_step_target_prev (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv420startup_parameters_t">startup_parameters_t (C++ struct)</a>
<ul>
<li><a href="software/header_files.html#_CPPv420startup_parameters_t">(C++ type)</a>
</li>
</ul></li>
<li><a href="software/header_files.html#_CPPv4N20startup_parameters_t12base_pwm_arrE">startup_parameters_t::base_pwm_arr (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N20startup_parameters_t14base_pwm_arr_iE">startup_parameters_t::base_pwm_arr_i (C++ member)</a>
</li>
<li><a href="software/header_files.html#_CPPv4N20startup_parameters_t5levelE">startup_parameters_t::level (C++ member)</a>
</li>
</ul></td>
</tr></table>
<h2 id="T">T</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv417track_signal_falljm">track_signal_fall (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv417track_signal_risejm">track_signal_rise (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv411two_std_devA_Kf8uint32_t">two_std_dev (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="U">U</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv423update_active_functions8uint32_t7uint8_tb">update_active_functions (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="V">V</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv413verify_cv_bit8uint16_tb7uint8_t">verify_cv_bit (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv414verify_cv_byte8uint16_t7uint8_t">verify_cv_byte (C++ function)</a>
</li>
<li><a href="software/header_files.html#_CPPv418verify_dcc_messagev">verify_dcc_message (C++ function)</a>
</li>
</ul></td>
</tr></table>
<h2 id="W">W</h2>
<table style="width: 100%" class="indextable genindextable"><tr>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv413write_cv_byte8uint16_t7uint8_t">write_cv_byte (C++ function)</a>
</li>
</ul></td>
<td style="width: 33%; vertical-align: top;"><ul>
<li><a href="software/header_files.html#_CPPv416write_cv_handler8uint16_t7uint8_t">write_cv_handler (C++ function)</a>
</li>
</ul></td>
</tr></table>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+135
View File
@@ -0,0 +1,135 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Hardware &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Hardware Description" href="hw_description.html" />
<link rel="prev" title="Getting started" href="../other/getting_started.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../other/getting_started.html">Getting started</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Hardware</a><ul>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html">Hardware Description</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Hardware</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/hardware/hw.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="hardware">
<h1>Hardware<a class="headerlink" href="#hardware" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="hw_description.html">Hardware Description</a><ul>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#characteristics">Characteristics</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#input-stage">Input Stage</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#motor-driver">Motor Driver</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#auxiliary-output">Auxiliary Output</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#gpio">GPIO</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#microcontroller">Microcontroller</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#complete-schematic">Complete Schematic</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#bom-alternative-parts">BOM &amp; Alternative Parts</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#alternatives-for-bdr6133">Alternatives for BDR6133:</a></li>
<li class="toctree-l2"><a class="reference internal" href="hw_description.html#alternative-for-ht7533s">Alternative for HT7533S:</a></li>
</ul>
</li>
</ul>
</div>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../other/getting_started.html" class="btn btn-neutral float-left" title="Getting started" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="hw_description.html" class="btn btn-neutral float-right" title="Hardware Description" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
@@ -0,0 +1,362 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Hardware Description &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Software" href="../software/sw.html" />
<link rel="prev" title="Hardware" href="hw.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../other/getting_started.html">Getting started</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="hw.html">Hardware</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Hardware Description</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#characteristics">Characteristics</a></li>
<li class="toctree-l3"><a class="reference internal" href="#input-stage">Input Stage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#motor-driver">Motor Driver</a></li>
<li class="toctree-l3"><a class="reference internal" href="#auxiliary-output">Auxiliary Output</a></li>
<li class="toctree-l3"><a class="reference internal" href="#gpio">GPIO</a></li>
<li class="toctree-l3"><a class="reference internal" href="#microcontroller">Microcontroller</a></li>
<li class="toctree-l3"><a class="reference internal" href="#complete-schematic">Complete Schematic</a></li>
<li class="toctree-l3"><a class="reference internal" href="#bom-alternative-parts">BOM &amp; Alternative Parts</a></li>
<li class="toctree-l3"><a class="reference internal" href="#alternatives-for-bdr6133">Alternatives for BDR6133:</a></li>
<li class="toctree-l3"><a class="reference internal" href="#alternative-for-ht7533s">Alternative for HT7533S:</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="hw.html">Hardware</a></li>
<li class="breadcrumb-item active">Hardware Description</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/hardware/hw_description.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="hardware-description">
<h1>Hardware Description<a class="headerlink" href="#hardware-description" title="Link to this heading"></a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<img alt="Block Diagram" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Block_Diagram.svg" />
<p>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.</p>
<ul class="simple">
<li><p><strong>Input Stage</strong>
- DCC Signal Level Shift
- Bridge Rectifier &amp; Voltage Regulator</p></li>
<li><p><strong>Motor Driver</strong>
- Motor Driver
- Back EMF measurement (ADC)</p></li>
<li><p><strong>General Purpose</strong>
- GPIO
- Auxiliary output</p></li>
<li><p><strong>Microcontroller</strong>
- Flash memory
- Crystal oscillator</p></li>
</ul>
</section>
<section id="characteristics">
<h2>Characteristics<a class="headerlink" href="#characteristics" title="Link to this heading"></a></h2>
<table class="docutils align-default" id="id1">
<caption><span class="caption-text">Characteristics table</span><a class="headerlink" href="#id1" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Symbol</p></th>
<th class="head"><p>Minimum</p></th>
<th class="head"><p>Maximum</p></th>
<th class="head"><p>Unit</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Absolute max. DCC Input Voltage</p></td>
<td><p>V<sub>DCC</sub></p></td>
<td><p>-25</p></td>
<td><p>+25</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-odd"><td><p>Absolute max. GPIO Voltage<sup>(0)</sup></p></td>
<td><p>V<sub>PIN</sub></p></td>
<td><p>-0.5</p></td>
<td><p>3.3+0.5</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-even"><td><p>Input Voltage High<sup>(0)</sup></p></td>
<td><p>V<sub>IH</sub></p></td>
<td><p>2.145</p></td>
<td><p>3.6</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-odd"><td><p>Input Voltage Low<sup>(0)</sup></p></td>
<td><p>V<sub>IL</sub></p></td>
<td><p>0</p></td>
<td><p>1.155</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-even"><td><p>Total GPIO Current<sup>(0)</sup></p></td>
<td><p>I<sub>IOVDD</sub></p></td>
<td></td>
<td><p>50</p></td>
<td><p>mA</p></td>
</tr>
<tr class="row-odd"><td><p>Absolute max. motor output current<sup>(1)</sup></p></td>
<td><p>I<sub>MOTOR</sub></p></td>
<td></td>
<td><p>2.8</p></td>
<td><p>A</p></td>
</tr>
<tr class="row-even"><td><p>Absolute max. auxiliary output current <sup>(2)</sup></p></td>
<td><p>I<sub>AUX</sub></p></td>
<td></td>
<td><p>400</p></td>
<td><p>mA</p></td>
</tr>
</tbody>
</table>
<p>(0): According to: <a class="reference external" href="https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf">RP2040 Datasheet</a> (assuming V<sub>DD</sub>= 3.3V)</p>
<p>(1): According to: <a class="reference external" href="https://datasheet.lcsc.com/lcsc/2101211904_Bardeen-Micro--BDR6133_C2687793.pdf">BDR6133 Datasheet</a></p>
<p>(2): According to: <a class="reference external" href="https://datasheet.lcsc.com/lcsc/1810271831_TOSHIBA-T2N7002BK-LM_C146372.pdf">T2N7002BK Datasheet</a></p>
</section>
<section id="input-stage">
<h2>Input Stage<a class="headerlink" href="#input-stage" title="Link to this heading"></a></h2>
<img alt="Input Stage" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Input_Stage.svg" />
<p>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).</p>
<p>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&lt;sub&gt;GS&lt;/sub&gt; &gt; V&lt;sub&gt;GS,th&lt;/sub&gt;), GPIO21 gets pulled to GND potential. R1 and R2 ensure that V&lt;sub&gt;GS&lt;/sub&gt; doesn’t exceed ±20V.</p>
</section>
<section id="motor-driver">
<h2>Motor Driver<a class="headerlink" href="#motor-driver" title="Link to this heading"></a></h2>
<img alt="Motor Driver" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Motor_Driver.svg" />
<p>The Motor Driver is a complete H-Bridge IC specifically made for DC-Motors.</p>
<p>In order to control the motor, it is necessary to measure the back-EMF. This is done by the ADC, which measures at Points ADC_EMF_A and ADC_EMF_B respectively. The two resistors are used as a voltage divider.</p>
</section>
<section id="auxiliary-output">
<h2>Auxiliary Output<a class="headerlink" href="#auxiliary-output" title="Link to this heading"></a></h2>
<img alt="Auxiliary Output" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Aux_Outputs.svg" />
<p>Switching of loads up to a maximum of about ~400mA can be done using four N-Channel MOSFETs. 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.</p>
</section>
<section id="gpio">
<h2>GPIO<a class="headerlink" href="#gpio" title="Link to this heading"></a></h2>
<p>To switch lighter loads, six soldering pads on the back side of the PCB are connected to GPIO0 - GPIO5 pins. Although not implemented yet, they could theoretically be used as inputs as well (e.g., Reed switch).</p>
</section>
<section id="microcontroller">
<h2>Microcontroller<a class="headerlink" href="#microcontroller" title="Link to this heading"></a></h2>
<img alt="Microcontroller" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Microcontroller.svg" />
<p>The Microcontroller needs a crystal oscillator to function properly. External flash memory is also needed as it holds the configuration variables and the program itself. R3 &amp; C14 are used to filter ADC_AVDD (ADC Reference Voltage).</p>
</section>
<section id="complete-schematic">
<h2>Complete Schematic<a class="headerlink" href="#complete-schematic" title="Link to this heading"></a></h2>
<img alt="Complete Schematic" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/RP2040-Decoder.svg" />
</section>
<section id="bom-alternative-parts">
<h2>BOM &amp; Alternative Parts<a class="headerlink" href="#bom-alternative-parts" title="Link to this heading"></a></h2>
<table class="docutils align-default" id="id2">
<caption><span class="caption-text">BOM</span><a class="headerlink" href="#id2" title="Link to this table"></a></caption>
<thead>
<tr class="row-odd"><th class="head"><p>Ref</p></th>
<th class="head"><p>Quantity</p></th>
<th class="head"><p>Value Component Type</p></th>
<th class="head"><p>Component Name</p></th>
<th class="head"><p>Footprint</p></th>
<th class="head"></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>C1, C2, C5, C6, C14</p></td>
<td><p>5</p></td>
<td><p>10u</p></td>
<td><p>Ceramic Capacitor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-odd"><td><p>C3, C4, C7, C8, C9, C10, C11, C12, C13, C15</p></td>
<td><p>10</p></td>
<td><p>100n</p></td>
<td><p>Ceramic Capacitor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-even"><td><p>C16, C17</p></td>
<td><p>2</p></td>
<td><p>33p</p></td>
<td><p>Ceramic Capacitor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-odd"><td><p>D1</p></td>
<td><p>1</p></td>
<td><p>V<sub>RMS</sub>=40V, I<sub>F</sub>=2A</p></td>
<td><p>Bridge Rectifier</p></td>
<td><p>KMB24F</p></td>
<td><p>MBS (TO-269AA)</p></td>
</tr>
<tr class="row-even"><td><p>Q1, Q2, Q3, Q4, Q5</p></td>
<td><p>5</p></td>
<td><p>V<sub>DS</sub>=60V, I<sub>D</sub>=0.4A</p></td>
<td><p>N-Channel MOSFET</p></td>
<td><p>T2N7002BK</p></td>
<td><p>SOT-23</p></td>
</tr>
<tr class="row-odd"><td><p>R1, R2, R5, R6</p></td>
<td><p>4</p></td>
<td><p>6k8</p></td>
<td><p>Resistor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-even"><td><p>R3</p></td>
<td><p>1</p></td>
<td><p>200</p></td>
<td><p>Resistor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-odd"><td><p>R7, R8, R9</p></td>
<td><p>3</p></td>
<td><p>1k</p></td>
<td><p>Resistor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-even"><td><p>U1</p></td>
<td><p>1</p></td>
<td><p>V<sub>OUT</sub>=3.3V</p></td>
<td><p>Low Dropout Voltage Regulator</p></td>
<td><p>HT7533S</p></td>
<td><p>SOT-23</p></td>
</tr>
<tr class="row-odd"><td><p>U2</p></td>
<td><p>1</p></td>
<td><p>I=2.8A</p></td>
<td><p>H-Bridge Driver</p></td>
<td><p>BDR6133</p></td>
<td><p>SOIC-8</p></td>
</tr>
<tr class="row-even"><td><p>U3</p></td>
<td><p>1</p></td>
<td><p>64Mb</p></td>
<td><p>Flash Memory</p></td>
<td><p>W25Q64JVSSIQ</p></td>
<td><p>SOIC-8</p></td>
</tr>
<tr class="row-odd"><td><p>U4</p></td>
<td><p>1</p></td>
<td><p>/</p></td>
<td><p>Microcontroller</p></td>
<td><p>RP2040</p></td>
<td><p>QFN-56-1EP_7x7mm_P0.4mm</p></td>
</tr>
<tr class="row-even"><td><p>Y1</p></td>
<td><p>1</p></td>
<td><p>f=12MHz</p></td>
<td><p>Crystal Oscillator</p></td>
<td><p>X322512MSB4SI</p></td>
<td><p>Crystal_SMD_3225-4Pin_3.2x2.5mm</p></td>
</tr>
</tbody>
</table>
<p>NOTE: Keep capacitor V<sub>max</sub> in mind!</p>
</section>
<section id="alternatives-for-bdr6133">
<h2>Alternatives for BDR6133:<a class="headerlink" href="#alternatives-for-bdr6133" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT5126A-S-TP_C162093.html">PT5126A-S-TP</a></p></li>
<li><p><a class="reference external" href="https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT2476_C481903.html">PT2476</a></p></li>
</ul>
</section>
<section id="alternative-for-ht7533s">
<h2>Alternative for HT7533S:<a class="headerlink" href="#alternative-for-ht7533s" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://www.lcsc.com/product-detail/Linear-Voltage-Regulators-LDO_Gainsil-GS7533-33TR3_C7427372.html">GS7533-33TR3</a></p></li>
</ul>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="hw.html" class="btn btn-neutral float-left" title="Hardware" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../software/sw.html" class="btn btn-neutral float-right" title="Software" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
@@ -0,0 +1,342 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Hardware Description &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../other/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Hardware Description</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/hardware/hw_description_md.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="hardware-description">
<h1>Hardware Description<a class="headerlink" href="#hardware-description" title="Link to this heading"></a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p><img alt="Block Diagram" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Block_Diagram.svg" /></p>
<p>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.</p>
<ul class="simple">
<li><p>Input Stage</p>
<ul>
<li><p>DCC Signal Level Shift</p></li>
<li><p>Bridge Rectifier &amp; Voltage Regulator</p></li>
</ul>
</li>
<li><p>Motor Driver</p>
<ul>
<li><p>Motor Driver</p></li>
<li><p>Back EMF measurement (ADC)</p></li>
</ul>
</li>
<li><p>General Purpose</p>
<ul>
<li><p>GPIO</p></li>
<li><p>Auxillary output</p></li>
</ul>
</li>
<li><p>Microcontroller</p>
<ul>
<li><p>Flash memory</p></li>
<li><p>Crystal oscillator</p></li>
</ul>
</li>
</ul>
</section>
<section id="characteristics">
<h2>Characteristics<a class="headerlink" href="#characteristics" title="Link to this heading"></a></h2>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Parameter</p></th>
<th class="head"><p>Symbol</p></th>
<th class="head"><p>Minimum</p></th>
<th class="head"><p>Maximum</p></th>
<th class="head"><p>Unit</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>Absolute max. DCC Input Voltage</p></td>
<td><p>V<sub>DCC</sub></p></td>
<td><p>-25</p></td>
<td><p>+25</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-odd"><td><p>Absolute max. GPIO Voltage<sup>(0)</sup></p></td>
<td><p>V<sub>PIN</sub></p></td>
<td><p>-0.5</p></td>
<td><p>3.3+0.5</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-even"><td><p>Input Voltage High<sup>(0)</sup></p></td>
<td><p>V<sub>IH</sub></p></td>
<td><p>2.145</p></td>
<td><p>3.6</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-odd"><td><p>Input Voltage Low<sup>(0)</sup></p></td>
<td><p>V<sub>IL</sub></p></td>
<td><p>0</p></td>
<td><p>1.155</p></td>
<td><p>V</p></td>
</tr>
<tr class="row-even"><td><p>Total GPIO Current<sup>(0)</sup></p></td>
<td><p>I<sub>IOVDD_MAX</sub></p></td>
<td><p></p></td>
<td><p>50</p></td>
<td><p>mA</p></td>
</tr>
<tr class="row-odd"><td><p>Absolute max. motor output current<sup>(1)</sup></p></td>
<td><p>I<sub>MOTOR</sub></p></td>
<td><p></p></td>
<td><p>2.8</p></td>
<td><p>A</p></td>
</tr>
<tr class="row-even"><td><p>Absolute max. auxillary output current<sup>(2)</sup></p></td>
<td><p>I<sub>AUX</sub></p></td>
<td><p></p></td>
<td><p>400</p></td>
<td><p>mA</p></td>
</tr>
</tbody>
</table>
<p>(0): According to: <a class="reference external" href="https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf">RP2040 Datasheet</a> (assuming V<sub>DD</sub> = 3.3V)</p>
<p>(1): According to: <a class="reference external" href="https://datasheet.lcsc.com/lcsc/2101211904_Bardeen-Micro--BDR6133_C2687793.pdf">BDR6133 Datasheet</a></p>
<p>(2): According to: <a class="reference external" href="https://datasheet.lcsc.com/lcsc/1810271831_TOSHIBA-T2N7002BK-LM_C146372.pdf">T2N7002BK Datasheet</a></p>
</section>
<section id="input-stage">
<h2>Input Stage<a class="headerlink" href="#input-stage" title="Link to this heading"></a></h2>
<p><img alt="Input Stage" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Input_Stage.svg" /></p>
<p>D1 Rectifies the DCC square-wave into +V, the amplitude is not critical as long as its within the 25V limit. The rectified voltage +V is then provided to the 3.3V voltage regulator (U1) and to the motor driver (U2).</p>
<p>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</sub> &gt; V<sub>GS,th</sub>), GPIO21 gets pulled to GND potential. R1 and R2 ensure that V<sub>GS</sub> doesnt exceed ±20V.</p>
</section>
<section id="motor-driver">
<h2>Motor Driver<a class="headerlink" href="#motor-driver" title="Link to this heading"></a></h2>
<p><img alt="Motor Driver" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Motor_Driver.svg" /></p>
<p>The Motor Driver is a complete H-Bridge IC specifically made for DC-Motors.</p>
<p>In order to control the motor, it is necessary to measure the back-EMF. This is done by the ADC which measures at Points ADC_EMF_A and ADC_EMF_B respectively. The two resistors are used as a voltage divider.</p>
</section>
<section id="auxillary-output">
<h2>Auxillary Output<a class="headerlink" href="#auxillary-output" title="Link to this heading"></a></h2>
<p><img alt="Auxillary Output" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Aux_Outputs.svg" /></p>
<p>Switching of loads up to a maximum of about ~400mA can be done using four N-Channel MOSFETS. 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.</p>
</section>
<section id="gpio">
<h2>GPIO<a class="headerlink" href="#gpio" title="Link to this heading"></a></h2>
<p>To switch lighter loads six soldering pads on the back side of the PCB are connected to GPIO0 - GPIO5 pins . Although not implemented yet they could theoretically be used as inputs as well (e.g. Reed switch).</p>
</section>
<section id="microcontroller">
<h2>Microcontroller<a class="headerlink" href="#microcontroller" title="Link to this heading"></a></h2>
<p><img alt="Microcontroller" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Microcontroller.svg" /></p>
<p>The Microcontroller needs a crystal oscillator to function properly. External flash memory is also needed as it holds the configuration variables and the program itself. R3 &amp; C14 are used to filter ADC_AVDD (ADC Reference Voltage).</p>
</section>
<section id="complete-schematic">
<h2>Complete Schematic<a class="headerlink" href="#complete-schematic" title="Link to this heading"></a></h2>
<p><img alt="Complete schematic" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/RP2040-Decoder.svg" /></p>
</section>
<section id="bom-alternative-parts">
<h2>BOM &amp; Alternative Parts<a class="headerlink" href="#bom-alternative-parts" title="Link to this heading"></a></h2>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>Ref</p></th>
<th class="head"><p>Quantity</p></th>
<th class="head"><p>Value</p></th>
<th class="head"><p>Component Type</p></th>
<th class="head"><p>Component Name</p></th>
<th class="head"><p>Footprint</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>C1, C2, C5, C6, C14</p></td>
<td><p>5</p></td>
<td><p>10u</p></td>
<td><p>Ceramic Capacitor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-odd"><td><p>C3, C4, C7, C8, C9, C10, C11, C12, C13, C15</p></td>
<td><p>10</p></td>
<td><p>100n</p></td>
<td><p>Ceramic Capacitor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-even"><td><p>C16, C17</p></td>
<td><p>2</p></td>
<td><p>33p</p></td>
<td><p>Ceramic Capacitor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-odd"><td><p>D1</p></td>
<td><p>1</p></td>
<td><p>V<sub>RMS</sub> = 40V , I<sub>F</sub> = 2A</p></td>
<td><p>Bridge Rectifier</p></td>
<td><p>KMB24F</p></td>
<td><p>MBS (TO-269AA)</p></td>
</tr>
<tr class="row-even"><td><p>Q1, Q2, Q3, Q4, Q5</p></td>
<td><p>5</p></td>
<td><p>V<sub>DS</sub> = 60V , I<sub>D</sub> = 0.4A</p></td>
<td><p>N-Channel MOSFET</p></td>
<td><p>T2N7002BK</p></td>
<td><p>SOT-23</p></td>
</tr>
<tr class="row-odd"><td><p>R1, R2, R5, R6</p></td>
<td><p>4</p></td>
<td><p>6k8</p></td>
<td><p>Resistor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-even"><td><p>R3</p></td>
<td><p>1</p></td>
<td><p>200</p></td>
<td><p>Resistor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-odd"><td><p>R7, R8, R9</p></td>
<td><p>3</p></td>
<td><p>1k</p></td>
<td><p>Resistor</p></td>
<td><p>/</p></td>
<td><p>0603_1608Metric</p></td>
</tr>
<tr class="row-even"><td><p>U1</p></td>
<td><p>1</p></td>
<td><p>V<sub>OUT</sub> = 3.3V</p></td>
<td><p>Low Dropout Voltage Regulator</p></td>
<td><p>HT7533S</p></td>
<td><p>SOT-23</p></td>
</tr>
<tr class="row-odd"><td><p>U2</p></td>
<td><p>1</p></td>
<td><p>I = 2.8A</p></td>
<td><p>H-Bridge driver</p></td>
<td><p>BDR6133</p></td>
<td><p>SOIC-8</p></td>
</tr>
<tr class="row-even"><td><p>U3</p></td>
<td><p>1</p></td>
<td><p>64Mb</p></td>
<td><p>Serial Flash Memory</p></td>
<td><p>W25Q64JVSSIQ</p></td>
<td><p>SOIC-8</p></td>
</tr>
<tr class="row-odd"><td><p>U4</p></td>
<td><p>1</p></td>
<td><p>/</p></td>
<td><p>Raspberry Pi RP2040 Microcontroller</p></td>
<td><p>RP2040</p></td>
<td><p>QFN-56-1EP_7x7mm_P0.4mm</p></td>
</tr>
<tr class="row-even"><td><p>Y1</p></td>
<td><p>1</p></td>
<td><p>f = 12MHz</p></td>
<td><p>Crystal Oscillator</p></td>
<td><p>X322512MSB4SI</p></td>
<td><p>Crystal_SMD_3225-4Pin_3.2x2.5mm</p></td>
</tr>
</tbody>
</table>
<p>NOTE: Keep capacitor V<sub>max</sub> in mind!</p>
<p>Alternatives for BDR6133:</p>
<p><a class="reference external" href="https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT5126A-S-TP_C162093.html">PT5126A-S-TP</a></p>
<p><a class="reference external" href="https://lcsc.com/product-detail/Motor-Driver-ICs_PTC-Princeton-Tech-PT2476_C481903.html">PT2476</a></p>
<p>Alternative for HT7533S:</p>
<p><a class="reference external" href="https://www.lcsc.com/product-detail/Linear-Voltage-Regulators-LDO_Gainsil-GS7533-33TR3_C7427372.html">GS7533-33TR3</a></p>
</section>
</section>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+140
View File
@@ -0,0 +1,140 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>RP2040-Decoder Documentation &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=6bd3bce2"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Getting started" href="other/getting_started.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="#" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="other/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware/hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="#">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="#" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">RP2040-Decoder Documentation</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/index.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="rp2040-decoder-documentation">
<h1>RP2040-Decoder Documentation<a class="headerlink" href="#rp2040-decoder-documentation" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="other/getting_started.html">Getting started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="other/getting_started.html#where-to-get-the-board">1. Where to get the board?</a></li>
<li class="toctree-l2"><a class="reference internal" href="other/getting_started.html#production-files">2. Production files?</a></li>
<li class="toctree-l2"><a class="reference internal" href="other/getting_started.html#building-and-flashing">3. Building and flashing</a></li>
<li class="toctree-l2"><a class="reference internal" href="other/getting_started.html#wiring-and-initial-startup">4. Wiring and initial startup</a></li>
<li class="toctree-l2"><a class="reference internal" href="other/getting_started.html#if-it-s-not-working-as-expected">5. If it’s not working as expected</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="hardware/hw.html">Hardware</a><ul>
<li class="toctree-l2"><a class="reference internal" href="hardware/hw_description.html">Hardware Description</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="software/sw.html">Software</a><ul>
<li class="toctree-l2"><a class="reference internal" href="software/sw_description.html">Software Description</a></li>
<li class="toctree-l2"><a class="reference internal" href="software/header_files.html">Header files</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="other/CV_list.html">Configuration Variables (CV)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="other/CV_list.html#note">Note</a></li>
<li class="toctree-l2"><a class="reference internal" href="other/CV_list.html#speed-step-configuration">Speed step configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="other/CV_list.html#cv-list">CV List</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="other/getting_started.html" class="btn btn-neutral float-right" title="Getting started" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
Binary file not shown.
+343
View File
@@ -0,0 +1,343 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Configuration Variables (CV) &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Troubleshooting" href="troubleshooting.html" />
<link rel="prev" title="Header files" href="../software/header_files.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../hardware/hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../software/sw.html">Software</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Configuration Variables (CV)</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#note">Note</a></li>
<li class="toctree-l2"><a class="reference internal" href="#speed-step-configuration">Speed step configuration</a></li>
<li class="toctree-l2"><a class="reference internal" href="#cv-list">CV List</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#cv-1-basic-address">CV_1 - Basic address</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-2-v-min">CV_2 - V_min</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-3-acceleration-rate">CV_3 - Acceleration rate</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-4-deceleration-rate">CV_4 - Deceleration rate</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-5-v-max">CV_5 - V_max</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-6-v-mid">CV_6 - V_mid</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-7-version-no-read-only">CV_7 - Version No. (Read-Only)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-8-manufacturer-read-only">CV_8 - Manufacturer (Read-Only)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-9-motor-pwm-frequency">CV_9 - Motor PWM Frequency</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-11-packet-timeout">CV_11 - Packet timeout</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-12-permitted-operating-modes">CV_12 - Permitted operating modes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-17-cv-18-14-bit-extended-long-address">CV_17 &amp; CV_18 - 14-Bit extended/long address</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-29-decoder-configuration">CV_29 - Decoder Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-31-cv-32-extended-cv-pointer-read-only">CV_31 &amp; CV_32 - Extended CV pointer (Read-Only)</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-47-feed-forward-gain-k-ff">CV_47 - Feed-forward gain k_ff</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-48-filter-time-constant-tau-in-ms">CV_48 - Filter time constant (tau) in ms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-49-pid-control-sampling-time-t-in-ms">CV_49 - PID Control sampling time t in ms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-50-pid-control-i-factor">CV_50 - PID Control I Factor</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-51-pid-control-d-factor">CV_51 - PID Control D Factor</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-52-cv-53-pid-integral-limits">CV_52 &amp; CV_53 - PID Integral Limits</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-54-cv-55-gain-scheduling-config-k-p-x0">CV_54 &amp; CV_55 - Gain scheduling config k_p &#64; x0</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-56-cv-57-gain-scheduling-config-k-p-x1">CV_56 &amp; CV_57 - Gain scheduling config k_p &#64; x1</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-58-cv-59-gain-scheduling-config-k-p-x2">CV_58 &amp; CV_59 - Gain scheduling config k_p &#64; x2</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-60-gain-scheduling-config-x1-shift-percentage">CV_60 - Gain scheduling config x1 shift percentage</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-61-measurement-iterations">CV_61 - Measurement Iterations</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-62-measurement-delay">CV_62 - Measurement Delay</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-63-cv-64-measurement-array-cutoffs">CV_63 &amp; CV_64 - Measurement array cutoffs</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-65-new-flash-variable">CV_65 - New flash variable</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-112-cv-113-cv-114-cv-115-gpio-pwm-configuration">CV_112, CV_113, CV_114, CV_115 - GPIO PWM Configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-116-to-cv-171-pwm-slice-configuration">CV_116 to CV_171 - PWM Slice configuration</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-172-adc-offset">CV_172 - ADC Offset</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-173-adc-offset-measurement-cycles">CV_173 - ADC offset measurement cycles</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-174-additional-motor-pwm-clock-divider">CV_174 - Additional motor-PWM clock divider.</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-175-speed-helper-timer-delay">CV_175 - speed_helper timer delay</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-176-cv-177-cv-178-cv-179-base-pwm-level-used-in-feed-forward-control">CV_176, CV_177, CV_178, CV_179 - Base PWM Level used in feed-forward control</a></li>
<li class="toctree-l3"><a class="reference internal" href="#cv-257-to-cv-512-function-mapping-cvs">CV_257 to CV_512 - Function Mapping CVs</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Configuration Variables (CV)</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/other/CV_list.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="configuration-variables-cv">
<h1>Configuration Variables (CV)<a class="headerlink" href="#configuration-variables-cv" title="Link to this heading"></a></h1>
<section id="note">
<h2>Note<a class="headerlink" href="#note" title="Link to this heading"></a></h2>
<p>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. Alternatively to reset all CVs to default a value of 8 can be written to CV8. Also note that index 0 in the CV array corresponds with CV_1, index 1 corresponds with CV_2 and so forth. This list only contains CVs that are in use.</p>
</section>
<section id="speed-step-configuration">
<h2>Speed step configuration<a class="headerlink" href="#speed-step-configuration" title="Link to this heading"></a></h2>
<p><img alt="Speed Table" src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/speed_table.svg" /></p>
<ul class="simple">
<li><p>V_min = CV_2</p></li>
<li><p>V_mid = CV_6 * 16</p></li>
<li><p>V_max = CV_5 * 16</p></li>
</ul>
<p>The illustration above shows how the speed steps can be configured using the corresponding CVs. The red * represents V_min which is always at speed step 1, the green * shows V_mid at speed step 64 and the blue * shows V_max at speed step 126.</p>
</section>
<section id="cv-list">
<h2>CV List<a class="headerlink" href="#cv-list" title="Link to this heading"></a></h2>
<section id="cv-1-basic-address">
<h3>CV_1 - Basic address<a class="headerlink" href="#cv-1-basic-address" title="Link to this heading"></a></h3>
<p>Short DCC address</p>
</section>
<section id="cv-2-v-min">
<h3>CV_2 - V_min<a class="headerlink" href="#cv-2-v-min" title="Link to this heading"></a></h3>
<p>Min motor voltage/speed</p>
</section>
<section id="cv-3-acceleration-rate">
<h3>CV_3 - Acceleration rate<a class="headerlink" href="#cv-3-acceleration-rate" title="Link to this heading"></a></h3>
<p>CV_3*CV_175 = Time for one discrete speed step change in ms</p>
</section>
<section id="cv-4-deceleration-rate">
<h3>CV_4 - Deceleration rate<a class="headerlink" href="#cv-4-deceleration-rate" title="Link to this heading"></a></h3>
<p>CV_4*CV_175 = Time for one discrete speed step change in ms</p>
</section>
<section id="cv-5-v-max">
<h3>CV_5 - V_max<a class="headerlink" href="#cv-5-v-max" title="Link to this heading"></a></h3>
<p>Max motor voltage/speed - V_max = CV_5 * 16</p>
</section>
<section id="cv-6-v-mid">
<h3>CV_6 - V_mid<a class="headerlink" href="#cv-6-v-mid" title="Link to this heading"></a></h3>
<p>Mid motor voltage/speed - V_max = CV_6 * 16</p>
</section>
<section id="cv-7-version-no-read-only">
<h3>CV_7 - Version No. (Read-Only)<a class="headerlink" href="#cv-7-version-no-read-only" title="Link to this heading"></a></h3>
<p>Rev 0.3 = 1</p>
<p>Writing a value of 7 triggers am ADC offset adjustment.</p>
</section>
<section id="cv-8-manufacturer-read-only">
<h3>CV_8 - Manufacturer (Read-Only)<a class="headerlink" href="#cv-8-manufacturer-read-only" title="Link to this heading"></a></h3>
<p>Default = “13” = Public Domain &amp; Do-It-Yourself Decoders</p>
<p>Writing a value of 8 resets all CV values to the default values in CV.h.
This will also happen if CV_65 == “255” == “0xFF”.</p>
</section>
<section id="cv-9-motor-pwm-frequency">
<h3>CV_9 - Motor PWM Frequency<a class="headerlink" href="#cv-9-motor-pwm-frequency" title="Link to this heading"></a></h3>
<p>f in Hz = CV_9 * 100 + 10000</p>
</section>
<section id="cv-11-packet-timeout">
<h3>CV_11 - Packet timeout<a class="headerlink" href="#cv-11-packet-timeout" title="Link to this heading"></a></h3>
<p>If no package is received for x seconds (x = CV_11) the decoder will automatically stop the motor (Emergency Stop).</p>
</section>
<section id="cv-12-permitted-operating-modes">
<h3>CV_12 - Permitted operating modes<a class="headerlink" href="#cv-12-permitted-operating-modes" title="Link to this heading"></a></h3>
<p>Currently DCC Digital mode is the only supported mode.</p>
</section>
<section id="cv-17-cv-18-14-bit-extended-long-address">
<h3>CV_17 &amp; CV_18 - 14-Bit extended/long address<a class="headerlink" href="#cv-17-cv-18-14-bit-extended-long-address" title="Link to this heading"></a></h3>
<p>Address is only used if bit5 has a value of “1” in CV_29.</p>
<p><img alt="Long Address" src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Long_address.svg" /></p>
<p>Bit15 and bit14 which correspond to bit7 and bit6 of CV_17 are always “1”. CV_17 = “192” &amp; CV_18 = “0” is also not a valid address. Otherwise the valid value range of CV_17 ranges from “192” to “231” and “0” to “255” for CV_18 respectively.</p>
</section>
<section id="cv-29-decoder-configuration">
<h3>CV_29 - Decoder Configuration<a class="headerlink" href="#cv-29-decoder-configuration" title="Link to this heading"></a></h3>
<p>Bit0 is used to reverse 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.</p>
</section>
<section id="cv-31-cv-32-extended-cv-pointer-read-only">
<h3>CV_31 &amp; CV_32 - Extended CV pointer (Read-Only)<a class="headerlink" href="#cv-31-cv-32-extended-cv-pointer-read-only" title="Link to this heading"></a></h3>
<p>Not in use.</p>
</section>
<section id="cv-47-feed-forward-gain-k-ff">
<h3>CV_47 - Feed-forward gain k_ff<a class="headerlink" href="#cv-47-feed-forward-gain-k-ff" title="Link to this heading"></a></h3>
<p>k_ff defines the correction behavior with regard to the y2 variable. High values for k_ff lead to a faster change in the variable. Values for k_ff that are too high can lead to oscillations.
k_ff = CV_47/10000</p>
</section>
<section id="cv-48-filter-time-constant-tau-in-ms">
<h3>CV_48 - Filter time constant (tau) in ms<a class="headerlink" href="#cv-48-filter-time-constant-tau-in-ms" title="Link to this heading"></a></h3>
<p>The time constant tau characterizes the low-pass filter which is connected downstream in the D component of the PID controller</p>
</section>
<section id="cv-49-pid-control-sampling-time-t-in-ms">
<h3>CV_49 - PID Control sampling time t in ms<a class="headerlink" href="#cv-49-pid-control-sampling-time-t-in-ms" title="Link to this heading"></a></h3>
<p>Every t seconds the pid_control() function gets called to compute the new control output</p>
</section>
<section id="cv-50-pid-control-i-factor">
<h3>CV_50 - PID Control I Factor<a class="headerlink" href="#cv-50-pid-control-i-factor" title="Link to this heading"></a></h3>
<p>Integral gain factor of the PID-Controller</p>
</section>
<section id="cv-51-pid-control-d-factor">
<h3>CV_51 - PID Control D Factor<a class="headerlink" href="#cv-51-pid-control-d-factor" title="Link to this heading"></a></h3>
<p>Derivative gain factor of the PID-Controller</p>
</section>
<section id="cv-52-cv-53-pid-integral-limits">
<h3>CV_52 &amp; CV_53 - PID Integral Limits<a class="headerlink" href="#cv-52-cv-53-pid-integral-limits" title="Link to this heading"></a></h3>
<p>Maximum and minimum integral part values</p>
</section>
<section id="cv-54-cv-55-gain-scheduling-config-k-p-x0">
<h3>CV_54 &amp; CV_55 - Gain scheduling config k_p &#64; x0<a class="headerlink" href="#cv-54-cv-55-gain-scheduling-config-k-p-x0" title="Link to this heading"></a></h3>
<p>CV_54 - High Byte – CV_55 - Low Byte</p>
</section>
<section id="cv-56-cv-57-gain-scheduling-config-k-p-x1">
<h3>CV_56 &amp; CV_57 - Gain scheduling config k_p &#64; x1<a class="headerlink" href="#cv-56-cv-57-gain-scheduling-config-k-p-x1" title="Link to this heading"></a></h3>
<p>CV_56 - High Byte – CV_57 - Low Byte</p>
</section>
<section id="cv-58-cv-59-gain-scheduling-config-k-p-x2">
<h3>CV_58 &amp; CV_59 - Gain scheduling config k_p &#64; x2<a class="headerlink" href="#cv-58-cv-59-gain-scheduling-config-k-p-x2" title="Link to this heading"></a></h3>
<p>CV_58 - High Byte – CV_59 - Low Byte</p>
</section>
<section id="cv-60-gain-scheduling-config-x1-shift-percentage">
<h3>CV_60 - Gain scheduling config x1 shift percentage<a class="headerlink" href="#cv-60-gain-scheduling-config-x1-shift-percentage" title="Link to this heading"></a></h3>
<p>Determines position of x1 in percent -&gt; x1 shift in % ≙ CV_60/255</p>
</section>
<section id="cv-61-measurement-iterations">
<h3>CV_61 - Measurement Iterations<a class="headerlink" href="#cv-61-measurement-iterations" title="Link to this heading"></a></h3>
<p>Total amount of BEMF-Voltage measurement iterations</p>
</section>
<section id="cv-62-measurement-delay">
<h3>CV_62 - Measurement Delay<a class="headerlink" href="#cv-62-measurement-delay" title="Link to this heading"></a></h3>
<p>BEMF-Voltage measurement delay</p>
</section>
<section id="cv-63-cv-64-measurement-array-cutoffs">
<h3>CV_63 &amp; CV_64 - Measurement array cutoffs<a class="headerlink" href="#cv-63-cv-64-measurement-array-cutoffs" title="Link to this heading"></a></h3>
<p>CV_63 determines how many elements from the left side (beginning with index 0) of the array will be discarded while CV_64 determines how many elements from the right side (beginning from highest index) will be discarded.</p>
</section>
<section id="cv-65-new-flash-variable">
<h3>CV_65 - New flash variable<a class="headerlink" href="#cv-65-new-flash-variable" title="Link to this heading"></a></h3>
<p>Each Byte of the factory new flash chip should have a inital state of “0xFF”. This will be checked for in the beginning of core0.c (see cv_setup_check()). When CV_65 == “255” == “0xFF” the default config (CV.h) will be written to flash. Alternatively a reset to default can be done by either writing “8” to CV_8 or writing “255” to CV_65 which then triggers a reset on startup.</p>
</section>
<section id="cv-112-cv-113-cv-114-cv-115-gpio-pwm-configuration">
<h3>CV_112, CV_113, CV_114, CV_115 - GPIO PWM Configuration<a class="headerlink" href="#cv-112-cv-113-cv-114-cv-115-gpio-pwm-configuration" title="Link to this heading"></a></h3>
<p>PWM enabled “1” - PWM disabled “0”</p>
</section>
<section id="cv-116-to-cv-171-pwm-slice-configuration">
<h3>CV_116 to CV_171 - PWM Slice configuration<a class="headerlink" href="#cv-116-to-cv-171-pwm-slice-configuration" title="Link to this heading"></a></h3>
<p><img alt="GPIO Slices" src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/GPIO_slices.svg" /></p>
<p>Every slice controls two independent output channels, duty cycle from 0% to 100% inclusive and can be configured with several parameters:</p>
<ul class="simple">
<li><p>Wrap (16Bit): Sets the slice time period of x cycles - effectively determining the frequency</p></li>
<li><p>Clock Divider: Additional clock divider</p></li>
<li><p>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</p></li>
</ul>
<p>To see which CVs correspond to which slice and channel, it is advisable to use CV.h as a reference</p>
<p>The PWM-frequency is calculated as follows: f<sub>PWM</sub> = 125 MHz / [ (CV<sub>clk_div</sub> + 1) * (CV<sub>wrap</sub> + 1) ]</p>
<p>The duty-cycle can be calculated as follows: D = CV<sub>Level</sub> / CV<sub>wrap</sub> + 1</p>
<p><strong>Example configuration - (AUX2: PWM-Frequency f<sub>PWM</sub> = 10kHz; Duty-cycle D = 20%):</strong></p>
<p>AUX1 =&gt; GPIO25 =&gt; Slice 4 / Channel B =&gt; Wrap: CV_144 &amp; CV_145; Clock-divider: CV_146; Level(B): CV_149 &amp; CV_150</p>
<p>=&gt; f<sub>PWM</sub> = 10kHz = 125 MHz / [ (0 + 1) * (12499 + 1) ];</p>
<p>=&gt; CV_144 = 110000, CV_145 = 11010011, CV_146 = 0; — (Note: “12499<sub>dec</sub>” = “11000011010011<sub>bin</sub>”)</p>
<p>=&gt; CV<sub>Level</sub> = CV_149 &amp; CV_150 = D * (CV<sub>wrap</sub> + 1) = 0.2 * 12500 = 2500</p>
<p>=&gt; CV_149 = 1001, CV_150 = 11000100; — (Note: “2500<sub>dec</sub>” = “100111000100<sub>bin</sub>”)</p>
<p>Another configuration which also achieves 10kHz and D = 20% would be CV<sub>clk_div</sub> = 10, CV<sub>wrap</sub> = 1249, CV<sub>Level</sub> = 250.</p>
<p>A more detailed explanation regarding PWM can be found in the <a class="reference external" href="https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf">RP2040-Datasheet - Chapter 4.5</a>.</p>
</section>
<section id="cv-172-adc-offset">
<h3>CV_172 - ADC Offset<a class="headerlink" href="#cv-172-adc-offset" title="Link to this heading"></a></h3>
<p>If CV_172 = “0xFF” = “255” there will be a measurement procedure on startup</p>
</section>
<section id="cv-173-adc-offset-measurement-cycles">
<h3>CV_173 - ADC offset measurement cycles<a class="headerlink" href="#cv-173-adc-offset-measurement-cycles" title="Link to this heading"></a></h3>
<p>Determines how many ADC offset measurement iterations are done.</p>
</section>
<section id="cv-174-additional-motor-pwm-clock-divider">
<h3>CV_174 - Additional motor-PWM clock divider.<a class="headerlink" href="#cv-174-additional-motor-pwm-clock-divider" title="Link to this heading"></a></h3>
<p>Additional Clock Divider - works the same as any GPIO clock divider</p>
</section>
<section id="cv-175-speed-helper-timer-delay">
<h3>CV_175 - speed_helper timer delay<a class="headerlink" href="#cv-175-speed-helper-timer-delay" title="Link to this heading"></a></h3>
<p>This timer delay can be used to change the time between two speed steps. So basically an additional option to adjust the deceleration and acceleration rate.</p>
</section>
<section id="cv-176-cv-177-cv-178-cv-179-base-pwm-level-used-in-feed-forward-control">
<h3>CV_176, CV_177, CV_178, CV_179 - Base PWM Level used in feed-forward control<a class="headerlink" href="#cv-176-cv-177-cv-178-cv-179-base-pwm-level-used-in-feed-forward-control" title="Link to this heading"></a></h3>
<p>CV_176 - High Byte forward – CV_177 - Low Byte forward – CV_178 - High Byte reverse – CV_179 - Low Byte reverse</p>
<p>These values are equivalent to y1(forward) and y1(reverse) mentioned <a class="reference external" href="https://github.com/gab-k/RP2040-Decoder/wiki/Software-description#feed-forward">here</a>. Writing “0” to all four CVs schedules a new calibration on startup.</p>
</section>
<section id="cv-257-to-cv-512-function-mapping-cvs">
<h3>CV_257 to CV_512 - Function Mapping CVs<a class="headerlink" href="#cv-257-to-cv-512-function-mapping-cvs" title="Link to this heading"></a></h3>
<p>The switching status of the outputs depends both on the function instruction received and on the current direction of travel. That means you can, for example, use a function to switch two or more outputs or, as is usual with headlights, switch them depending on the direction of travel. For configuration, 32 bits (corresponding to the GPIOs) are available for each function in each direction of travel.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../software/header_files.html" class="btn btn-neutral float-left" title="Header files" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="troubleshooting.html" class="btn btn-neutral float-right" title="Troubleshooting" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
@@ -0,0 +1,212 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Getting started &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Hardware" href="../hardware/hw.html" />
<link rel="prev" title="RP2040-Decoder Documentation" href="../index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Getting started</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#where-to-get-the-board">1. Where to get the board?</a></li>
<li class="toctree-l2"><a class="reference internal" href="#production-files">2. Production files?</a></li>
<li class="toctree-l2"><a class="reference internal" href="#building-and-flashing">3. Building and flashing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#windows">Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="#other-os">Other OS</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#wiring-and-initial-startup">4. Wiring and initial startup</a></li>
<li class="toctree-l2"><a class="reference internal" href="#if-it-s-not-working-as-expected">5. If it’s not working as expected</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../hardware/hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Getting started</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/other/getting_started.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="getting-started">
<h1>Getting started<a class="headerlink" href="#getting-started" title="Link to this heading"></a></h1>
<p>In order to make use of this project, you will need the following:</p>
<ul class="simple">
<li><p>The RP2040-Decoder board itself</p></li>
<li><p>Raspberry Pi Pico or another multi-drop SWD debug interfaces might work as well</p></li>
<li><p>Micro-USB cable</p></li>
</ul>
<section id="where-to-get-the-board">
<h2>1. Where to get the board?<a class="headerlink" href="#where-to-get-the-board" title="Link to this heading"></a></h2>
<p>You can of course choose any preferred PCB manufacturer, the PCB is designed to be compliant with JLCPCB.com 2 layer board capabilities (hole diameter/clearence/etc.). Regarding assembly, you can of course assemble the board yourself but I would not recommend it (especially the RP2040 QFN Package is not easy to solder). Alternatively you can order the board fully or partly assembled. All parts are normally available at LCSC.com who supply parts to JLCPCB.com.</p>
</section>
<section id="production-files">
<h2>2. Production files?<a class="headerlink" href="#production-files" title="Link to this heading"></a></h2>
<p>In order to generate export the production files (Gerber/BOM/Pick and Place) you need <a class="reference external" href="https://www.kicad.org/download/">KiCad</a> 6 which is open source.
<a class="reference external" href="https://jlcpcb.com/help/article/362-how-to-generate-gerber-and-drill-files-in-kicad-7">How to do this?</a></p>
</section>
<section id="building-and-flashing">
<h2>3. Building and flashing<a class="headerlink" href="#building-and-flashing" title="Link to this heading"></a></h2>
<p>To build the software and run it on the Controller we need to interface the RP2040 using Serial Wire Debug. This can be done using a Raspberry Pi Pico board.</p>
<section id="windows">
<h3>Windows<a class="headerlink" href="#windows" title="Link to this heading"></a></h3>
<ol class="arabic simple">
<li><p>Connect Raspberry Pi Pico via USB while holding the reset button. Your Pi Pico should now be visible in Windows explorer as a mass storage device.</p></li>
<li><p>Download the latest prebuilt “picoprobe.uf2” release binary from <a class="reference external" href="https://github.com/raspberrypi/picoprobe/releases">here</a> or download it from the <a class="reference external" href="https://www.raspberrypi.com/documentation/microcontrollers/raspberry-pi-pico.html#debugging-using-another-raspberry-pi-pico">Raspberry Pi Website</a>.</p></li>
<li><p>Copy “picoprobe.uf2” to your Pi Pico. The Pi Pico onboard LED should now light up.</p></li>
<li><p>Connect GND to GND, GPIO2 to SWCLK, GPIO3 to SWDIO, VBUS to +V, as shown in the picture below .
<img src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Debug_Connections.svg" width="700"/></p></li>
<li><p>Download and install <a class="reference external" href="https://github.com/raspberrypi/pico-setup-windows">Pico setup for Windows</a></p></li>
<li><p>Download and install <a class="reference external" href="https://www.msys2.org/">MSYS2</a></p></li>
<li><p>Open a MSYS2 MINGW64 shell window</p></li>
<li><p>Update all pacman packages</p></li>
</ol>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>pacman<span class="w"> </span>-Syu
</pre></div>
</div>
<ol class="arabic simple" start="9">
<li><p>Install mingw-w64-x86_64-toolchain (choose to install all)</p></li>
</ol>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>pacman<span class="w"> </span>-S<span class="w"> </span>mingw-w64-x86_64-toolchain
</pre></div>
</div>
<ol class="arabic simple" start="10">
<li><p>Add “C:\msys64\mingw64\bin” to your users PATH environment variable. If you have choosen to not use the default directory for MSYS2 add the one you have choosen. <a class="reference external" href="https://www.computerhope.com/issues/ch000549.htm">How to do this?</a></p></li>
<li><p>Open the Pico - Developer Powershell</p></li>
<li><p>Navigate to a folder you like and clone the project repository</p></li>
</ol>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/gab-k/RP2040-Decoder
</pre></div>
</div>
<ol class="arabic simple" start="13">
<li><p>Enter cloned repository, create and enter build directory</p></li>
</ol>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span><span class="w"> </span>RP2040-Decoder
mkdir<span class="w"> </span>build
<span class="nb">cd</span><span class="w"> </span>build
</pre></div>
</div>
<ol class="arabic simple" start="14">
<li><p>Run CMake and the mingw32-make to build</p></li>
</ol>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>-G<span class="w"> </span><span class="s2">&quot;MinGW Makefiles&quot;</span><span class="w"> </span>-DCMAKE_BUILD_TYPE<span class="o">=</span>Debug<span class="w"> </span>..
mingw32
</pre></div>
</div>
<ol class="arabic simple" start="15">
<li><p>Flash the decoders software using openocd</p></li>
</ol>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>openocd<span class="w"> </span>-f<span class="w"> </span>interface/cmsis-dap.cfg<span class="w"> </span>-f<span class="w"> </span>target/rp2040.cfg<span class="w"> </span>-c<span class="w"> </span><span class="s2">&quot;adapter speed 5000&quot;</span><span class="w"> </span>-c<span class="s2">&quot;program rp2040-decoder.elf verify reset exit&quot;</span>
</pre></div>
</div>
</section>
<section id="other-os">
<h3>Other OS<a class="headerlink" href="#other-os" title="Link to this heading"></a></h3>
<p>The first four steps are identical to the steps described above for windows users. Regarding building and flashing, please refer to <a class="reference external" href="https://datasheets.raspberrypi.com/pico/getting-started-with-pico.pdf">Getting started - Pico</a>. Chapter 3 &amp; 5 and Appendix A are the most relevant but you might also refer to chapter 9.1 if you are using macOS.</p>
</section>
</section>
<section id="wiring-and-initial-startup">
<h2>4. Wiring and initial startup<a class="headerlink" href="#wiring-and-initial-startup" title="Link to this heading"></a></h2>
<img src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Wiring_diagram.svg" width="700"/>
<p>The illustration above shows an example wiring configuration, you can connect up to 4 outputs(up to 400mA) and 6 GPIOs for lighter loads or custom applications. A Free-wheeling diode should be used when switching inductive loads!</p>
<p>Another important note is that when the decoder is put into operation for the first time, it automatically performs a motor calibration, which is required for feedforward control. The calibration takes about one to two minutes.</p>
</section>
<section id="if-it-s-not-working-as-expected">
<h2>5. If it’s not working as expected<a class="headerlink" href="#if-it-s-not-working-as-expected" title="Link to this heading"></a></h2>
<ol class="arabic simple">
<li><p>Follow the <a class="reference external" href="https://github.com/gab-k/RP2040-Decoder/wiki/Troubleshooting">Troubleshooting instructions</a></p></li>
<li><p>If you still have trouble create a new <a class="reference external" href="https://github.com/gab-k/RP2040-Decoder/discussions">discussion</a> or <a class="reference external" href="https://github.com/gab-k/RP2040-Decoder/issues">issue</a> and describe your question/issue.</p></li>
</ol>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../index.html" class="btn btn-neutral float-left" title="RP2040-Decoder Documentation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../hardware/hw.html" class="btn btn-neutral float-right" title="Hardware" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
@@ -0,0 +1,126 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Troubleshooting &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="prev" title="Configuration Variables (CV)" href="CV_list.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../hardware/hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Troubleshooting</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/other/troubleshooting.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="troubleshooting">
<h1>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Link to this heading"></a></h1>
<p>To narrow down the issue when your decoder is not working as expected, you can do the following:</p>
<p>Check the power supply of the decoder:</p>
<ul class="simple">
<li><p>+3V3 to GND should be 3.3V</p></li>
<li><p>+V to GND should be somewhere in the range of around +10V to +20V</p></li>
<li><p>If you dont measure the correct voltages, try to <a class="reference external" href="https://dccwiki.com/Measuring_Track_Voltage">measure Track Voltage</a></p></li>
</ul>
<p>Check your motor:</p>
<ul class="simple">
<li><p>Desolder your motor and try the motor with a analog power supply 0…+-16V to check if the motor is working or not (desolder the wires because the decoder doesn’t like voltage on these pins!)</p></li>
</ul>
<p>Reset:</p>
<ul class="simple">
<li><p>Try to reset the decoder by writing a value of 8 to CV8 (beware, this will reset the complete CV memory!)</p></li>
</ul>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="CV_list.html" class="btn btn-neutral float-left" title="Configuration Variables (CV)" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
+124
View File
@@ -0,0 +1,124 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Search &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />
<script src="_static/jquery.js?v=5d32c60e"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=6bd3bce2"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<script src="_static/searchtools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="#" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="#" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="other/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="hardware/hw.html">Hardware</a></li>
<li class="toctree-l1"><a class="reference internal" href="software/sw.html">Software</a></li>
<li class="toctree-l1"><a class="reference internal" href="other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Search</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<noscript>
<div id="fallback" class="admonition warning">
<p class="last">
Please activate JavaScript to enable the search functionality.
</p>
</div>
</noscript>
<div id="search-results">
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
<script>
jQuery(function() { Search.loadIndex("searchindex.js"); });
</script>
<script id="searchindexloader"></script>
</body>
</html>
+1
View File
@@ -0,0 +1 @@
Search.setIndex({"alltitles": {"1. Where to get the board?": [[5, "where-to-get-the-board"]], "2. Production files?": [[5, "production-files"]], "3. Building and flashing": [[5, "building-and-flashing"]], "4. Wiring and initial startup": [[5, "wiring-and-initial-startup"]], "5. If it\u2019s not working as expected": [[5, "if-it-s-not-working-as-expected"]], "Alternative for HT7533S:": [[1, "alternative-for-ht7533s"]], "Alternatives for BDR6133:": [[1, "alternatives-for-bdr6133"]], "Auxiliary Output": [[1, "auxiliary-output"]], "Auxillary Output": [[2, "auxillary-output"]], "BOM": [[1, "id2"]], "BOM & Alternative Parts": [[1, "bom-alternative-parts"], [2, "bom-alternative-parts"]], "Back-EMF voltage measurement": [[9, "back-emf-voltage-measurement"]], "CV List": [[4, "cv-list"]], "CV.h": [[7, "cv-h"]], "CV_1 - Basic address": [[4, "cv-1-basic-address"]], "CV_11 - Packet timeout": [[4, "cv-11-packet-timeout"]], "CV_112, CV_113, CV_114, CV_115 - GPIO PWM Configuration": [[4, "cv-112-cv-113-cv-114-cv-115-gpio-pwm-configuration"]], "CV_116 to CV_171 - PWM Slice configuration": [[4, "cv-116-to-cv-171-pwm-slice-configuration"]], "CV_12 - Permitted operating modes": [[4, "cv-12-permitted-operating-modes"]], "CV_17 & CV_18 - 14-Bit extended/long address": [[4, "cv-17-cv-18-14-bit-extended-long-address"]], "CV_172 - ADC Offset": [[4, "cv-172-adc-offset"]], "CV_173 - ADC offset measurement cycles": [[4, "cv-173-adc-offset-measurement-cycles"]], "CV_174 - Additional motor-PWM clock divider.": [[4, "cv-174-additional-motor-pwm-clock-divider"]], "CV_175 - speed_helper timer delay": [[4, "cv-175-speed-helper-timer-delay"]], "CV_176, CV_177, CV_178, CV_179 - Base PWM Level used in feed-forward control": [[4, "cv-176-cv-177-cv-178-cv-179-base-pwm-level-used-in-feed-forward-control"]], "CV_2 - V_min": [[4, "cv-2-v-min"]], "CV_257 to CV_512 - Function Mapping CVs": [[4, "cv-257-to-cv-512-function-mapping-cvs"]], "CV_29 - Decoder Configuration": [[4, "cv-29-decoder-configuration"]], "CV_3 - Acceleration rate": [[4, "cv-3-acceleration-rate"]], "CV_31 & CV_32 - Extended CV pointer (Read-Only)": [[4, "cv-31-cv-32-extended-cv-pointer-read-only"]], "CV_4 - Deceleration rate": [[4, "cv-4-deceleration-rate"]], "CV_47 - Feed-forward gain k_ff": [[4, "cv-47-feed-forward-gain-k-ff"]], "CV_48 - Filter time constant (tau) in ms": [[4, "cv-48-filter-time-constant-tau-in-ms"]], "CV_49 - PID Control sampling time t in ms": [[4, "cv-49-pid-control-sampling-time-t-in-ms"]], "CV_5 - V_max": [[4, "cv-5-v-max"]], "CV_50 - PID Control I Factor": [[4, "cv-50-pid-control-i-factor"]], "CV_51 - PID Control D Factor": [[4, "cv-51-pid-control-d-factor"]], "CV_52 & CV_53 - PID Integral Limits": [[4, "cv-52-cv-53-pid-integral-limits"]], "CV_54 & CV_55 - Gain scheduling config k_p @ x0": [[4, "cv-54-cv-55-gain-scheduling-config-k-p-x0"]], "CV_56 & CV_57 - Gain scheduling config k_p @ x1": [[4, "cv-56-cv-57-gain-scheduling-config-k-p-x1"]], "CV_58 & CV_59 - Gain scheduling config k_p @ x2": [[4, "cv-58-cv-59-gain-scheduling-config-k-p-x2"]], "CV_6 - V_mid": [[4, "cv-6-v-mid"]], "CV_60 - Gain scheduling config x1 shift percentage": [[4, "cv-60-gain-scheduling-config-x1-shift-percentage"]], "CV_61 - Measurement Iterations": [[4, "cv-61-measurement-iterations"]], "CV_62 - Measurement Delay": [[4, "cv-62-measurement-delay"]], "CV_63 & CV_64 - Measurement array cutoffs": [[4, "cv-63-cv-64-measurement-array-cutoffs"]], "CV_65 - New flash variable": [[4, "cv-65-new-flash-variable"]], "CV_7 - Version No. (Read-Only)": [[4, "cv-7-version-no-read-only"]], "CV_8 - Manufacturer (Read-Only)": [[4, "cv-8-manufacturer-read-only"]], "CV_9 - Motor PWM Frequency": [[4, "cv-9-motor-pwm-frequency"]], "Characteristics": [[1, "characteristics"], [2, "characteristics"]], "Characteristics table": [[1, "id1"]], "Complete Schematic": [[1, "complete-schematic"], [2, "complete-schematic"]], "Configuration Variables (CV)": [[4, null]], "Contents:": [[0, null], [3, null], [8, null]], "DCC signal decoding": [[9, "dcc-signal-decoding"]], "Feed-forward": [[9, "feed-forward"]], "GPIO": [[1, "gpio"], [2, "gpio"]], "Gain scheduling": [[9, "gain-scheduling"]], "Getting started": [[5, null]], "Hardware": [[0, null]], "Hardware Description": [[1, null], [2, null]], "Header files": [[7, null]], "Input Stage": [[1, "input-stage"], [2, "input-stage"]], "Microcontroller": [[1, "microcontroller"], [2, "microcontroller"]], "Motor Driver": [[1, "motor-driver"], [2, "motor-driver"]], "Motor control overview": [[9, "motor-control-overview"]], "Note": [[4, "note"]], "Other OS": [[5, "other-os"]], "Overview": [[1, "overview"], [2, "overview"], [9, "overview"]], "PID Controller": [[9, "pid-controller"]], "RP2040-Decoder Documentation": [[3, null]], "Software": [[8, null]], "Software Description": [[9, null]], "Speed step configuration": [[4, "speed-step-configuration"]], "Troubleshooting": [[6, null]], "Windows": [[5, "windows"]], "core0.h": [[7, "core0-h"]], "core1.h": [[7, "core1-h"]], "shared.h": [[7, "Line truncated
File diff suppressed because it is too large. Load diff
+136
View File
@@ -0,0 +1,136 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Software &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Software Description" href="sw_description.html" />
<link rel="prev" title="Hardware Description" href="../hardware/hw_description.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../other/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../hardware/hw.html">Hardware</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Software</a><ul>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html">Software Description</a></li>
<li class="toctree-l2"><a class="reference internal" href="header_files.html">Header files</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Software</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/software/sw.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="software">
<h1>Software<a class="headerlink" href="#software" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="sw_description.html">Software Description</a><ul>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html#overview">Overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html#motor-control-overview">Motor control overview</a></li>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html#pid-controller">PID Controller</a></li>
<li class="toctree-l2"><a class="reference internal" href="sw_description.html#dcc-signal-decoding">DCC signal decoding</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="header_files.html">Header files</a><ul>
<li class="toctree-l2"><a class="reference internal" href="header_files.html#core0-h">core0.h</a></li>
<li class="toctree-l2"><a class="reference internal" href="header_files.html#core1-h">core1.h</a></li>
<li class="toctree-l2"><a class="reference internal" href="header_files.html#shared-h">shared.h</a></li>
<li class="toctree-l2"><a class="reference internal" href="header_files.html#cv-h">CV.h</a></li>
</ul>
</li>
</ul>
</div>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../hardware/hw_description.html" class="btn btn-neutral float-left" title="Hardware Description" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="sw_description.html" class="btn btn-neutral float-right" title="Software Description" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
@@ -0,0 +1,208 @@
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Software Description &mdash; RP2040-Decoder 0.3, 1.0 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=6bd3bce2"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Header files" href="header_files.html" />
<link rel="prev" title="Software" href="sw.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
RP2040-Decoder
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../other/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../hardware/hw.html">Hardware</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="sw.html">Software</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Software Description</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#overview">Overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#motor-control-overview">Motor control overview</a></li>
<li class="toctree-l3"><a class="reference internal" href="#pid-controller">PID Controller</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#gain-scheduling">Gain scheduling</a></li>
<li class="toctree-l4"><a class="reference internal" href="#feed-forward">Feed-forward</a></li>
<li class="toctree-l4"><a class="reference internal" href="#back-emf-voltage-measurement">Back-EMF voltage measurement</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#dcc-signal-decoding">DCC signal decoding</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="header_files.html">Header files</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../other/CV_list.html">Configuration Variables (CV)</a></li>
<li class="toctree-l1"><a class="reference internal" href="../other/troubleshooting.html">Troubleshooting</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">RP2040-Decoder</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="sw.html">Software</a></li>
<li class="breadcrumb-item active">Software Description</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/software/sw_description.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="software-description">
<h1>Software Description<a class="headerlink" href="#software-description" title="Link to this heading"></a></h1>
<section id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Link to this heading"></a></h2>
<p>The Software is structured as follows:</p>
<ul class="simple">
<li><p>Core0.c</p>
<ul>
<li><p>DCC package detection &amp; decoding</p></li>
<li><p>Programming mode (Modify and read CVs on programming track)</p></li>
<li><p>ADC-Offset measurement</p></li>
<li><p>Feed-forward base PWM measurement</p></li>
</ul>
</li>
<li><p>Core1.c</p>
<ul>
<li><p>PID motor controller</p></li>
</ul>
</li>
<li><p>CV.h</p>
<ul>
<li><p>Default configuration variables</p></li>
</ul>
</li>
</ul>
<p>Conveniently The Raspberry Pi Foundation provides a well documented <a class="reference external" href="https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf">SDK</a> 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.</p>
</section>
<section id="motor-control-overview">
<h2>Motor control overview<a class="headerlink" href="#motor-control-overview" title="Link to this heading"></a></h2>
<p><img alt="Block Diagram" src="https://github.com/1nct/RP2040-Decoder/blob/main/docs/svg/Block_Diagram_Control.svg" /></p>
<hr class="docutils" />
<p><strong>Block diagram - Motor control</strong></p>
<p>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 <a class="reference external" href="https://en.wikipedia.org/wiki/Feed_forward_(control)">Feed-forward</a> that has an impact on the control output variable. The Feed-forward block adds an additional offset to the output depending on the setpoint, this is done to achieve better control. A more detailed explanation regarding Feed-forward can be found below. The speed helper block is corresponding to the speed_helper() function which delays changing the setpoint according to the configured deceleration/acceleration rates.</p>
</section>
<section id="pid-controller">
<h2>PID Controller<a class="headerlink" href="#pid-controller" title="Link to this heading"></a></h2>
<p><img alt="PID Controller" src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/Block_Diagram_PID.svg" /></p>
<p>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.</p>
<p>Output = E * (K<sub>P</sub> + K<sub>I</sub>/s + (K<sub>D</sub>*s)/(sτ+1)) = P + I + D</p>
<ul class="simple">
<li><p>P = E * K<sub>P</sub></p></li>
<li><p>I = E * K<sub>I</sub>/s</p></li>
<li><p>D = E * (K<sub>D</sub>*s)/(sτ+1)</p></li>
</ul>
<p>The continuous-time system representation can now be transformed into a discrete-time representation using <a class="reference external" href="https://en.wikipedia.org/wiki/Bilinear_transform">bilinear transform</a> [ s = 2*(z-1) / T<sub>s</sub>*(z+1) ].</p>
<p>This results in the following difference equations which are then implemented in software:</p>
<ul class="simple">
<li><p>p<sub>n</sub> = K<sub>P</sub> * e<sub>n</sub></p></li>
<li><p>i<sub>n</sub> = 0.5K<sub>I</sub> * (e<sub>n</sub> + e<sub>n-1</sub>) + i<sub>n-1</sub></p></li>
<li><p>d<sub>n</sub> = [ 2K<sub>D</sub> * (e<sub>n</sub> - e<sub>n-1</sub>) + (2τ - T<sub>s</sub>) * d<sub>n-1</sub> ] / [ 2τ + T<sub>s</sub>]</p></li>
</ul>
<p>=&gt; output<sub>n</sub> = p<sub>n</sub> + i<sub>n</sub> + d<sub>n</sub></p>
<p>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.</p>
<section id="gain-scheduling">
<h3>Gain scheduling<a class="headerlink" href="#gain-scheduling" title="Link to this heading"></a></h3>
<p><img alt="K_P" src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/adaptive_kp.svg" /></p>
<p>Another aspect to consider is the implementation of <a class="reference external" href="https://en.wikipedia.org/wiki/Gain_scheduling">gain scheduling</a>. K<sub>P</sub> is a function of the current setpoint. Often it is favorable to have a higher proportional gain K<sub>P</sub> for slow speeds, achieving better control results. The illustration above shows the default setting for K<sub>P</sub>. CV_54 &amp; CV_55 are used to set K<sub>P</sub> &#64; x<sub>0</sub>, CV_56 &amp; CV_57 for K<sub>P</sub> &#64; x<sub>1</sub> and CV_58 &amp; CV_59 for K<sub>P</sub> &#64; x<sub>2</sub>. Additionally CV_60 is used to shift x<sub>1</sub> from the leftmost point (0% = 0/255) to the rightmost point (100% = 255/255).</p>
</section>
<section id="feed-forward">
<h3>Feed-forward<a class="headerlink" href="#feed-forward" title="Link to this heading"></a></h3>
<p><img alt="Feed-forward" src="https://github.com/gab-k/RP2040-Decoder/blob/main/docs/svg/feed_forward.svg" />
To achieve better control <a class="reference external" href="https://en.wikipedia.org/wiki/Feed_forward_(control)">Feed-forward</a> 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</sub>) for both directions. The base pwm level (y<sub>1</sub>) 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</sub> is corrected automatically when i<sub>n</sub> reaches 0.5i<sub>min</sub> or 0.5i<sub>max</sub>. CV_47 can be used to set how sensitive this correction is.</p>
</section>
<section id="back-emf-voltage-measurement">
<h3>Back-EMF voltage measurement<a class="headerlink" href="#back-emf-voltage-measurement" title="Link to this heading"></a></h3>
<p>To provide a feedback signal which is proportional to the motor speed the ADC is used to measure the <a class="reference external" href="https://en.wikipedia.org/wiki/Counter-electromotive_force">Back-EMF voltage</a>. The measurement works by setting the PWM duty cycle to 0%, waiting for a certain delay time (CV_62) and then measuring x times (x = CV_63). While measuring the array with measurement values 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%.</p>
</section>
</section>
<section id="dcc-signal-decoding">
<h2>DCC signal decoding<a class="headerlink" href="#dcc-signal-decoding" title="Link to this heading"></a></h2>
<p>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.</p>
<p>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.</p>
<p>Only a few instructions are currently implemented, only 128 speed step instructions are supported.</p>
<p><strong>Implemented instructions:</strong></p>
<ul class="simple">
<li><p>0011-1111 - (128 Speed Step Control) - 2 Byte length</p></li>
<li><p>10XX-XXXX - (Function Group Instruction) (F0 - F12)</p></li>
<li><p>110X-XXXX - Expansion Instruction (F13 - F31)</p></li>
</ul>
<p>All DCC instructions can be found in Section 9.2, 9.2.1 and 9.2.1.1 of the <a class="reference external" href="https://www.nmra.org/index-nmra-standards-and-recommended-practices">NMRA Communications Standard </a></p>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="sw.html" class="btn btn-neutral float-left" title="Software" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="header_files.html" class="btn btn-neutral float-right" title="Header files" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2024, Gabriel Koppenstein.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>