Merge branch 'main' into chore-addendum

Author: ClemensElflein

README.md

@@ -1,75 +1,124 @@
-# xCore Docs
-
-This is the source code for the xCore Docs.
-
-If you find some issues with the documentation or want to add to it, please fork this repo and open a pull request.
-
-It's a good idea to tell me that you are working on some part of the website. This maximises the chance, that your changes will be merged to the website.
-
-## Running the website locally
-
-Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).
+<p align="center">
+  <a>
+    <h1 align="center">xCore Docs</h1>
+    <img align="center" src="./documents/banner.jpg">
+  </a>
+</p>
+<br>
+<p align="center">
+  This is the source code for the <a href="https://core.x-tech.online/">xCore Docs</a>.
+</p>
+
+<br>
+<hr>
+<br>
+
+<p align="center">
+  If you find some issues with the documentation or want to add to it, please fork this repo and open a pull request.<br>It's a good idea to tell me that you are working on some part of the website. This maximises the chance, that your changes will be merged to the website.
+</p>
+
+<br>
+<hr>
+<br>
+
+<ul>
+<li><a href="#running-local">Running the website locally...</a></li>
+<ul>
+  <li><a href="#running-local-hugo">on Bare Metal</a></li>
+  <li><a href="#running-local-container">on Podman/Docker</a></li>
+  <li><a href="#running-local-docker-compose">on Docker Compose</a></li>
+</ul>
+<br>
+<li><!--<a href="#github-pages">-->Running the website on github pages <i>(To be written)</i><!--</a>--></li>
+<br>
+<li><a href="#troubleshooting">Troubleshooting...</a></li>
+</ul>
+
+<br>
+<hr>
+<br>
+
+<h2 id="running-local">
+  Running the website locally...
+</h2>
+
+<br>
+
+<h3 id="running-local-hugo">
+  Running the website locally on Bare Metal
+</h3>
+
+Building and running the site locally requires a recent `extended` version of [Hugo](https://gohugo.io).  
 You can find out more about how to install Hugo for your environment in our
 [Getting started](https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation) guide.
 
 Once you've made your working copy of the site repo, change to the repo root folder, install the required modules:
 
-```
+```bash
 npm install --no-bin-links
 ```
 
 and finally run:
 
-```
+```bash
 hugo server
 ```
 
-## Running a container locally
+<br>
 
-You can run this inside a [Docker](https://docs.docker.com/)
-container, the container runs with a volume bound to the `docsy-example`
-folder. This approach doesn't require you to install any dependencies other
-than [Docker Desktop](https://www.docker.com/products/docker-desktop) on
-Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/)
-on Linux.
+<h3 id="running-local-container">
+  Running the website locally on Podman/Docker
+</h3>
 
-1. Build the docker image 
+_to be writen..._
 
-   ```bash
-   docker-compose build
-   ```
 
-1. Run the built image
+<br>
 
+<h3 id="running-local-docker-compose">
+  Running the website locally on Docker Compose
+</h3>
+
+You can run this inside a container _([Docker](https://docs.docker.com/) or [Podman](https://podman.io/))_, the container runs with a volume bound to the `docsy-example` folder. This approach doesn't require you to install any dependencies other than [Docker Desktop](https://www.docker.com/products/docker-desktop) on Windows and Mac, and [Docker Compose](https://docs.docker.com/compose/install/) on Linux.
+
+- Build the docker image
    ```bash
-   docker-compose up
+   docker compose build
    ```
 
-   > NOTE: You can run both commands at once with `docker-compose up --build`.
+- Run the built image
+   ```bash
+   docker compose up
+   ```
+> [!TIP]
+> You can run both commands at once with `docker compose up --build`.
 
-1. Verify that the service is working. 
+- Verify that the service is working.
 
    Open your web browser and type `http://localhost:1313` in your navigation bar,
-   This opens a local instance of the homepage. You can now make
+   This opens a local instance of the this homepage. You can now make
    changes to the website and those changes will immediately show up in your
    browser after you save (not on Windows though. Hot reload only works on the non-dockerized hugo!).
 
 ### Cleanup
 
-To stop Docker Compose, on your terminal window, press **Ctrl + C**. 
+To stop Docker Compose, on your terminal window, press <kbd>Ctrl</kbd>+<kbd>C</kbd>.
 
 To remove the produced images run:
-
-```console
-docker-compose rm
+```bash
+docker compose rm
 ```
-For more information see the [Docker Compose
-documentation](https://docs.docker.com/compose/gettingstarted/).
+For more information see the [Docker Compose documentation](https://docs.docker.com/compose/gettingstarted/).
 
-## Troubleshooting
+<br>
+<hr>
+<br>
 
-As you run the website locally, you may run into the following error:
+<h2 id="troubleshooting">
+  Troubleshooting
+</h2>
 
+As you run the website locally, you may run into the following error:
 ```
 ➜ hugo server
 
@@ -83,7 +132,6 @@ This error occurs if you have not installed the extended version of Hugo.
 See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
 
 Or you may encounter the following error:
-
 ```
 ➜ hugo server
 
@@ -92,4 +140,3 @@ Error: failed to download modules: binary with name "go" not found
 
 This error occurs if you have not installed the `go` programming language on your system.
 See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
-

content/en/docs/Tutorials/flashing-stm32-from-cm4/_index.md

@@ -10,7 +10,7 @@ the CM4's GPIOs to connect to the STM32's SWD interface.
 ### Step 1: Building OpenOCD
 Execute the following commands in order to install the dependencies, build and install OpenOCD:
 ```bash
-sudo apt install automake autoconf build-essential libtool libftdi-dev libusb-1.0-0-dev texinfo pkg-config rpi.gpio-common curl
+sudo apt install autoconf automake build-essential curl libftdi-dev libtool libusb-1.0-0-dev git pkg-config rpi.gpio-common texinfo
 git clone https://github.com/raspberrypi/openocd.git --recursive
 cd openocd
 ./bootstrap
@@ -32,3 +32,12 @@ cd ~
 openocd -f interface/xcore.cfg -f target/stm32h7x.cfg -c "program openmower.elf verify reset exit"
 ```
 The firmware should be uploaded and the program should be running.
+
+
+### Debugging via remote GDB
+In order to debug the program on your xCore board, run the following command:
+```bash
+openocd -f interface/xcore.cfg -f target/stm32h7x.cfg -c "bindto 0.0.0.0"
+```
+
+Then connect your favorite IDE to port 3333 to upload and debug using GDB

content/en/docs/interfaces/_index.md

@@ -57,7 +57,7 @@ In addition to the interfaces available via the SODIMM connector, the xCore boar
 - **CSI (Camera Serial Interface)**: Direct connection for a camera module using the CSI interface.
 - **DSI (Display Serial Interface)**: Direct connection for a display using the DSI interface.
 - **SD Card Interface (for CM4 Lite)**: Provides SD card storage access for Raspberry Pi CM4 Lite models.
-- **Fan Connector**: Allows you to connect a cooling fan to manage thermal performance for the CM4.
+- **Fan Connector**: Allows you to connect a cooling fan to manage thermal performance for the CM4 _(It is the same connector as the [Pi 5](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#raspberry-pi-5-fan-connector-pinout) and controllable by GPIO6)._
 
 These additional interfaces enable the xCore platform to fully leverage the capabilities of the Raspberry Pi CM4, offering high-speed data transfer, camera and display connectivity.