Merge pull request #402 from NordicSemiconductor/doc_framework_setup

doc: add documentation framework

.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-ppk
+      - 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-ppk.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-ppk
+      - 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-ppk.zip
+          quit
+          EOF

.github/workflows/zoomin.yml

@@ -0,0 +1,34 @@
+name: Create Zoomin bundle
+
+on:
+  pull_request:
+    types: [synchronize, opened, reopened]
+    paths:
+      - 'doc/**'
+  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-ppk.zip \
+          docs/* mkdocs.yml custom.properties tags.yml
+
+      - name: Upload documentation artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: nrf-connect-ppk
+          path: nrf-connect-ppk.zip
+          retention-days: 7

doc/docs/index.md

@@ -0,0 +1,10 @@
+# nRF Connect Power Profiler
+
+nRF Connect Power Profiler is an app available from [nRF Connect for Desktop](https://nordic-dev.zoominsoftware.io/bundle/nrf-connect-desktop/page/index.html) that you can use to communicate with the Power Profiler Kit II (PPK2) in order to obtain real-time current measurements of your designs.
+
+The PPK measures current consumption for a connected Nordic Development Kit or any external board. It gives a detailed picture of the current profile for the user application.
+
+## Supported devices
+
+- Power Profiler Kit II (PPK2)
+- Power Profiler Kit (PPK1)

doc/docs/installing.md

@@ -0,0 +1,3 @@
+# Installing the Power Profiler 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,5 @@
+# Overview and user interface
+
+The nRF Connect Power Profiler app has two views that provide detailed power consumption information.
+
+![nRF Connect Power Profiler default view at startup](./screenshots/ppk2_standard_view.png "nRF Connect Power Profiler default view at startup")

doc/docs/revision_history.md

@@ -0,0 +1,10 @@
+# Revision history
+
+| Date       | Description                                                                                          |
+|------------|------------------------------------------------------------------------------------------------------|
+| 2024-02-07 | Separated the application documentation from the [PPK2 hardware documentation](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/PPK_user_guide_Intro.html).    |
+| 2022-08-16 | Updated the following topics based on nRF9160 DK v0.9.0 or later:</br></br>- Quick start</br></br>- [Measuring current in Source Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_source_meter.html)</br></br>- [Measuring current in Ampere Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_ampere_meter.html) |
+| 2021-11-01 | - Updated [Measuring current in Ampere Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_ampere_meter.html)</br></br>- Editorial changes     |
+| 2021-06-08 | Updated Pin connections in Ampere Meter mode                                                         |
+| 2021-02-26 | - Updated [Using the Power Profiler app](using_ppk_app.md)</br></br>- Updated [Measuring current in Source Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_source_meter.html)</br></br>- Updated [Measuring current in Ampere Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_ampere_meter.html)</br></br>- Added [Views](overview.md)</br></br>- Editorial changes     |
+| 2020-12-01 | First release                                                                                        |

doc/docs/troubleshooting.md

@@ -0,0 +1,42 @@
+# Troubleshooting
+
+Here are some basic troubleshooting steps to help you fix issues you may encounter when using the Power Profiler Kit II (PPK2).
+
+For more information, visit [Nordic DevZone](https://devzone.nordicsemi.com/).
+
+For personalized support from our technical support team, sign up for or sign in to Nordic Developer Zone and enter a private ticket.
+
+## Data loss with PPK2
+
+In some rare cases data loss can happen between the PPK2 firmware and the Power
+Profiler app. If this happens, first please check your data by zooming in on the
+chart and look for gaps. An occasional gap that lasts a few microseconds
+probably does not effect the accuracy of the data. However if significant data
+loss is visible please check the following points:
+
+-   avoid using USB hubs
+-   if you can, try changing your USB connection from USB3 to USB2, or other way
+    around
+-   update your USB drivers
+-   change the USB cable
+
+
+## PPK2 only measuring noise
+
+Make sure you have connected the PPK2 to the Device Under Test (DUT) as described in [Setting up the Power Profiler Kit II](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/setting_up.html).
+
+## Measurements fluctuate when there should be a steady current draw
+
+Your DUT may have a power consumption that is close to a switching point causing rapid switching between the ranges and creating measurement errors/distorted plots.
+
+## Graph response is very slow
+
+Avoid using Universal Serial Bus (USB) hubs and docking stations. Data plotting may consume a lot of CPU resources after some time, so ensure that sufficient resources are available.
+
+## PPK2 not measuring anything
+
+Confirm that the measurement cables are connected correctly because the PPK2 cannot measure negative currents.
+
+## Grounding
+
+Ensure that the DUT ground is connected to the PPK2 even in ampere meter mode.

doc/docs/using_ppk_app.md

@@ -0,0 +1,29 @@
+# Using the Power Profiler app
+
+The Power Profiler Kit II (PPK2) must be connected to your computer and powered on before the Power Profiler app is started.
+
+1. [Set up the Power Profiler Kit II for measurements](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/setting_up.html).
+1. Open the Power Profiler app using [nRF Connect](https://docs.nordicsemi.com/bundle/nrf-connect-desktop/page/installing_apps.html).
+
+    ![Default window of the Power Profiler app](./screenshots/ppk2_standard_view.png "Default window of the Power Profiler app")
+
+1. Click **Select Device** (in the top left corner) and select the PPK2 from the list.
+
+1. Do one of the following:
+
+    - If the PPK2 is set up to measure in Ampere Meter mode (see [Measuring current in Ampere Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_ampere_meter.html)), select **Ampere meter**.
+
+        !!! note "Note"
+            The power output is enabled by default in the Ampere Meter mode.
+
+    - If the PPK2 is set up to measure in Source Meter mode (see [Measuring current in Source Meter mode](https://docs.nordicsemi.com/bundle/ug_ppk2/page/UG/ppk/measure_current_source_meter.html)), select **Source meter**.
+
+        !!! note "Note"
+            You can change the voltage output to the Device Under Test (DUT, a manufactured product undergoing testing) by using the slider or typing the required voltage.
+
+1. Click **Start**.
+1. Toggle **Enable power output** to enable power to the DUT.
+
+You can start measuring current when the connection is established.
+
+The Power Profiler app checks if the PPK2 has the required firmware and shows a firmware upgrade dialog if needed.

doc/mkdocs.yml

@@ -0,0 +1,66 @@
+site_name: nRF Connect Power Profiler 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 the Power Profiler app: installing.md
+  - Overview and user interface: overview.md
+  - Using the Power Profiler app: using_ppk_app.md
+  - Troubleshooting: troubleshooting.md
+  - Revision history: revision_history.md

doc/zoomin/custom.properties

@@ -0,0 +1,3 @@
+manual.name=nrf-connect-ppk
+booktitle=nRF Connect Power Profiler
+shortdesc=Documentation for the nRF Connect Power Profiler application.

doc/zoomin/tags.yml

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