Merge pull request #3 from NordicSemiconductor/doc_add_user_guide

doc: add documentation for board configurator

.github/workflows/zoomin-publish-dev.yml

@@ -0,0 +1,39 @@
+name: Publish documentation to Zoomin
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - doc/docs
+  workflow_dispatch:
+
+jobs:
+  create-zoomin-bundle:
+    name: Create Zoomin bundle
+    uses: './.github/workflows/zoomin.yml'
+  publish-zoomin-bundle:
+    name: Publish Zoomin bundle to dev
+    needs: create-zoomin-bundle
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get bundle
+        uses: actions/download-artifact@v3
+        with:
+          name: nrf-connect-board-configurator
+      - name: Upload documentation
+        run: |
+          # trust server
+          mkdir -p ~/.ssh
+          ssh-keyscan upload-v1.zoominsoftware.io >> ~/.ssh/known_hosts
+
+          # prepare key
+          echo "${{ secrets.ZOOMIN_KEY }}" > zoomin_key
+          chmod 600 zoomin_key
+
+          # upload bundle:
+          sftp -v -i zoomin_key [email protected] <<EOF
+          cd /nordic-be-dev.zoominsoftware.io/markdown/incoming
+          put nrf-connect-board-configurator.zip
+          quit
+          EOF

.github/workflows/zoomin-publish.yml

@@ -0,0 +1,34 @@
+name: Publish documentation to Zoomin
+
+on:
+  workflow_dispatch:
+
+jobs:
+  create-zoomin-bundle:
+    name: Create Zoomin bundle
+    uses: './.github/workflows/zoomin.yml'
+  publish-zoomin-bundle:
+    name: Publish Zoomin bundle
+    needs: create-zoomin-bundle
+    runs-on: ubuntu-latest
+    steps:
+      - name: Get bundle
+        uses: actions/download-artifact@v3
+        with:
+          name: nrf-connect-board-configurator
+      - name: Upload documentation
+        run: |
+          # trust server
+          mkdir -p ~/.ssh
+          ssh-keyscan upload-v1.zoominsoftware.io >> ~/.ssh/known_hosts
+
+          # prepare key
+          echo "${{ secrets.ZOOMIN_KEY }}" > zoomin_key
+          chmod 600 zoomin_key
+
+          # upload bundle:
+          sftp -v -i zoomin_key [email protected] <<EOF
+          cd /docs-be.nordicsemi.com/markdown/incoming
+          put nrf-connect-board-configurator.zip
+          quit
+          EOF

.github/workflows/zoomin.yml

@@ -0,0 +1,34 @@
+name: Create Zoomin bundle
+
+on:
+  pull_request:
+    types: [synchronize, opened, reopened]
+    paths:
+      - '.github/workflows/zoomin.yml'
+  workflow_dispatch:
+  workflow_call:
+
+jobs:
+  create-zoomin-bundle:
+    name: Create Zoomin bundle
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Copy zoomin properties
+        run: |
+          cp doc/zoomin/custom.properties doc/ \
+          && cp doc/zoomin/tags.yml doc/
+
+      - name: Create zip file
+        run: |
+          cd doc/ \
+          && zip -r ../nrf-connect-board-configurator.zip \
+          docs/* mkdocs.yml custom.properties tags.yml
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: nrf-connect-board-configurator
+          path: nrf-connect-board-configurator.zip
+          retention-days: 7

doc/docs/index.md

@@ -0,0 +1,12 @@
+# nRF Connect Board Configurator
+
+nRF Connect Board Configurator is an application that you can use to update the board configuration on Nordic Development kits.
+
+!!! note "Note"
+      The current Board Configurator version is experimental. This means that the application is incomplete in functionality and verification and will change in the future.
+
+## Supported devices
+
+- nRF9161 DK (v0.9.1)
+
+Board Configurator is installed and updated using [nRF Connect for Desktop](https://docs.nordicsemi.com/bundle/ug_nrf_connect_desktop/page/struct/nrftools_nrfconnect.html).

doc/docs/installing.md

@@ -0,0 +1,16 @@
+# Installing Board Configurator app
+
+Board Configurator is installed as an app for **nRF Connect for Desktop**. Before you can install the app, you must download and install [nRF Connect for Desktop](https://www.nordicsemi.com/Software-and-Tools/Development-Tools/nRF-Connect-for-desktop) (version 4.3.0 or later).
+
+To install the app:
+
+1. Open nRF Connect for Desktop.
+2. Find the Board Configurator app in the list and click **Install**.
+
+Once the app is installed, you can launch it by clicking **Open**.
+
+For easy access, you can create a desktop shortcut by clicking the arrow-down button and selecting **Create shortcut**.
+
+If a new version of the app becomes available, an **Update** button is displayed next to the **Open** button. Click this button to install the latest version.
+
+To uninstall the app, click the arrow-down button and select **Uninstall**.

doc/docs/overview.md

@@ -0,0 +1,36 @@
+# Overview and user interface
+
+After starting Board Configurator, the main application window is displayed.
+
+![Board Configurator application window](./screenshots/board_configurator_overview.png "Board Configurator application window")
+
+The available options and information change after you **Select Device**.
+
+## Select Device
+
+Opens the drop-down with the list of devices connected to the computer. You can choose a device from the list of connected devices to perform further actions on the device such as configuring.
+
+## Actions
+
+When you select a device, the following actions become available in the side panel:
+
+- **Write config** - Writes the selected configurations to the development kit.
+
+## Configuration tab
+
+In the **Configuration** tab, you can see the options that are configurable for the selected development kit.
+
+![Board Configurator configuration tab](./screenshots/board_configurator_connected.png "Board Configurator configuration tab")
+
+## Log
+
+The Log panel allows you to view the most important log events, tagged with a timestamp. Each time you open the app, a new session log file is created. You can find the Log panel and its controls, below the main application Window.
+
+- When troubleshooting, to view more detailed information than shown in the Log panel, use **Open log file** to open the current log file in a text editor.
+- To clear the information currently displayed in the Log panel, use **Clear Log**. The contents of the log file are not affected.
+- To hide or display the Log panel in the user interface, use **Show Log**.
+- To freeze Log panel scrolling, use **Autoscroll Log**.
+
+## About tab
+
+You can view application information, restore defaults, access source code, and documentation. You also can find information on the selected device, access support tools, and enable verbose logging.

doc/docs/revision_history.md

@@ -0,0 +1,5 @@
+# Revision history
+
+| Date       | Description   |
+|------------|---------------|
+| 2024-01-15 | First release, for the experimental [v0.1.0](https://github.com/NordicSemiconductor/pc-nrfconnect-board-configurator/blob/main/Changelog.md) of the application. |

doc/docs/troubleshooting.md

@@ -0,0 +1,20 @@
+# Troubleshooting
+
+These troubleshooting instructions can help you fix issues you might encounter when working with Board Configurator.
+
+Remember to check the [Log](./overview.md#log) panel whenever you encounter a problem.
+To view more detailed information, use the **Open log file** option to open the current log file in a text editor.
+
+The Board Configurator app shares several of the troubleshooting issues and suggested solutions with the [nRF Connect Bluetooth Low Energy](https://docs.nordicsemi.com/bundle/nrf-connect-ble/page/index.html) app. Refer to the [troubleshooting section in the nRF Connect Bluetooth Low Energy user guide](https://docs.nordicsemi.com/bundle/nrf-connect-ble/page/troubleshooting.html) for the list of issues.
+
+## Unable to configure a device
+
+Verify that you are trying to program a [supported device](./index.md#supported-devices).
+
+## Restarting the Board Configurator app
+
+You can restart the Board Configurator app by pressing Ctrl+R in Windows and command+R in macOS. A restart might be required in the following situations:
+
+- A device is reset while it is connected to the Board Configurator app.</br>
+  In this case, you may not see all COM ports in the drop-down list while selecting the device in the app.
+- Other errors occur.

doc/docs/updating.md

@@ -0,0 +1,12 @@
+# Updating the board configuration
+
+In Board Configurator, you can update the configuration of a supported Nordic development kit.
+
+To update the configuration of a development kit, complete the following steps:
+
+1. Open nRF Connect for Desktop and open nRF Connect Board Configurator.
+1. Connect a development kit to the computer with a USB cable and turn it on.
+1. Click [**Select Device**](./overview.md#select-device) and select the device from the drop-down list.</br>
+   The button text changes to the name and serial number of the selected device and the configuration options for the selected device will appear, indicating that the device is connected.
+1. Change the setting of the wanted options in the [**Configuration**](./overview.md#configuration-tab) tab.
+1. Click [**Write config**](./overview.md#actions) to upload the config to the device.

doc/mkdocs.yml

@@ -0,0 +1,66 @@
+site_name: nRF Connect Board Configurator documentation
+site_url:
+use_directory_urls: false
+
+theme:
+  name: material
+  palette:
+    - scheme: custom-blue
+      toggle:
+        icon: material/lightbulb-outline
+        name: Switch to dark mode
+    - scheme: custom-blue-dark
+      toggle:
+        icon: material/lightbulb
+        name: Switch to light mode
+  # logo: assets/logo.png
+  # favicon: assets/logo.png
+  features:
+    - content.code.annotate
+    - content.tooltips
+    - content.tabs.link
+    - navigation.indexes
+    - navigation.top
+    - navigation.tracking
+    - search.highlight
+    - toc.follow
+
+
+extra_css:
+  - stylesheets/style.css
+
+copyright:
+  Copyright © 2023
+
+markdown_extensions:
+  - abbr
+  - admonition
+  - attr_list
+  - md_in_html
+  - meta
+  - pymdownx.details
+  - pymdownx.keys
+  - pymdownx.tabbed
+  - pymdownx.superfences
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
+  - toc:
+      permalink: true
+      toc_depth: 4
+
+plugins:
+  - macros
+  - search
+
+
+extra:
+  test: This is a test abbreviation snippet
+
+nav:
+  - Home: index.md
+  - Installing Board Configurator app: installing.md
+  - Overview and user interface: overview.md
+  - Updating the board configuration: updating.md
+  - Troubleshooting: troubleshooting.md
+  - Revision history: revision_history.md

doc/zoomin/custom.properties

@@ -0,0 +1,3 @@
+manual.name=nrf-connect-board-configurator
+booktitle=nRF Connect Board Configurator
+shortdesc=Documentation for the nRF Connect Board Configurator application.

doc/zoomin/tags.yml

@@ -0,0 +1,10 @@
+# Document tags for Zoomin.
+
+# Tags for all topics:
+mapping_global:
+  - nrf-connect-board-configurator
+
+# Tags for individual topics:
+#mapping_topics:
+#  - filename.md: ["tag1","tag2"]
+