Updated M.2 Dock User's Guide

docs/getting-started.md

@@ -0,0 +1,135 @@
+# Getting Started with M.2 Dock
+
+## Introduction
+
+This guide is intended to assist users in the initial setup and demonstration of the basic usage with M.2 Dock:
+
+* [Logging via Serial port](#logging-via-serial-port)
+* [Drag-n-Drop Programming](#drag-n-drop-programming)
+* [Using pyOCD Command Tool](#using-pyocd-command-tool)
+
+## What you'll need
+
+* A [nRF52840 M.2 Developer Kit](https://store.makerdiary.com/products/nrf52840-m2-developer-kit) (including nRF52840 M.2 Module and M.2 Dock)
+* A macOS, Linux or Windows computer
+
+## Assemble the hardware
+
+1. Make sure the M.2 Dock is powered off
+
+2. Attach the provided 2.4GHz and NFC cabled PCB antennas to the nRF52840 M.2 module as shown in the figure below:
+
+	![Attaching Antennas](assets/images/attaching-antennas-to-m2.webp)
+
+3. Insert the module into the connector as shown in the figure below:
+
+	!!! Warning "Angle of Insertion"
+		Angled insertion is allowable and preferred to minimize the insertion force. The angle of insertion is **5° ~ 25°**, **typically 20°**.
+
+	![Module Insertion](assets/images/m2-module-insertion.png)
+
+4. Secure the module using the provided mounting screw as shown in the figure below:
+
+	![Secure the module](assets/images/secure-m2-module-screw.png)
+
+
+## Connect the board
+
+1. Mount the nRF52840 M.2 Module
+2. Connect the **Debugger USB port** of M.2 Dock to your PC using the provided USB-C Cable
+3. A disk drive called **M2-DOCK** will be automatically detected by the computer.
+
+![](assets/images/connect-m2-dock-debugger.webp)
+
+## Logging via Serial port
+
+M.2 Dock enables developers with a Virtual COM Port which you can use for logging and reporting application state.
+
+There are many Terminal applications available for your host PC. They provide a window where your target can print messages. Select the tool according to your host:
+
+* [screen](https://www.gnu.org/software/screen/manual/screen.html) (for macOS/Linux)
+* [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/) (for Windows)
+* [CoolTerm](http://freeware.the-meiers.org/) (for macOS/Linux/Windows)
+
+![](assets/images/screen-via-serial.webp)
+
+## Drag-n-Drop Programming
+
+Drag-n-Drop is an optional intuitive programming feature. It allows programming of your target MCU in a very simple way: dragging and dropping a file (`.hex`-format) onto the **M2-DOCK** drive.
+
+There is no need to install application software. Anyone that can drag and drop a file to a USB memory stick can now program the target module.
+
+![](assets/images/drag-n-drop-programming.webp)
+
+!!! tip
+	Upon completion, the drive remounts. If a failure occurs, the file `FAIL.TXT` appears on the drive containing information about the failure.
+
+## Using pyOCD Command Tool
+
+[pyOCD](https://github.com/mbedmicro/pyOCD) is an open source Python package for programming and debugging Arm Cortex-M microcontrollers using the DAPLink debugger. It is fully cross-platform, with support for Linux, macOS, and Windows.
+
+The latest stable version of pyOCD can be installed via [pip](https://pip.pypa.io/en/stable/index.html) as follows. **Skip** the installation if pyOCD already exists.
+
+``` sh
+pip install -U pyocd
+```
+
+List information about the probe connected to your computer by running:
+
+``` sh
+pyocd list
+```
+
+The output should be similar as below:
+
+``` sh
+  #   Probe                   Unique ID
+--------------------------------------------------------------------------------
+  0   ARM DAPLink CMSIS-DAP   10283602185129a100000000000000000000000097969902
+```
+
+The following commands demonstrate how to flash/erase the nRF52840 M.2 Module:
+
+* To erase the whole flash of the nRF52840 target:
+
+	``` sh
+	pyocd erase -t nrf52840 --chip
+	```
+
+* To flash the nRF52840 target with `.hex`-format firmware:
+
+	``` sh
+	pyocd flash -t nrf52840 Sample.hex
+	```
+
+* To flash the nRF52840 target with a plain binary:
+
+	``` sh
+	pyocd flash -t nrf52840 --base-address 0x1000 Sample.bin
+	```
+	The `--base-address` option is used for setting the address where to flash a binary. Defaults to start of flash.
+
+!!! tip
+	Run `pyocd --hlep` to get the available commands and additional help.
+
+## Explore Further
+
+Now that you are familiar with the M.2 Dock, it's time to explore more tutorials available below:
+
+* [Getting Started with Power Profiling](power-profiling.md)
+* [Debugging with pyOCD](debugging/pyocd.md)
+* [Debugging with Visual Studio Code](debugging/vscode.md)
+* [Debugging with Eclipse](debugging/eclipse.md)
+* [Debugging with Keil MDK](debugging/keil-mdk.md)
+* [Debugging with IAR Workbench](debugging/iar-ewarm.md)
+* [Upgrading the DAPLink Firmware](upgrading.md)
+
+We also offer the **[nRF52840 M.2 Developer Kit](https://store.makerdiary.com/products/nrf52840-m2-developer-kit)** to help you prototype your application and then scale to production faster using the nRF52840 M.2 Module combined with your custom PCB hardware.
+
+<a href="https://wiki.makerdiary.com/nrf52840-m2-devkit" target="_blank"><button class="md-tile md-tile--primary" style="width:auto;"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M12.17 3.83c-.27-.27-.47-.55-.63-.88-.16-.31-.27-.66-.34-1.02-.58.33-1.16.7-1.73 1.13-.58.44-1.14.94-1.69 1.48-.7.7-1.33 1.81-1.78 2.45H3L0 10h3l2-2c-.34.77-1.02 2.98-1 3l1 1c.02.02 2.23-.64 3-1l-2 2v3l3-3v-3c.64-.45 1.75-1.09 2.45-1.78.55-.55 1.05-1.13 1.47-1.7.44-.58.81-1.16 1.14-1.72-.36-.08-.7-.19-1.03-.34a3.39 3.39 0 01-.86-.63zM16 0s-.09.38-.3 1.06c-.2.7-.55 1.58-1.06 2.66-.7-.08-1.27-.33-1.66-.72-.39-.39-.63-.94-.7-1.64C13.36.84 14.23.48 14.92.28 15.62.08 16 0 16 0z"></path></svg> nRF52840 M.2 Developer Kit</button></a>
+
+## Create an Issue
+
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/m2-dock/issues/new?title=Getting%20Started:%20%3Ctitle%3E"><button class="md-tile md-tile--primary"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 16" width="14" height="16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 011.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg> Create an Issue</button></a>

docs/index.md

@@ -0,0 +1,75 @@
+# M.2 Dock<br/><small>An essential carrier board to quickly prototype your next embedded design with a removable M.2 module.</small>
+
+## Description
+
+The M.2 Dock is an essential carrier board to quickly prototype your next embedded design with a removable M.2 module. It features a fully-integrated [DAPLink](https://armmbed.github.io/DAPLink/) debugger with [Power Profiling](power-profiling.md), enabling you to program, debug and perform real-time current profiling of your IoT applications without using external tools.
+
+This design extends the interfaces compared to the M.2 Module through an M.2 E-Key connector, including USB 2.0 ports, UART, SPI, TWI, PDM, I2S, PWM, ADC and GPIOs.
+
+The M.2 Dock also comes with 1.3" 240x240 Color IPS TFT LCD, Li-Po Battery Charger, microSD Card Slot, Grove Connectors, LEDs and Buttons.
+
+[![M.2 Dock Image](assets/images/m2-dock-prod.webp)](https://store.makerdiary.com/products/nrf52840-m2-developer-kit)
+
+## Key Features
+
+* Integrated DAPLink Debugger
+	- MSC - drag-n-drop programming flash memory
+	- CDC - virtual com port for log, trace and terminal emulation
+	- HID/WEBUSB HID - CMSIS-DAP compliant debug channel
+
+* Advanced Power Profiling
+	- Up to 690 mA current measurement
+	- Voltage tracking
+	- 30000 samples per second
+	- Precision amplifiers with dual gain stage
+	- Cross-platform utility available in Python
+
+* 1.3" 240x240 Color IPS TFT LCD Display
+* Li-Po Battery Charger with Power Path Management
+* User programmable LED and Button
+* microSD Card Slot
+* 4 Grove Connectors
+* Reversible USB-C Connectors
+* Arduino Form Factor
+* 3.3V IO Operationg Voltage
+
+## Hardware Diagram
+
+The hardware diagram of the M.2 Dock is shown below:
+
+<a href="resources/m2_dock_diagram_v1_0.pdf" target="_blank"><img alt="Click to download the PDF" src="assets/images/m2-dock-diagram.webp"></a>
+
+## Tutorials
+
+We think the best way to learn is by doing. And to help you get started, we have provided a series of tutorials. Find the details below:
+
+* [Getting Started with M.2 Dock](getting-started.md)
+* [Getting Started with Power Profiling](power-profiling.md)
+* [Debugging with pyOCD](debugging/pyocd.md)
+* [Debugging with Visual Studio Code](debugging/vscode.md)
+* [Debugging with Eclipse](debugging/eclipse.md)
+* [Debugging with Keil MDK](debugging/keil-mdk.md)
+* [Debugging with IAR Workbench](debugging/iar-ewarm.md)
+* [Upgrading the DAPLink Firmware](upgrading.md)
+
+We also offer the **[nRF52840 M.2 Developer Kit](https://store.makerdiary.com/products/nrf52840-m2-developer-kit)** to help you prototype your application and then scale to production faster using the nRF52840 M.2 Module combined with your custom PCB hardware.
+
+<a href="https://wiki.makerdiary.com/nrf52840-m2-devkit" target="_blank"><button class="md-tile md-tile--primary" style="width:auto;"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" width="16" height="16"><path fill-rule="evenodd" d="M12.17 3.83c-.27-.27-.47-.55-.63-.88-.16-.31-.27-.66-.34-1.02-.58.33-1.16.7-1.73 1.13-.58.44-1.14.94-1.69 1.48-.7.7-1.33 1.81-1.78 2.45H3L0 10h3l2-2c-.34.77-1.02 2.98-1 3l1 1c.02.02 2.23-.64 3-1l-2 2v3l3-3v-3c.64-.45 1.75-1.09 2.45-1.78.55-.55 1.05-1.13 1.47-1.7.44-.58.81-1.16 1.14-1.72-.36-.08-.7-.19-1.03-.34a3.39 3.39 0 01-.86-.63zM16 0s-.09.38-.3 1.06c-.2.7-.55 1.58-1.06 2.66-.7-.08-1.27-.33-1.66-.72-.39-.39-.63-.94-.7-1.64C13.36.84 14.23.48 14.92.28 15.62.08 16 0 16 0z"></path></svg> nRF52840 M.2 Developer Kit</button></a>
+
+## Supported Modules
+
+The following shows the M.2 module that can work with M.2 Dock. More modules are planned and will show up gradually over time.
+
+* [nRF52840 M.2 Module](https://store.makerdiary.com/products/nrf52840-m2-module)
+
+## Design Resource
+
+* [M.2 Dock Hardware Diagram v1.0](resources/m2_dock_diagram_v1_0.pdf)
+* [M.2 Dock Schematic V1.0 for nRF52840 M.2 Module](resources/m2_dock_schematic_v1_0_for_nrf52840.pdf)
+* [M.2 Dock Board File V1.0](resources/m2_dock_board_file_v1_0.pdf)
+* [M.2 Dock 3D Model V1.0](resources/m2_dock_3d_model_v1_0.step)
+
+## Create an Issue
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/m2-dock/issues/new"><button class="md-tile md-tile--primary"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 16" width="14" height="16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 011.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg> Create an Issue</button></a>

docs/power-profiling.md

@@ -0,0 +1,73 @@
+# Getting Started with Power Profiling
+
+## Description
+
+The M.2 Dock features an Advanced Power Profiler, enabling you to perform real-time current profiling of your applications without using external tools.
+
+**Key features**
+
+* Up to 690 mA current measurement
+* Voltage tracking
+* 30000 samples per second
+* Precision amplifiers with dual gain stage
+* Cross-platform utility available in Python
+
+This section details how to perform real-time current profiling of your applications.
+
+## What you'll need
+
+* A [nRF52840 M.2 Developer Kit](https://store.makerdiary.com/products/nrf52840-m2-developer-kit) (including nRF52840 M.2 Module and M.2 Dock)
+* A macOS, Linux or Windows computer
+
+## How it works
+
+The Advanced Power Profiler utilizes a current sense amplifier together with a dual gain stage to measure the voltage drop over a small series resistor (0.056Ω). The output voltage is measured by an ADC channel.
+
+The Advanced Power Profiler is capable of measuring currents up to 690 mA. When measuring currents below 11 mA, the accuracy is 50 µA. For currents above 11 mA, the accuracy is 5 mA.
+
+In addition, the voltage of the module (VDD_M2) is measured by another ADC channel through a 1:2 voltage divider. 
+
+After the conversion is completed, the samples are exported to the Power Profiler utility over USB CDC ACM. It can produce 30000 samples per second (2 bytes per sample).
+
+The figure below shows how the Advanced Power Profiler works:
+
+![](assets/images/power-profiler-diagram.webp)
+
+## Installing the Power Profiler
+
+[Power Profiler](https://github.com/makerdiary/power-profiler) is an open source Python utility for real-time power profiling of your applications running on the nRF52840 M.2 Developer Kit. It is fully cross-platform, with support for Linux, macOS, and Windows.
+
+The latest stable version of Power Profiler can be installed via [pip](https://pip.pypa.io/en/stable/index.html) as follows.
+
+``` sh
+pip3 install power-profiler
+```
+
+## Using the Power Profiler
+
+The steps below demonstrate how to use the Power Profiler utility to perform real-time current profiling of a simple application:
+
+1. Assemble the M.2 Module, then connect the **Debugger USB port** to your PC using the provided USB-C Cable. A disk drive called **M2-DOCK** will be automatically detected by the computer.
+
+	![](assets/images/connect-m2-dock-debugger.webp)
+
+2. Program the board with your application firmware. Will use the [Blinky](https://github.com/makerdiary/nrf52840-m2-devkit/tree/master/examples/nrf5-sdk/blinky) example here to keep it simple.
+
+3. Start the Power Profiler in your terminal by running:
+
+	``` sh
+	power-profiler
+	```
+
+4. The Power Profiler window will appear. Observe the current curve:
+
+	![](assets/images/blinky-power-profiling.webp)
+
+5. You can try more example applications and measure their real-time power consumption.
+
+
+## Create an Issue
+
+Interested in contributing to this project? Want to report a bug? Feel free to click here:
+
+<a href="https://github.com/makerdiary/m2-dock/issues/new?title=Power%20Profiling:%20%3Ctitle%3E"><button class="md-tile md-tile--primary"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 16" width="14" height="16"><path fill-rule="evenodd" d="M7 2.3c3.14 0 5.7 2.56 5.7 5.7s-2.56 5.7-5.7 5.7A5.71 5.71 0 011.3 8c0-3.14 2.56-5.7 5.7-5.7zM7 1C3.14 1 0 4.14 0 8s3.14 7 7 7 7-3.14 7-7-3.14-7-7-7zm1 3H6v5h2V4zm0 6H6v2h2v-2z"></path></svg> Create an Issue</button></a>

docs/resources.md

@@ -0,0 +1,29 @@
+# Resources
+
+See below for available documentation, software, and other resources.
+
+## Documentation and guides
+
+* [Getting Started with M.2 Dock](getting-started.md)
+* [Getting Started with Power Profiling](power-profiling.md)
+* [Debugging with pyOCD](debugging/pyocd.md)
+* [Debugging with Visual Studio Code](debugging/vscode.md)
+* [Debugging with Eclipse](debugging/eclipse.md)
+* [Debugging with Keil MDK](debugging/keil-mdk.md)
+* [Debugging with IAR Workbench](debugging/iar-ewarm.md)
+* [Upgrading the DAPLink Firmware](upgrading.md)
+* [nRF52840 M.2 Developer Kit Documentation](https://wiki.makerdiary.com/nrf52840-m2-devkit)
+* [nRF52840 M.2 Module Documentation](https://wiki.makerdiary.com/nrf52840-m2)
+
+## Hardware Resource
+
+* [M.2 Dock Hardware Diagram V1.0](https://wiki.makerdiary.com/m2-dock/resources/m2_dock_hw_diagram_v1_0.pdf)
+* [M.2 Dock Schematic V1.0](https://wiki.makerdiary.com/m2-dock/resources/m2_dock_schematic_v1_0.pdf)
+* [M.2 Dock Board File V1.0](https://wiki.makerdiary.com/m2-dock/resources/m2_dock_board_file_v1_0.pdf)
+* [M.2 Dock 3D Model V1.0](https://wiki.makerdiary.com/m2-dock/resources/m2_dock_3d_model_v1_0.step)
+
+## Request a Tutorial
+
+If you don't see what you're looking for, you can request a tutoial by submitting an issue to our GitHub Repository. We'd love to see your feedback!
+
+<a href="https://github.com/makerdiary/m2-dock/issues/new?title=Tutorial%20Request:%20%3Ctitle%3E&body=Description%0A%0ATechnical%20Level%0Abeginner%20%7C%20intermediate%20%7C%20advanced%0A%0ALength%0Ashort%20(%3C%20250%20words)%20%7C%20medium%20(250-500%20words)%20%7C%20long%20(1000%20words+)%0A"><button class="md-tile md-tile--primary" style="width:auto;"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 14 16" width="14" height="16"><path fill-rule="evenodd" d="M12 8V1c0-.55-.45-1-1-1H1C.45 0 0 .45 0 1v12c0 .55.45 1 1 1h2v2l1.5-1.5L6 16v-4H3v1H1v-2h7v-1H2V1h9v7h1zM4 2H3v1h1V2zM3 4h1v1H3V4zm1 2H3v1h1V6zm0 3H3V8h1v1zm6 3H8v2h2v2h2v-2h2v-2h-2v-2h-2v2z"></path></svg> Request a Tutorial</button></a>