diff --git a/.copier/answers.docs.yml b/.copier/answers.docs.yml new file mode 100644 index 0000000..d1c3d88 --- /dev/null +++ b/.copier/answers.docs.yml @@ -0,0 +1,5 @@ +# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY +_commit: v1.0.2 +_src_path: https://git.spirirobotics.com/Spiri/template-docs.git +author_name: Spiri Robotics +project_name: spiri-sdk diff --git a/.github/workflows/build-docs.yaml b/.github/workflows/build-docs.yaml new file mode 100644 index 0000000..7985db5 --- /dev/null +++ b/.github/workflows/build-docs.yaml @@ -0,0 +1,44 @@ +name: Build Docs + +on: + push: + +env: + REGISTRY: git.spirirobotics.com + IMAGE_NAME: ${{ github.repository }} + +jobs: + build: + runs-on: ubuntu-latest + container: sphinxdoc/sphinx-latexpdf + + steps: + - name: Install sphinx-rtd-theme + run: pip install sphinx-rtd-theme + - name: Install node so that custom actions work. + run : apt-get update && apt-get --yes install nodejs git + + - name: Checkout Repository + uses: actions/checkout@v4 + + - name: Build Docs + run: make html latexpdf + working-directory: docs # assuming your documentation is in a 'docs' folder + + - name: Save PDF Artifacts + run: mv docs/build/latex/*.pdf ${{ github.workspace }}/docs.pdf + + - name: Compress HTML + run: tar -czvf docs_html.tar.gz -C docs/build/html . + + - name: Upload Docs + uses: actions/upload-artifact@v3 + with: + name: docs_html.tar.gz + path: docs_html.tar.gz + + - name: Upload PDF + uses: actions/upload-artifact@v3 + with: + name: docs.pdf + path: docs.pdf diff --git a/README.md b/README.md index 53d5858..5fda9a0 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,10 @@ -# Spiri SDK - Simulated robot - -The Spiri SDK consists of a number of components. What you're looking at right now -is the drone simulation component, which is the core of the SDK. +# Spiri SDK Spiri Robots run a number of docker containers to achieve their core functionality, we try to keep these essential docker containers in one docker compose file. The docker compose file you'll find in this repository starts an ardupilot-based UAV simulation -as well as a ROS master, and mavproxy to tie it together. +as well as a ROS master, and mavproxy to tie it together, mirroring the core deployment of +a spiri robot. To get started you can simply clone this repository and run `docker compose --profile uav-sim up`. @@ -15,6 +13,35 @@ MavLink compatible software. We expose the UAVs Mavlink conenction on tcp port 5 There is experimental GUI support you can enable by running `docker compose --profile uav-sim --profile ui up`. + +## Prerequisites + +The Spiri-SDK is intended for use on linux. +It was tested with docker engine `20.10.24` and NVIDIA Container Toolkit CLI version `1.16.2`. + +UI features like virtual camera support were tested with Nvidia GPUs using CDI passthrough, but could +work with other GPUs as long as they support CDI. + +Machine-learning features like image recognition are expected to only work with NVIDIA GPUs. + +### Installing Docker + +There are many ways to install docker for your platform. We recomend using your linux distribution's package +manager to install docker, using a command like `sudo apt-get install docker-compose-v2`. The exact command +will vary depending on your exact linux distribution. + +You can see the [official docker documentation](https://docs.docker.com/engine/install/) for more details. + +### Installing nvidia-container-toolkit + + +We recomend following the [offical guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) to install the nvidia-container-toolkit. + +Make sure you run `sudo nvidia-ctk runtime configure --runtime=docker` and `sudo systemctl restart docker`. + +When installed correctly you should see your gpu available in `nvidia-ctk cdi list`. + + ## Creating a new project We provide project templates you can use for development that integrate seamlessly into diff --git a/docker-compose.yml b/docker-compose.yml index cabba4d..cb765d2 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -21,13 +21,12 @@ services: # Wayland socket - ${XDG_RUNTIME_DIR}/wayland-0:${XDG_RUNTIME_DIR}/wayland-0 # Allow access to the host's GPU - - /dev/dri:/dev/dri - devices: - # Provide access to GPU devices - - /dev/dri:/dev/dri + # - /dev/dri:/dev/dri + # devices: + # # Provide access to GPU devices + # - /dev/dri:/dev/dri # network_mode: host ipc: host - #user: "${UID}:${GID}" privileged: true # Allow privileged access if necessary (e.g., for GPU access) # restart: unless-stopped # command: /bin/bash -c "source /opt/ros/foxy/setup.bash && rvis2" # Replace with the actual command to run Gazebo Ignition @@ -40,7 +39,6 @@ services: device_ids: - nvidia.com/gpu=all - ardupilot: image: git.spirirobotics.com/spiri/ardupilot:spiri-master command: > diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/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/docs/README.md b/docs/README.md new file mode 100644 index 0000000..44b6013 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,11 @@ +If you have a correctly configured sphinx environment you can build this project +using `make html latexpdf`. + +You can also use nektos/act to build this project in the same way our build does. +```bash +cd ../ #Make sure you're in the project root, you should have a hidden folder +# named ./.github/workflows available. +act --artifact-server-path ./doc-build +``` + +Your compiled doc project will now be in the ./doc-build folder. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/docs/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/docs/source/_static/custom.css b/docs/source/_static/custom.css new file mode 100644 index 0000000..cdc1a92 --- /dev/null +++ b/docs/source/_static/custom.css @@ -0,0 +1,34 @@ +.wy-side-nav-search { + background: #FFFFFF !important; +} + + +.wy-nav-side { + background-color: #FFFFFF !important; +} + + +/* Add borders and box-shadow */ +.wy-side-nav { + border: 1px solid #899CA3 !important; +} + +.logo { + width: 100px !important; +} + +.wy-menu-vertical a { + color: #899CA3 !important; /* Change to your desired color */ +} + +.document-title { + color: #000 !important; + font-size: 24px !important; + text-transform: uppercase !important; +} + +.icon-home { + font-weight: bold !important; + text-transform: uppercase !important; + color: #000 !important; +} diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d5b77c9 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,65 @@ +# 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 +import sphinx_rtd_theme + +project = "spiri-sdk" +copyright = "2024, Spiri Robotics" +author = "Spiri Robotics" + +html_logo = "logos/SPIRI_STLockup_Mixed_RGB.png" # For HTML output +html_logo_width = '200px' +latex_logo = "logos/SPIRI_STLockup_Mixed_RGB.png" +latex_logo_width = '5cm' + + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", +] + + +numfig = True + +todo_include_todos = True +todo_emit_warnings = True +todo_link_only = True + + +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_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +html_static_path = ['_static'] + +html_css_files = [ + 'custom.css', +] + + +html_theme_options = { + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, #could be set to -1 if we want unlimited depth + 'includehidden': True, + 'titles_only': False +} + +latex_engine = "xelatex" +# Configure LaTeX options for PDF generation diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..e564e24 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +.. spiri-sdk documentation master file, created by + sphinx-quickstart on Wed Feb 14 11:51:45 2024. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to spiri-sdk's documentation! +============================================ + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/source/logos/SPIRI_STLockup_Mixed_RGB.png b/docs/source/logos/SPIRI_STLockup_Mixed_RGB.png new file mode 100644 index 0000000..e1a4800 Binary files /dev/null and b/docs/source/logos/SPIRI_STLockup_Mixed_RGB.png differ diff --git a/guiTools/Dockerfile b/guiTools/Dockerfile index f8ed848..3faf9ec 100644 --- a/guiTools/Dockerfile +++ b/guiTools/Dockerfile @@ -1,10 +1,8 @@ FROM osrf/ros:jazzy-desktop-full RUN apt-get update -RUN apt-get install qterminal -y +RUN apt-get install qterminal mesa-utils -y COPY ./launcher.py /launcher.py CMD python3 /launcher.py - - diff --git a/guiTools/launcher.py b/guiTools/launcher.py index 109c078..94b469f 100644 --- a/guiTools/launcher.py +++ b/guiTools/launcher.py @@ -3,11 +3,12 @@ import subprocess # Dictionary of applications: key is the button text, value is the command to execute applications = { - "Launch Terminal": ['qterminal'], - "Launch rqt": ["rqt"], - "Launch rviz2": ["rviz2"], - "Launch Gazebo": "gz sim -v4 -g".split(), - "Launch Gazebo Standalone": "gz sim -v4".split(), + "Terminal": ['qterminal'], + "rqt": ["rqt"], + "rviz2": ["rviz2"], + "Gazebo": "gz sim -v4 -g".split(), + "Gazebo Standalone": "gz sim -v4".split(), + "glxgears (GPU test)": ["glxgears"], # Add more applications here if needed }