DotBots · aabadie · Nov 22, 2023 · Nov 17, 2023 · Nov 17, 2023 · Nov 21, 2023
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -54,6 +54,8 @@ jobs:
         uses: actions/checkout@v2
       - name: Install Doxygen
         run: sudo apt-get install -y doxygen graphviz
+      - name: Install Sphinx
+        run: python -m pip install -r doc/sphinx/requirements.txt
       - name: Build documentation
         run: make doc
 

diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all list-projects clean doc
+.PHONY: all list-projects clean
 
 DOCKER_IMAGE ?= aabadie/dotbot:latest
 DOCKER_TARGETS ?= all
@@ -145,5 +145,10 @@ docker:
 		-v $(PWD):/dotbot $(DOCKER_IMAGE) \
 		make $(DOCKER_TARGETS)
 
+.PHONY: doc docclean
+docclean:
+	make -C doc/doxygen clean --no-print-directory
+	make -C doc/sphinx clean --no-print-directory
+
 doc:
-	@make -C doc/doxygen
+	make -C doc/sphinx linkcheck html --no-print-directory SPHINXOPTS="-W --keep-going -n"
diff --git a/README.md b/README.md
@@ -1,85 +1,38 @@
 # DotBot: easy-to-use micro-robot for education and research purposes
-
 
-<p align="center">
-  <img src="static/03app_dotbot.gif" alt="dotbot app demo"/>
-</p>
-
-This repository contains the source code for the DotBot's firmware.
-
-Loading this app onto the DotBot board will make the motors of the DotBot remote controllable by a nRF52840-DK with the [gateway-firmware](https://github.com/DotBots/Gateway-firmware/releases) firmware, as it can be seen in the above video.
-
-
-## Getting Started
-
-The following instructions will guide through running the default remote control example in your DotBot board.
-
-### Materials
-
-- 1x DotBot board
-- 1x nRF52840-DK development board
-- 1x 10pin IDC programming cable
-- 1x micro USB able
-
-
-### Download the firmware onto the boards
-
-
-1. Download the latest releases (the .hex files) of the DotBot-firmware and of the Gateway firmware from
-[here](https://github.com/DotBots/DotBot-firmware/releases)
-
-You should end up with 2 files named `03app_dotbot.hex` and `03app_dotbot_gateway.hex`.
+## Overview
 
-2. Connect the nRF52840-DK to your computer through the micro USB cable
+This repository contains the source code for firmwares usable with the DotBot
+hardware.
 
 <p align="center">
-  <img src="static/nRF-DK_connected.jpg" width="40%" height="40%" alt="nRF DK connected to a computer with a micro USB cable"/>
+  <img src="https://github.com/DotBots/DotBot-firmware/blob/main/static/03app_dotbot.gif?raw=true" alt="dotbot app demo"/>
 </p>
-
-  - A USB drive called  __JLINK__ should appear on your computer. 
 
-<p align="center">
-  <img src="static/JLINK_folder.png" width="60%" height="60%" alt="JLINK drive folder"/>
-</p>
-
-3. Drag-&-Drop the Gateway firmware executable `03app_dotbot_gateway.hex` into the JLINK folder to program the development board.
-
-4. Connect the nRF52840-DK to the DotBot through the 10 pin IDC cable.
-  - Make sure the DotBot is turned ON and has full batteries installed.
-
-<p align="center">
-  <img src="static/dotbot_and_dk_connected.jpg" width="40%" height="40%" alt="DotBot connected to the nrF-DK through the 10pin IDC cable."/>
-</p>
+## Related projects
 
-5. Drag-&-Drop the DotBot firmware executable `03app_dotbot.hex` into the JLINK folder to program the DotBot.
+The DotBots ecosystem provides Python
+[PyDotBot](https://github.com/DotBots/PyDotBot) to interacts with a nRF DK board
+used a gateway.
 
-6. Disconnect the DotBot from the nRF53840-DK
+The DotBots hardware design are published on GitHub at
+[https://github.com/DotBots/DotBot-harware](https://github.com/DotBots/DotBot-hardware).
 
+## Building firmwares
 
-### Controlling the DotBot
-
-<p align="center">
-  <img src="static/03app_dotbot.gif" alt="dotbot app demo"/>
-</p>
-
-
-At this point you should be able to control the movement of the DotBot using the buttons on the nRF52840-DK, the controls are as follows:
-- __Button 1__: Left wheel moves forward
-- __Button 2__: Right wheel moves forward
-- __Button 3__: Left wheel moves backward
-- __Button 4__: Right wheel moves backward
+The source code of the different applications available in this repository can be built using
+[SEGGER Embedded Studio for ARM](https://www.segger.com/downloads/embedded-studio).
+In SEGGER embedded studio, use the package manager
+(available in menu Tools > Package manager) to install the CMSIS 5 CMSIS-CORE,
+CMSIS-DSP and nRF packages.
 
-You can combine buttons 1 & 2 to move the DotBot straight forward, buttons 3 & 4 to move the DotBot backward, etc.
+For details on SEGGER Embedded Studio, read the
+[online documentation](https://studio.segger.com/index.htm?https://studio.segger.com/home.htm).
 
-## Accessing the source code
+## Flashing firmwares
 
-The source code of the remote control example of the DotBot can be found in
-[projects/03app_dotbot/03app_dotbot.c](projects/03app_dotbot/03app_dotbot.c).
-The source code of the gateway application can be found in
-[projects/03app_dotbot/03app_dotbot_gateway.c](projects/03app_dotbot/03app_dotbot_gateway.c).
+All DotBots and DKs are based on Nordic Semiconductors microcontrollers, so
+we recommend that you use Nordic programming tools to flash firmwares:
 
-The different applications in this repository can be built using
-[SEGGER embedded studio for ARM](https://www.segger.com/downloads/embedded-studio).
-In SEGGER embedded studio, use the package manager
-(available in menu Tools > Package manager) to install the CMSIS 5 CMSIS-CORE
-, CMSIS-DSP and nRF packages.
+- [nRF Command Line Tools](https://infocenter.nordicsemi.com/topic/ug_nrf_cltools/UG/cltools/nrf_command_line_tools_lpage.html)
+- [nRF Connect Programmer](https://infocenter.nordicsemi.com/topic/ug_nc_programmer/UG/nrf_connect_programmer/ncp_introduction.html)
diff --git a/doc/doxygen/Doxyfile b/doc/doxygen/Doxyfile
@@ -177,7 +177,7 @@ IGNORE_PREFIX          =
 #---------------------------------------------------------------------------
 # Configuration options related to the HTML output
 #---------------------------------------------------------------------------
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 HTML_OUTPUT            = html
 HTML_FILE_EXTENSION    = .html
 HTML_HEADER            =

diff --git a/doc/doxygen/Makefile b/doc/doxygen/Makefile
@@ -1,8 +1,6 @@
 .PHONY: all clean
 
 all:
-	@mkdir -p html/static
-	@cp -R ../../static/* html/static/.
 	@doxygen
 
 clean:

diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore
@@ -0,0 +1 @@
+build/
diff --git a/doc/sphinx/Makefile b/doc/sphinx/Makefile
@@ -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)
diff --git a/doc/sphinx/make.bat b/doc/sphinx/make.bat
@@ -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
diff --git a/doc/sphinx/requirements.txt b/doc/sphinx/requirements.txt
@@ -0,0 +1,4 @@
+breathe==4.35.0
+myst-parser==2.0.0
+pydata-sphinx-theme==0.14.3
+sphinx==7.2.6
diff --git a/doc/sphinx/source/_static/.emtpy b/doc/sphinx/source/_static/.emtpy
diff --git a/doc/sphinx/source/api.rst b/doc/sphinx/source/api.rst
@@ -0,0 +1,19 @@
+API
+===
+
+This section contains the API documentation for the various modules of the DotBot firmware.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Contents:
+
+   bsp
+   drv
+   crypto
+
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`search`
diff --git a/doc/sphinx/source/applications.rst b/doc/sphinx/source/applications.rst
@@ -0,0 +1,14 @@
+Main applications
+=================
+
+.. doxygengroup:: projects
+
+.. toctree::
+   :maxdepth: 1
+
+   projects/03app_dotbot
+   projects/03app_dotbot_gateway
+   projects/03app_sailbot
+   projects/03app_log_dump
+   projects/03app_nrf5340_app
+   projects/03app_nrf5340_net
diff --git a/doc/sphinx/source/bsp.rst b/doc/sphinx/source/bsp.rst
@@ -0,0 +1,28 @@
+Drivers
+=======
+
+.. doxygengroup:: bsp
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   bsp/board
+   bsp/clock
+   bsp/device
+   bsp/gpio
+   bsp/i2c
+   bsp/ipc
+   bsp/lh2
+   bsp/motors
+   bsp/nvmc
+   bsp/partition
+   bsp/pwm
+   bsp/qdec
+   bsp/radio
+   bsp/rgbled
+   bsp/rng
+   bsp/rpm
+   bsp/timer
+   bsp/timer_hf
+   bsp/uart
diff --git a/doc/sphinx/source/bsp/board.rst b/doc/sphinx/source/bsp/board.rst
@@ -0,0 +1,8 @@
+Board support
+=============
+
+.. doxygengroup:: bsp_board
+.. doxygenfile:: bsp/board.h
+
+.. .. doxygengroup:: bsp_board_config
+.. .. doxygenfile:: bsp/board_config.h
diff --git a/doc/sphinx/source/bsp/clock.rst b/doc/sphinx/source/bsp/clock.rst
@@ -0,0 +1,5 @@
+Clocks initialization
+=====================
+
+.. doxygengroup:: bsp_clock
+.. doxygenfile:: bsp/clock.h
diff --git a/doc/sphinx/source/bsp/device.rst b/doc/sphinx/source/bsp/device.rst
@@ -0,0 +1,5 @@
+Device information
+==================
+
+.. doxygengroup:: bsp_device
+.. doxygenfile:: bsp/device.h
diff --git a/doc/sphinx/source/bsp/gpio.rst b/doc/sphinx/source/bsp/gpio.rst
@@ -0,0 +1,5 @@
+GPIO driver
+===========
+
+.. doxygengroup:: bsp_gpio
+.. doxygenfile:: bsp/gpio.h
diff --git a/doc/sphinx/source/bsp/i2c.rst b/doc/sphinx/source/bsp/i2c.rst
@@ -0,0 +1,5 @@
+I2C driver
+==========
+
+.. doxygengroup:: bsp_i2c
+.. doxygenfile:: bsp/i2c.h
diff --git a/doc/sphinx/source/bsp/ipc.rst b/doc/sphinx/source/bsp/ipc.rst
@@ -0,0 +1,5 @@
+Inter-Process Communication support
+===================================
+
+.. doxygengroup:: bsp_ipc
+.. doxygenfile:: bsp/ipc.h
diff --git a/doc/sphinx/source/bsp/lh2.rst b/doc/sphinx/source/bsp/lh2.rst
@@ -0,0 +1,5 @@
+Lighthouse 2 driver
+===================
+
+.. doxygengroup:: bsp_lh2
+.. doxygenfile:: bsp/lh2.h
diff --git a/doc/sphinx/source/bsp/motors.rst b/doc/sphinx/source/bsp/motors.rst
@@ -0,0 +1,5 @@
+Motors driver
+=============
+
+.. doxygengroup:: bsp_motors
+.. doxygenfile:: bsp/motors.h
diff --git a/doc/sphinx/source/bsp/nvmc.rst b/doc/sphinx/source/bsp/nvmc.rst
@@ -0,0 +1,5 @@
+Non-Volatile Memory Controller Driver
+=====================================
+
+.. doxygengroup:: bsp_nvmc
+.. doxygenfile:: bsp/nvmc.h
diff --git a/doc/sphinx/source/bsp/partition.rst b/doc/sphinx/source/bsp/partition.rst
@@ -0,0 +1,5 @@
+Partition table management
+==========================
+
+.. doxygengroup:: bsp_partition
+.. doxygenfile:: bsp/partition.h
diff --git a/doc/sphinx/source/bsp/pwm.rst b/doc/sphinx/source/bsp/pwm.rst
@@ -0,0 +1,5 @@
+PWM driver
+==========
+
+.. doxygengroup:: bsp_pwm
+.. doxygenfile:: bsp/pwm.h
diff --git a/doc/sphinx/source/bsp/qdec.rst b/doc/sphinx/source/bsp/qdec.rst
@@ -0,0 +1,5 @@
+QDEC driver
+===========
+
+.. doxygengroup:: bsp_qdec
+.. doxygenfile:: bsp/qdec.h
diff --git a/doc/sphinx/source/bsp/radio.rst b/doc/sphinx/source/bsp/radio.rst
@@ -0,0 +1,5 @@
+Radio driver
+============
+
+.. doxygengroup:: bsp_radio
+.. doxygenfile:: bsp/radio.h
diff --git a/doc/sphinx/source/bsp/rgbled.rst b/doc/sphinx/source/bsp/rgbled.rst
@@ -0,0 +1,5 @@
+RGB LED driver
+==============
+
+.. doxygengroup:: bsp_rgbled
+.. doxygenfile:: bsp/rgbled.h
diff --git a/doc/sphinx/source/bsp/rng.rst b/doc/sphinx/source/bsp/rng.rst
@@ -0,0 +1,5 @@
+RNG driver
+==========
+
+.. doxygengroup:: bsp_rng
+.. doxygenfile:: bsp/rng.h
diff --git a/doc/sphinx/source/bsp/rpm.rst b/doc/sphinx/source/bsp/rpm.rst
@@ -0,0 +1,5 @@
+RPM driver
+==========
+
+.. doxygengroup:: bsp_rpm
+.. doxygenfile:: bsp/rpm.h
diff --git a/doc/sphinx/source/bsp/timer.rst b/doc/sphinx/source/bsp/timer.rst
@@ -0,0 +1,5 @@
+Low-Frequency Timer management
+==============================
+
+.. doxygengroup:: bsp_timer
+.. doxygenfile:: bsp/timer.h
diff --git a/doc/sphinx/source/bsp/timer_hf.rst b/doc/sphinx/source/bsp/timer_hf.rst
@@ -0,0 +1,5 @@
+High-Frequency Timer management
+===============================
+
+.. doxygengroup:: bsp_timer_hf
+.. doxygenfile:: bsp/timer_hf.h
diff --git a/doc/sphinx/source/bsp/uart.rst b/doc/sphinx/source/bsp/uart.rst
@@ -0,0 +1,5 @@
+UART driver
+===========
+
+.. doxygengroup:: bsp_uart
+.. doxygenfile:: bsp/uart.h