docs/build: document nanopi-r1 setup

Closes: siemens#124
Signed-off-by: Cedric Hombourger <cedric.hombourger@siemens.com>

.reuse/dep5

@@ -27,42 +27,22 @@ Files: docs/.gitignore
 Copyright: 2021 Siemens Digital Industries Software
 License: MIT
 
-Files: docs/*.rst
+Files: docs/*.png
 Copyright: 2021 Siemens Digital Industries Software
 License: MIT
 
-Files: docs/jqc3f-05vdc.jpg
+Files: docs/*.rst
 Copyright: 2021 Siemens Digital Industries Software
 License: MIT
 
-Files: docs/neo_block_diagram.png
+Files: docs/jqc3f-05vdc.jpg
 Copyright: 2021 Siemens Digital Industries Software
 License: MIT
 
 Files: docs/neo_pinout.jpg
 Copyright: 2021 Siemens Digital Industries Software
 License: MIT
 
-Files: docs/neo_sdwire_de0-nano-soc.png
-Copyright: 2021 Siemens Digital Industries Software
-License: MIT
-
-Files: docs/homekit_add_1.png
-Copyright: 2021 Siemens Digital Industries Software
-License: MIT
-
-Files: docs/homekit_add_2.png
-Copyright: 2021 Siemens Digital Industries Software
-License: MIT
-
-Files: docs/lava_mtda_workers.png
-Copyright: 2021 Siemens Digital Industries Software
-License: MIT
-
-Files: docs/lava_shared_worker.png
-Copyright: 2021 Siemens Digital Industries Software
-License: MIT
-
 Files: meta-isar/recipes-conf/hostname/files/postinst
 Copyright: 2021 Siemens Digital Industries Software
 License: MIT

docs/build.rst

@@ -199,6 +199,129 @@ and install it::
 Before starting ``kvm``, MTDA checks for the ``swtpm`` tool and automatically
 enables QEMU's support for TPM devices.
 
+NanoPI R1
+---------
+
+The NanoPi R1 ("R1") is a complete open source board developed by FriendlyElec
+for IoT applications.
+
+It has two Ethernet ports, on-board Wi-Fi and Bluetooth, a micro SD card slot
+and two USB ports. It takes power from its micro USB port.
+
+Debian (bullseye) will be loaded on the microSD card and will include the MTDA
+agent. It will communicate with its clients over Ethernet. An electric relay
+will be controlled via USB to drive power for our Device Under Test.
+Communication with that device will be achieved via the USB OTG port where the
+following functions will be exposed:
+
+ * ACM: provide a Serial over USB port. The Operating System running on the
+   Device Under Test may use this virtual serial port to provide a login
+   shell to MTDA clients.
+
+ * HID: the NanoPI R1 will be seen as a keyboard. This may be used by e.g.
+   ``power on`` scripts to enter the firmware of the Device Under Test to
+   select a boot media (SSD or USB).
+
+ * Mass Storage: a USB stick will be connected to the USB Host available on the
+   NanoPI R1 and will be exposed to the Device Under Test. MTDA will allow
+   clients to write a new OS image for the device it is connected to.
+
+Building the microSD card image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use ``kas-container`` to build a Debian image for the nanoPI R1 with MTDA
+pre-installed::
+
+    $ ./kas-container build kas/debian/mtda-nanopi-r1.yml
+
+Insert a microSD card to your system and write the generated image::
+
+    # Check the microSD card device, /dev/mmcblk0 is used as an example
+    $ sudo dd if=build/tmp/deploy/images/nanopi-r1/isar-*.wic.img \
+      of=/dev/mmcblk0 bs=8M
+
+(replace ``/dev/mmcblk0`` with the actual SD card device on your system).
+
+Booting the NanoPI R1
+~~~~~~~~~~~~~~~~~~~~~
+
+Insert the microSD card created above into the microSD card slot of your NanoPI
+R1 and connect the board to your network. Attach a formatted USB stick to
+the USB-Host port. Lastly, get a USB Y cable with one end connected to a fixed
+USB power source (2A) and the other end connected to the Device Under Test. The
+microUSB end will be connected to the R1. The red LED of the R1 should light up
+as well as the LEDs from the RJ45 port. You may check that your R1 has obtained
+an IP address. Use ``ssh`` to connect (use ``mtda`` as both login and password).
+
+Attaching an electric relay
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+We will use a 5V relay such as the ARCELI SRD-05VDC-SL-C and attach it to one
+of the USB ports provided by the R1.
+
+Stitching It All Together
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following diagram shows the various connections described above:
+
+.. image:: r1_block_diagram.png
+
+Configuring MTDA
+~~~~~~~~~~~~~~~~
+
+A configuration file should be created on the NanoPI R1. Use ``ssh`` to connect
+with the ``mtda`` user and then ``sudo`` to get elevated privileges::
+
+    $ ssh mtda@172.17.0.50
+    The authenticity of host '172.17.0.50 (172.17.0.50)' can't be established.
+    ECDSA key fingerprint is SHA256:X4hTqfSmfG1bet2Bg/MfU1fNMgp30T+6SkAwLXZbJTQ.
+    Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
+    Warning: Permanently added '172.17.0.50' (ECDSA) to the list of known hosts.
+    mtda@172.17.0.50's password: mtda
+    Linux mtda 5.14.0-0.bpo.2-armmp #1 SMP Debian 5.14.9-2~bpo11+1 (2021-10-10) armv7l
+
+    The programs included with the Debian GNU/Linux system are free software;
+    the exact distribution terms for each program are described in the
+    individual files in /usr/share/doc/*/copyright.
+
+    Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
+    permitted by applicable law.
+    Last login: Wed Dec 29 22:09:23 2021 from 192.168.1.101
+    $ sudo -s
+    [sudo] password for mtda: mtda
+    #
+
+Use ``vi`` to create an initial configuration::
+
+    # vi /etc/mtda/config
+
+Hit ``i`` to enter the input mode and type the following configuration::
+
+    [console]
+    variant=serial
+    port=/dev/ttyGS0
+    rate=9600
+
+    [power]
+    variant=usbrelay
+    lines=959BI_1
+
+    [keyboard]
+    variant=hid
+    device=/dev/hidg0
+
+    [storage]
+    variant=usbf
+
+Hit ``ESC`` to leave the input mode and type ``:x`` to exit. You should be back
+to the shell and may restart the agent::
+
+    # sync
+    # systemctl restart mtda
+
+Clients may now connect to the MTDA agent, control the power input of the Device
+Under Test and remotely access its console.
+
 NanoPI NEO-LTS
 --------------
 
@@ -232,14 +355,24 @@ Building the microSD card image
 Use ``kas-container`` to build a Debian image for the nanoPI NEO-LTS with MTDA
 pre-installed::
 
-    $ kas-container build kas/debian/mtda-nanopi-neo.yml
+    $ ./kas-container build kas/debian/mtda-nanopi-neo.yml
 
 Insert a microSD card to your system and write the generated image::
 
     # Check the microSD card device, /dev/mmcblk0 is used as an example
     $ sudo dd if=build/tmp/deploy/images/nanopi-neo/isar-*.wic.img \
       of=/dev/mmcblk0 bs=8M
 
+(replace ``/dev/mmcblk0`` with the actual SD card device on your system).
+
+Applying external power
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The NanoPI NEO-LTS usually gets powered over its USB-OTG interface. Since we
+will attach this port to the Device Under Test, we need to apply external
+power instead. Re-purpose a USB cable and connect its red wire to #2 (5V IN)
+and its black wire to #6 (GND).
+
 Booting the NanoPI NEO-LTS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -268,17 +401,6 @@ We will use pin #4 (``5V OUT``) to deliver 5V to the relay, pin #9 (``GND``) to
 connect the relay to ground and pin #7 (``PG11``) to drive the relay. It should
 be noted that the signal GPIO pin is seen as GPIO ``203`` in Linux.
 
-Applying external power
-~~~~~~~~~~~~~~~~~~~~~~~
-
-The NanoPI NEO-LTS usually gets powered over its USB-OTG interface. Since we
-will attach this port to the Device Under Test, we need to apply external
-power instead. Re-purpose a USB cable and connect its red wire to #2 (5V IN)
-and its black wire to #6 (GND).
-
-Apply power and verify that Linux comes up on the NanoPI by logging via ``ssh``
-to the ``mtda`` user account.
-
 Stitching It All Together
 ~~~~~~~~~~~~~~~~~~~~~~~~~