Update documentation system with doxygen/breathe/sphinx

This commit is contained in:
gab-k committed 2024-11-27 11:33:22 +01:00
1 parent fad8b68e01
commit 72bd29ddbc
9 files changed
+231 -2896

No files matched your search

+4 -2
View File
@@ -3,8 +3,10 @@
.idea
# Doxygen generated files
html
latex
docs/doxygen/build
# Sphinx generated files
docs/sphinx/build
# Build folders
build
-2894
View File
File diff suppressed because it is too large. Load diff
+15
View File
@@ -0,0 +1,15 @@
OUTPUT_DIRECTORY = ./build
GENERATE_XML = YES # Needed for Breathe
GENERATE_HTML = NO # Optional: if you don’t need standalone Doxygen HTML output
GENERATE_LATEX = NO
INPUT = ../../ # Path to your source code
FILE_PATTERNS = *.h \
*.c \
RECURSIVE = YES # Include subdirectories
OPTIMIZE_OUTPUT_FOR_C = YES # Optimize output for C
EXTRACT_ALL = NO # Extract documentation even for undocumented items (optional)
EXTRACT_PRIVATE = NO # Include private members if needed
EXTRACT_STATIC = YES
ENABLE_PREPROCESSING = YES
PREDEFINED = extern=//
EXPAND_AS_DEFINED = extern
+20
View File
@@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+35
View File
@@ -0,0 +1,35 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
+34
View File
@@ -0,0 +1,34 @@
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'RP2040-Decoder'
copyright = '2024, Gabriel Koppenstein'
author = 'Gabriel Koppenstein'
release = '0.3, 1.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = ['myst_parser', 'breathe',]
templates_path = ['_templates']
exclude_patterns = []
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = "sphinx_rtd_theme"
html_static_path = ['_static']
# Breathe Configuration
breathe_projects = {
"RP2040-Decoder": "../../doxygen/build/xml"
}
breathe_default_project = "RP2040-Decoder"
@@ -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.
+19
View File
@@ -0,0 +1,19 @@
.. 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
============================
Add your content using ``reStructuredText`` syntax. See the
`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
documentation for details.
.. toctree::
:maxdepth: 2
:caption: Contents:
getting_started/getting_started
software/header_files
@@ -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