Merge pull request #239 from NordicSemiconductor/doc_add_framework

doc: add documentation framework and basic docs

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

@@ -0,0 +1,39 @@
+name: Publish documentation to Zoomin dev
+
+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-rssi-viewer
+      - 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-rssi-viewer.zip
+          quit
+          EOF

.github/workflows/zoomin-publish.yml

@@ -0,0 +1,34 @@
+name: Publish documentation to Zoomin prod
+
+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-rssi-viewer
+      - 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-rssi-viewer.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-rssi-viewer.zip \
+          docs/* mkdocs.yml custom.properties tags.yml
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: nrf-connect-rssi-viewer
+          path: nrf-connect-rssi-viewer.zip
+          retention-days: 7

README.md

@@ -3,17 +3,25 @@
 [![Build Status](https://dev.azure.com/NordicSemiconductor/Wayland/_apis/build/status/NordicSemiconductor.pc-nrfconnect-rssi?branchName=main)](https://dev.azure.com/NordicSemiconductor/Wayland/_build/latest?definitionId=9&branchName=main)
 [![License](https://img.shields.io/badge/license-Modified%20BSD%20License-blue.svg)](LICENSE)
 
-_nRF Connect RSSI Viewer_ is a tool that shows dBm per frequency in the
-2400-2480 MHz range, and allows the user to tweak settings like sweep delay and
-animation duration.
+nRF Connect RSSI Viewer is a tool that shows dBm per frequency in the 2400-2480
+MHz range, and allows you to tweak settings like sweep delay and animation
+duration.
 
-![screenshot](resources/screenshot.gif)
+![screenshot](./doc/docs/screenshots/rssi_viewer_showcase.gif)
 
 ## Installation
 
-See the
-[InfoCenter](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fstruct_nrftools%2Fstruct%2Fnrftools_nrfconnect.html)
-pages for information on how to install the application.
+nRF Connect RSSI Viewer is installed from nRF Connect from Desktop. For detailed
+steps, see
+[Installing nRF Connect for Desktop apps](https://docs.nordicsemi.com/bundle/nrf-connect-desktop/page/installing_apps.html)
+in the nRF Connect from Desktop documentation.
+
+## Documentation
+
+Read the
+[nRF Connect RSSI Viewer](https://docs.nordicsemi.com/bundle/nrf-connect-rssi-viewer/page/index.html)
+official documentation, which includes information about the
+[application UI](https://docs.nordicsemi.com/bundle/nrf-connect-rssi-viewer/page/overview.html).
 
 ## Development
 
@@ -29,7 +37,7 @@ Please report issues on the [DevZone](https://devzone.nordicsemi.com) portal.
 ## Contributing
 
 See the
-[infos on contributing](https://nordicsemiconductor.github.io/pc-nrfconnect-docs/contributing)
+[information on contributing](https://nordicsemiconductor.github.io/pc-nrfconnect-docs/contributing)
 for details.
 
 ## License

doc/docs/index.md

@@ -0,0 +1,12 @@
+# nRF Connect RSSI Viewer
+
+nRF Connect RSSI Viewer is a cross-platform tool that shows dBm per frequency in the 2.4 GHz range. It scans the 2400-2480 MHz range, records signal level on the Bluetooth Low Energy channel frequencies, and presents the results.
+
+You can use the tool with a sniffer device to look for interferers, check how channels are used, and to tweak settings like sweep delay and animation duration.
+
+RSSI Viewer is installed and updated using [nRF Connect for Desktop](https://docs.nordicsemi.com/bundle/nrf-connect-desktop/page/index.html).
+
+## Supported devices
+
+Any of the nRF52 Series boards can be used as the sniffer with the RSSI Viewer application.
+When you [select the device](overview.md#select-device), the tool will reprogram the connected board to act as the sniffer.

doc/docs/installing.md

@@ -0,0 +1,3 @@
+# Installing RSSI Viewer app
+
+For installation instructions, see [Installing nRF Connect for Desktop apps](https://docs.nordicsemi.com/bundle/nrf-connect-desktop/page/installing_apps.html) in the nRF Connect for Desktop documentation.

doc/docs/overview.md

@@ -0,0 +1,82 @@
+# Overview and user interface
+
+After starting RSSI Viewer, the main application window is displayed.
+
+![RSSI Viewer application window](./screenshots/rssi_overview.png "RSSI Viewer application window")
+
+The available options and information change after you **Select Device**.
+
+## Before selection
+
+Before a device is selected, the side panel contains the following buttons:
+
+### Select Device
+
+Dropdown to list the devices attached to the computer. When you select a [supported device](index.md#supported-devices), the app programs the device with the sniffer firmware, and then connects to one of the available serial ports. Sniffing starts automatically.
+
+## After selection
+
+When a device is selected, sniffing in the 2.4 GHz range starts automatically and the side panel options become available.
+
+![RSSI Viewer application window after selecting a device](./screenshots/rssi_viewer_working.gif "RSSI Viewer application window after selecting a device")
+
+### Controls
+
+This side panel area contains buttons that control the sniffing process:
+
+- **Start** and **Pause** - Lets you start or pause the sniffing process.
+- **Reset** - Lets you reset the sniffing output.
+
+### Sweep Scan
+
+This option lets you control the frequency with which the sniffing scan are run and with which the results are updated in the [**RSSI Viewer**](#rssi-viewer-tab) tab.
+
+### Channel Details
+
+The options in this area refer to the Bluetooth Low Energy channels displayed in the [**RSSI Viewer**](#rssi-viewer-tab) tab.
+
+- **Show max for last X scans** - The application will hold the maximum detected value of the last X scans for the given channel.
+
+    !!! info "Tip"
+          If you configure the scan to be run every `10` ms in the [**Sweep Scan**](#sweep-scan) area and set the `X` in **Show max for last X scans** to `30`, the numerical value for each channel in the [**RSSI Viewer**](#rssi-viewer-tab) tab will show the maximum value in the last 300 ms of sniffing.
+
+- **Sample each channel X times** - The application will sample each channel X times during each scan and will provide the average value as the maximum value.
+- **Hold values for X ms** - The application will hold the values measured for the given channel for X ms. The higher the value, the more values are held. This affects the dark blue part of the channel sniffing animation in the [**RSSI Viewer**](#rssi-viewer-tab) tab.
+
+### Filters
+
+The options in this area allows you to filter out specific Bluetooth LE channels and dBm values in the [**RSSI Viewer**](#rssi-viewer-tab) tab.
+Once you select the values, the sniffing will be performed only within your custom range.
+
+### Device
+
+The **Toggle LED** button lets you toggle the LED on the connected device. This feature is only available for the nRF52 DK and the nRF52840 Dongle.
+
+## RSSI Viewer tab
+
+This is the main area of the application where the sniffing results are displayed. Changing the side panel option settings is automatically reflected on the sniffing results when the sniffing is ongoing.
+
+![Changing RSSI Viewer options during sniffing](./screenshots/rssi_viewer_showcase.gif "Changing RSSI Viewer options during sniffing")
+
+You can read the channel color coding the following way:
+
+| Color                                | Meaning                                                                           |
+| ------------------------------------ | --------------------------------------------------------------------------------- |
+| Green column                         | Bluetooth LE advertisement channels (37, 38, 39).                                 |
+| Blue column                          | Bluetooth LE non-advertisement channels.                                          |
+| Dark hue (green or blue)             | Average value for the given channel. Depends on the value selected in **Hold values for X ms** in [**Channel Details**](#channel-details).                                             |
+| Light hue (green or blue)            | Maximum value for the given channel.                                              |
+| Numerical value                      | The maximum value for the given channel for the time selected in the [**Sweep Scan**](#sweep-scan) area and the amount of scans selected in **Show max for last X scans** in [**Channel Details**](#channel-details). |
+
+## 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, send feedback, and enable verbose logging.

doc/mkdocs.yml

@@ -0,0 +1,63 @@
+site_name: nRF Connect RSSI Viewer 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 RSSI Viewer app: installing.md
+  - Overview and user interface: overview.md

doc/zoomin/custom.properties

@@ -0,0 +1,3 @@
+manual.name=nrf-connect-rssi-viewer
+booktitle=nRF Connect RSSI Viewer
+shortdesc=Documentation for the nRF Connect RSSI Viewer application.

doc/zoomin/tags.yml

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