doc: add initial documentation

Add initial documentation.

Signed-off-by: Henrik Brix Andersen <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Documentation
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          pip install -r doc/requirements.txt
+
+      - name: Build
+        run: |
+          cd doc
+          env SPHINXOPTS="-W" make html
+
+      - name: Setup pages
+        if: github.event_name != 'pull_request'
+        uses: actions/configure-pages@v4
+
+      - name: Upload pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/build/html
+
+      - name: Upload artifact
+        if: github.event_name == 'pull_request'
+        uses: actions/upload-artifact@v4
+        with:
+          path: doc/build/html
+
+  deploy:
+    runs-on: ubuntu-22.04
+    needs: build
+    if: github.event_name != 'pull_request'
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.gitignore

@@ -11,6 +11,3 @@
 **/build*
 
 __pycache__/
-
-# docs
-/doc/_build*

README.md

@@ -18,7 +18,8 @@ other software packages.
 The firmware, which is based on the [Zephyr RTOS](https://www.zephyrproject.org), allows turning
 your favorite microcontroller development board into a full-fledged USB to CAN adapter.
 
-CANnectivity is licensed under the [Apache-2.0 license](LICENSE).
+CANnectivity is licensed under the [Apache-2.0 license](LICENSE). The CANnectivity documentation is
+licensed under the [CC BY 4.0 license](doc/LICENSE).
 
 ## Firmware Features
 

doc/Makefile

@@ -0,0 +1,21 @@
+# Copyright (c) 2024 Henrik Brix Andersen <[email protected]>
+# SPDX-License-Identifier: Apache-2.0
+#
+# Minimal Makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+
+SOURCEDIR     = .
+BUILDDIR      = build
+
+.PHONY: Makefile clean help html
+
+html: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	$(RM) -r build

doc/building.rst

@@ -0,0 +1,85 @@
+..
+  Copyright (c) 2024 Henrik Brix Andersen <[email protected]>
+  SPDX-License-Identifier: CC-BY-4.0
+
+:hide-toc:
+
+Building and Running
+====================
+
+Building the CANnectivity firmware requires a proper Zephyr development environment. Follow the
+official `Zephyr Getting Started Guide`_ to establish one.
+
+Once a proper Zephyr development environment is established, inialize the workspace folder (here
+``my-workspace``). This will clone the CANnectivity firmware repository and download the necessary
+Zephyr modules:
+
+.. code-block:: console
+
+   west init -m https://github.com/CANnectivity/cannectivity --mr main my-workspace
+   cd my-workspace
+   west update
+
+Next, build the CANnectivity firmware in its default configuration for your board (here
+``lpcxpresso55s16``) using ``west``:
+
+.. code-block:: console
+
+   west build -b lpcxpresso55s16/lpc55s16 cannectivity/app/
+
+To use the ``release`` configuration, which has reduced log levels, set ``FILE_SUFFIX=release``:
+
+.. code-block:: console
+
+   west build -b lpcxpresso55s16/lpc55s16 cannectivity/app/ -- -DFILE_SUFFIX=release
+
+Build configurations for using the experimental ``device_next`` USB device stack in Zephyr are also
+provided. These can be selected by setting either ``FILE_SUFFIX=usbd_next`` or
+``FILE_SUFFIX=usbd_next_release``.
+
+After building, the firmware can be flashed to the board by running the ``west flash`` command.
+
+USB Device Firmware Upgrade (DFU) Mode
+--------------------------------------
+
+CANnectivity supports USB Device Firmware Upgrade (`DFU`_) via the `MCUboot`_ bootloader. This is
+intended for use with boards without an on-board programmer.
+
+To build CANnectivity with MCUboot integration for USB DFU use `sysbuild`_ with the
+``sysbuild-dfu.conf`` configuration file when building for your board (here ``frdm_k64f``):
+
+.. code-block:: console
+
+   west build -b frdm_k64f/mk64f12  --sysbuild ../custom/cannectivity/app/ -- -DSB_CONF_FILE=sysbuild-dfu.conf
+
+After building, MCUboot and the CANnectivity firmware can be flashed to the board by running the
+``west flash`` command.
+
+Subsequent CANnectivity firmware updates can be applied via USB DFU. In order to do so, the board
+must first be booted into USB DFU mode. If your board has a dedicated DFU button (identified by the
+``mcuboot-button0`` devicetree alias) press and hold it for 5 seconds or press and hold the button
+while powering up the board. If your board has a DFU LED (identified by the ``mcuboot-led0``
+devicetree alias), the LED will flash while the DFU button is being held and change to constant on
+once DFU mode is activated. Refer to your board documentation for further details.
+
+Once in DFU mode, the CANnectivity firmware can be updated using
+`dfu-util`_:
+
+.. code-block:: console
+
+   dfu-util -a 1 -D build/app/zephyr/zephyr.signed.bin.dfu
+
+.. _Zephyr Getting Started Guide:
+   https://docs.zephyrproject.org/latest/getting_started/index.html
+
+.. _DFU:
+   https://docs.zephyrproject.org/latest/services/device_mgmt/dfu.html
+
+.. _MCUboot:
+   https://www.trustedfirmware.org/projects/mcuboot/
+
+.. _sysbuild:
+   https://docs.zephyrproject.org/latest/build/sysbuild/index.html
+
+.. _dfu-util:
+   https://dfu-util.sourceforge.net/

doc/conf.py

@@ -0,0 +1,58 @@
+# Copyright (c) 2024 Henrik Brix Andersen <[email protected]>
+# SPDX-License-Identifier: Apache-2.0
+#
+# Configuration file for the Sphinx documentation builder
+
+from pathlib import Path
+import re
+import sys
+
+project = 'CANnectivity'
+copyright = '2024, The CANnectivity Developers'
+author = 'The CANnectivity Developers'
+
+extensions = [
+    'sphinx_copybutton',
+    'sphinx.ext.githubpages',
+]
+
+exclude_patterns = ['build', 'Thumbs.db', '.DS_Store']
+
+html_baseurl = 'https://cannectivity.org/'
+html_title = 'CANnectivity USB to CAN adapter firmware'
+html_logo = 'static/CANnectivity.png'
+html_last_updated_fmt = "%Y-%m-%d"
+html_show_sourcelink = False
+html_show_sphinx = False
+html_static_path = ['static']
+html_theme = 'furo'
+html_copy_source = False
+html_theme_options = {
+    "light_css_variables": {
+        "color-sidebar-caption-text": "#019966",
+        "color-brand-primary": "#404040",
+        "color-brand-content": "#404040",
+    },
+    "dark_css_variables": {
+        "color-sidebar-caption-text": "#019966",
+        "color-brand-primary": "#e0e0e0",
+        "color-brand-content": "#e0e0e0",
+    },
+    "top_of_page_buttons": ["view"],
+    "source_repository": "https://github.com/CANnectivity/cannectivity/",
+    "source_branch": "main",
+    "source_directory": "doc/",
+    "sidebar_hide_name": True,
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/CANnectivity/cannectivity",
+            "html": """
+                <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
+                    <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
+                </svg>
+            """,
+            "class": "",
+        },
+    ],
+}

doc/index.rst

@@ -0,0 +1,69 @@
+..
+  Copyright (c) 2024 Henrik Brix Andersen <[email protected]>
+  SPDX-License-Identifier: CC-BY-4.0
+
+:hide-toc:
+
+Introduction
+============
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+   :caption: Contents:
+
+   self
+   building
+   porting
+   module
+
+CANnectivity is an open source firmware for Universal Serial Bus (USB) to Controller Area Network
+(CAN) adapters.
+
+The firmware implements the Geschwister Schneider USB/CAN device protocol (often referred to as
+"gs_usb").  This protocol is supported by the Linux kernel SocketCAN `gs_usb driver`_, by
+`python-can`_, and by many other software packages.
+
+The firmware, which is based on the `Zephyr RTOS`_, allows turning your favorite microcontroller
+development board into a full-fledged USB to CAN adapter.
+
+CANnectivity is licenced under the `Apache-2.0 license`_. The CANnectivity documentation is licensed
+under the `CC BY 4.0 license`_.
+
+Firmware Features
+-----------------
+
+The CANnectivity firmware supports the following features, some of which depend on hardware support:
+
+* CAN classic
+* CAN FD (flexible data rate)
+* Fast-speed and Hi-speed USB
+* Multiple, independent CAN channels
+* GPIO-controlled LEDs:
+
+  * CAN channel state LEDs
+  * CAN channel activity LEDs
+  * Visual CAN channel identification
+
+* GPIO-controlled CAN bus termination resistors
+* Hardware timestamping of received and transmitted CAN frames
+* CAN bus state reporting
+* CAN bus error reporting
+* Automatic gs_usb driver loading under Linux using custom udev rules
+* Automatic WinUSB driver installation under Microsoft Windows 8.1 and newer
+* USB Device Firmware Upgrade (DFU) mode
+
+.. _gs_usb driver:
+   https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/net/can/usb/gs_usb.c
+
+.. _python-can:
+   https://python-can.readthedocs.io/en/stable/interfaces/gs_usb.html
+
+.. _Zephyr RTOS:
+   https://www.zephyrproject.org
+
+.. _Apache-2.0 license:
+   http://www.apache.org/licenses/LICENSE-2.0
+
+.. _CC BY 4.0 license:
+   https://creativecommons.org/licenses/by/4.0/

doc/module.rst

@@ -0,0 +1,27 @@
+..
+  Copyright (c) 2024 Henrik Brix Andersen <[email protected]>
+  SPDX-License-Identifier: CC-BY-4.0
+
+:hide-toc:
+
+Zephyr Module
+=============
+
+The CANnectivity firmware repository is a `Zephyr module`_ which allows for reuse of its components
+(i.e. the ``gs_usb`` protocol implementation) outside of the CANnectivity firmware application.
+
+To pull in CANnectivity as a Zephyr module, either add it as a West project in the ``west.yaml``
+file or pull it in by adding a submanifest (e.g. ``zephyr/submanifests/cannectivity.yaml``) file
+with the following content and run ``west update``:
+
+.. code-block:: yaml
+
+   manifest:
+     projects:
+       - name: cannectivity
+         url: https://github.com/CANnectivity/cannectivity.git
+         revision: main
+         path: custom/cannectivity # adjust the path as needed
+
+.. _Zephyr module:
+   https://docs.zephyrproject.org/latest/develop/modules.html

doc/porting.rst

@@ -0,0 +1,40 @@
+..
+  Copyright (c) 2024 Henrik Brix Andersen <[email protected]>
+  SPDX-License-Identifier: CC-BY-4.0
+
+:hide-toc:
+
+Board Porting Guide
+===================
+
+Hardware Requirements
+---------------------
+
+Since the CANnectivity firmware is based on the Zephyr RTOS, it requires Zephyr support for the
+board it is to run on. The board configuration must support both an USB device driver and at least
+one CAN controller.
+
+Check the list of `supported boards`_ in the Zephyr documentation to see if your board is already
+supported. If not, have a look at the instructions in the `board porting guide`_.
+
+Board Configuration
+-------------------
+
+By default, CANnectivity relies on the `devicetree`_ ``zephyr,canbus`` chosen node property for
+specifying the CAN controller to use. If a devicetree alias for ``led0`` is present, it is used as
+status LED. This means that virtually any Zephyr board configuration supporting USB device, a CAN
+controller, and an optional user LED will work without any further configuration.
+
+Advanced board configuration (e.g. multiple CAN controllers, multiple LEDs, hardware timestamp
+counter) is also supported via devicetree overlays. Check the description for the ``cannectivity``
+devicetree binding ``app/dts/bindings/cannectivity.yaml`` and the example devicetree overlays under
+``app/boards/``.
+
+.. _supported boards:
+   https://docs.zephyrproject.org/latest/boards/index.html
+
+.. _board porting guide:
+   https://docs.zephyrproject.org/latest/hardware/porting/board_porting.html
+
+.. _devicetree:
+   https://docs.zephyrproject.org/latest/build/dts/index.html

doc/requirements.txt

@@ -0,0 +1,3 @@
+furo
+sphinx
+sphinx-copybutton