doc: add framework and docs

Added documentation framework and documentation for the app. Signed-off-by: Grzegorz Ferenc <Grzegorz.Ferenc@nordicsemi.no>
NordicSemiconductor · Mar 27, 2024 · 0cbc6d8 · 0cbc6d8
1 parent f2ff29d
commit 0cbc6d8
Show file tree

Hide file tree

Showing 21 changed files with 456 additions and 16 deletions.
diff --git a/.github/workflows/zoomin-publish-dev.yml b/.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-direct-test-mode
+      - 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 nordic@upload-v1.zoominsoftware.io <<EOF
+          cd /nordic-be-dev.zoominsoftware.io/markdown/incoming
+          put nrf-connect-direct-test-mode.zip
+          quit
+          EOF
diff --git a/.github/workflows/zoomin-publish.yml b/.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-direct-test-mode
+      - 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 nordic@upload-v1.zoominsoftware.io <<EOF
+          cd /docs-be.nordicsemi.com/markdown/incoming
+          put nrf-connect-direct-test-mode.zip
+          quit
+          EOF
diff --git a/.github/workflows/zoomin.yml b/.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-direct-test-mode.zip \
+          docs/* mkdocs.yml custom.properties tags.yml
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: nrf-connect-direct-test-mode
+          path: nrf-connect-direct-test-mode.zip
+          retention-days: 7
diff --git a/Changelog.md b/Changelog.md
@@ -33,7 +33,7 @@
 
 ### Added
 
--   Port selection for devices with multiple serialports.
+-   Port selection for devices with multiple serial ports.
 -   Selected ports are persisted per device.
 
 ### Fixed
@@ -61,7 +61,7 @@
 
 ### Fixed
 
--   DTM did not display all serialport devices.
+-   DTM did not display all serial port devices.
 
 ## 2.0.1 - 2022-01-04
 
@@ -131,7 +131,7 @@
 ### Added
 
 -   Support custom devices and custom firmware.
--   Support for physical serialport on Windows.
+-   Support for physical serial port on Windows.
 
 ## 1.0.0 - 2020-01-08
 

diff --git a/README.md b/README.md
@@ -3,18 +3,22 @@
 [![Build Status](https://dev.azure.com/NordicSemiconductor/Wayland/_apis/build/status/pc-nrfconnect-dtm?branchName=main)](https://dev.azure.com/NordicSemiconductor/Wayland/_build/latest?definitionId=19&branchName=main)
 [![License](https://img.shields.io/badge/license-Modified%20BSD%20License-blue.svg)](LICENSE)
 
-_nRF Connect Direct Test Mode_ lets you perform RF PHY testing of Bluetooth Low
-Energy devices with the Bluetooth specified Direct Test Mode. See the
-[Bluetooth Core specification](https://www.bluetooth.com/specifications/specs/core-specification-5-3/)
-(volume 6, part F) for more information on the Direct Test Mode specification.
+nRF Connect Direct Test Mode is an application for performing RF PHY testing of Bluetooth Low Energy devices with the Bluetooth-specified Direct Test Mode. See the [Bluetooth Core specification](https://www.bluetooth.com/specifications/specs/core-specification-5-3/) (volume 6, part F) for more information about the Direct Test Mode specification.
 
 ![screenshot](resources/screenshot.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 Direct Test Mode 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 Direct Test Mode](https://docs.nordicsemi.com/bundle/nrf-connect-direct-test-mode/page/index.html)
+official documentation.
 
 ## Development
 
@@ -36,3 +40,4 @@ for details.
 ## License
 
 See the [LICENSE](LICENSE) file for details.
+
diff --git a/doc/docs/index.md b/doc/docs/index.md
@@ -0,0 +1,25 @@
+# nRF Connect Direct Test Mode
+
+nRF Connect Direct Test Mode is an application that provides a graphical UI for the Direct Test Mode (DTM) commands through 2-wire UART. The DTM is a Bluetooth test framework used for performing RF PHY testing of Bluetooth Low Energy devices and ensuring interoperability of the Bluetooth devices.
+
+You can use nRF Connect Direct Test Mode to control the following features of the radio:
+
+- Set transmission power and receiver sensitivity
+- Set frequency offset and drift
+- Set modulation characteristics
+- Verify packet error rate
+- Set intermodulation performance
+
+See the [Bluetooth Core specification](https://www.bluetooth.com/specifications/specs/core-specification-5-3/) (volume 6, part F) for more information about the DTM requirements.
+
+!!! tip "Important"
+      nRF Connect Direct Test Mode cannot be used as a testing or certification tool. This is because it only provides a graphical wrapper around DTM commands for the Upper Tester. For verification using both the Upper Tester and the Lower Tester, you need an external tester equipment. For example, in case of the [Direct Test Mode Bluetooth sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/bluetooth/direct_test_mode/README.html), this can be the Anritsu MT8852 or similar, in which case you obtain the following configuration:
+
+      ![Testing setup for the Direct Test Mode Bluetooth sample](./screenshots/bt_dtm_dut.svg "Testing setup for the Direct Test Mode Bluetooth sample")
+
+nRF Connect Direct Test Mode is installed and updated using [nRF Connect for Desktop](https://docs.nordicsemi.com/bundle/ug_nrf_connect_desktop/page/struct/nrftools_nrfconnect.html) (v4.4.1 or later).
+
+## Supported devices
+
+- nRF52840 DK
+- nRF52833 DK (nRF52 DK)
diff --git a/doc/docs/installing.md b/doc/docs/installing.md
@@ -0,0 +1,3 @@
+# Installing Direct Test Mode 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.
diff --git a/doc/docs/overview.md b/doc/docs/overview.md
@@ -0,0 +1,69 @@
+# Overview and user interface
+
+After starting nRF Connect Direct Test Mode, the main application window is displayed.
+
+![nRF Connect Direct Test Mode window](./screenshots/dtm_overview.png "nRF Connect Direct Test Mode 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 serial port drop-down menu appears, where you can select the port for testing.
+
+## Transmitter tab
+
+In **Transmitter** tab, you can configure and test the transmission of the Bluetooth packets and verify the fidelity of the transmission.
+
+![Transmitter tab settings](./screenshots/dtm_transmitter_options.png "Transmitter tab settings")
+
+Click **Start test** to start transmitting test packets.
+
+The available settings are related to the DTM specification.
+
+|       Settings       |       Option        |                                                 Description                                                 |
+| -------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Channel mode**     | Single              | Transmit on the specified channel only.                                                                     |
+|                      | Sweep               | Transmit in the specified channel range.                                                                    |
+| **Channel settings** | Transmit on channel | Channel on which to transmit test packets.                                                                  |
+|                      | Transmit power      | Power of the transmission.                                                                                  |
+|                      | Transmit period     | Time during which to transmit. Only available for the Sweep mode.                                           |
+|                      | Physical layer      | Select the PHY layers on which to transmit test packets.                                                    |
+|                      | Packet type         | Select the test pattern for the test packets. `Constant carrier` uses [vendor-specific packet payload](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/bluetooth/direct_test_mode/README.html#vendor-specific_packet_payload).                                                               |
+|                      | Packet length       | Select the length of the packet.                                                                            |
+|                      | Timeout             | Select the duration of time for which the device under test (DUT) waits for a response from another device. |
+
+## Receiver tab
+
+In the **Receiver** tab, you can configure and test the reception of the Bluetooth packets and verify the fidelity of the reception.
+
+![Receiver tab settings](./screenshots/dtm_receiver_options.png "Receiver tab settings")
+
+Click **Start test** to start receiving test packets.
+
+The available settings are related to the DTM specification.
+
+|       Settings       |       Option       |                                                 Description                                                 |
+| -------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------- |
+| **Channel mode**     | Single             | Receive on the specified channel only.                                                                      |
+|                      | Sweep              | Receive in the specified channel range.                                                                     |
+| **Channel settings** | Receive on channel | Channel on which to receive test packets.                                                                   |
+|                      | Receive period     | Time during which to receive packets. Only available for the Sweep mode.                                    |
+|                      | Physical layer     | Select the PHY layers on which to receive test packets.                                                     |
+|                      | Timeout            | Select the duration of time for which the device under test (DUT) waits for a response from another device. |
+
+## 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.
diff --git a/doc/docs/revision_history.md b/doc/docs/revision_history.md
@@ -0,0 +1,5 @@
+# Revision history
+
+| Date       | Description   |
+|------------|---------------|
+| 2024-04-02 | First release, for the [v2.3.1](https://github.com/NordicSemiconductor/pc-nrfconnect-dtm/blob/main/Changelog.md) of the application. |
diff --git a/doc/docs/screenshots/bt_dtm_dut.svg b/doc/docs/screenshots/bt_dtm_dut.svg
diff --git a/doc/docs/screenshots/dtm_overview.png b/doc/docs/screenshots/dtm_overview.png
diff --git a/doc/docs/screenshots/dtm_receiver_options.png b/doc/docs/screenshots/dtm_receiver_options.png
diff --git a/doc/docs/screenshots/dtm_transmitter_options.png b/doc/docs/screenshots/dtm_transmitter_options.png
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Installing Direct Test Mode 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.