Merge branch 'main' of https://git.beagleboard.org/jkridner/docs.beagleboard.io

.gitlab-ci.yml

@@ -4,15 +4,35 @@ variables:
   GIT_SUBMODULE_STRATEGY: recursive
 
 cache:
-  key: bbdocs
+  key: sphinx-build-env-docs-001
   paths:
-  - public
+  - .venv
+  - .cache
+
+build:
+  stage: build
+  tags:
+  - docker-amd64
+  parallel:
+    matrix:
+      - TARGET: [html, pdf]
+  artifacts:
+    paths:
+    - public/$TARGET
+  before_script:
+    - source ./venv-build-env.sh
+  script:
+    - ./gitlab-build.sh $TARGET
 
 pages:
+  stage: deploy
+  dependencies:
+    - "build: [html]"
+    - "build: [pdf]"
   tags:
-  - docker-arm64
+  - docker-amd64
   script:
-  - "./gitlab-build.sh"
+  - ./gitlab-build.sh publish
   artifacts:
     paths:
     - public
@@ -20,10 +40,14 @@ pages:
     - tags
 
 docs:
+  stage: deploy
+  dependencies:
+    - "build: [html]"
+    - "build: [pdf]"
   tags:
   - docs
   script:
-  - "./gitlab-build.sh"
+  - ./gitlab-build.sh publish
   artifacts:
     paths:
     - public

boards/beagleconnect/freedom/02-quick-start.rst

@@ -15,25 +15,10 @@ What's included in the box?
 
    Image with what's inside the box and a better description.
 
-.. only:: latex
-    
-   .. image:: https://img.youtube.com/vi/bJYZ6PTiV9g/maxresdefault.jpg
-      :alt: BeagleConnect unboxing YouTube video
-      :width: 1280
-      :target: https://www.youtube.com/watch?v=bJYZ6PTiV9g
-
-.. only:: html
-
-    .. raw:: html
-
-        <iframe style="display: block; margin: auto;" width="1280" height="720" style="align:center" 
-        src="https://www.youtube.com/embed/bJYZ6PTiV9g" 
-        title="YouTube video player" 
-        frameborder="0" 
-        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
-        allowfullscreen>
-        </iframe>
-
+.. youtube:: bJYZ6PTiV9g
+   :align: center
+   :width: 1280
+   :height: 720
 
 Attaching antenna
 ******************

boards/beagleplay/02-quick-start.rst

@@ -24,24 +24,12 @@ Attaching antennas
 
 You can watch this video to see how to attach the attennas.
 
-.. only:: latex
-    
-    .. image:: images/attach-antennas.*
-        :alt: YouTube video of BeaglePlay antenna connection
-        :width: 1280
-        :target: https://youtu.be/8zeIVd-JRc0
-
-.. only:: html
+.. admonition:: YouTube video of BeaglePlay antenna connection
 
-    .. raw:: html
-
-        <iframe style="display: block; margin: auto;" width="920" height="520" style="align:center" 
-        src="https://www.youtube.com/embed/8zeIVd-JRc0" 
-        title="YouTube video player" 
-        frameborder="0" 
-        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" 
-        allowfullscreen>
-        </iframe>
+    .. youtube:: 8zeIVd-JRc0
+        :width: 1280
+        :height: 720
+        :align: center
 
 Tethering to PC
 ****************
@@ -57,7 +45,7 @@ Tethering to PC
 
 For tethering to your PC you'll need a USB-C data cable.
 
-.. figure:: images/tethered-connection.jpg
+.. figure:: images/tethered-connection.*
     :width: 1400
     :align: center
     :alt: Tethering BeaglePlay to PC
@@ -76,7 +64,7 @@ to browse documents and start programming your BeaglePlay!
    not having a public URL for your board. If you have any questions about this, please as on
    https://forum.beagleboard.org/tag/play.
 
-.. figure:: images/vscode.png
+.. figure:: images/vscode.*
     :width: 1400
     :align: center
     :alt: BeaglePlay VSCode IDE (192.168.7.2:3000)

boards/beagleplay/03-design.rst

@@ -501,14 +501,14 @@ Dimensions & Weight
     | Weight             | 55.3g                                              |
     +--------------------+----------------------------------------------------+
 
-.. figure:: images/dimensions.png
+.. figure:: images/dimensions.*
     :width: 700
     :align: center
     :alt: BeaglePlay board dimensions
 
     BeaglePlay board dimensions
 
-.. figure:: images/side-dimensions.png
+.. figure:: images/side-dimensions.*
     :width: 700
     :align: center
     :alt: BeaglePlay board side dimensions

boards/beagleplay/demos-and-tutorials/connect-wifi.rst

@@ -78,13 +78,13 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
 
       You can start ``wpa_gui`` either from ``Applications > Internet > wpa_gui`` or double click on the ``wpa_gui`` desktop application shortcut.
 
-      .. figure:: ../images/wpa_gui_step1a.png
+      .. figure:: ../images/wpa_gui_step1a.*
           :align: center
           :alt: Starting wpa_gui from Applications > Internet > wpa_gui
 
           Starting wpa_gui from Applications > Internet > wpa_gui
 
-      .. figure:: ../images/wpa_gui_step1b.png
+      .. figure:: ../images/wpa_gui_step1b.*
           :align: center
           :alt: Starting wpa_gui from Desktop application shortcut
 
@@ -102,7 +102,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
           - Click on ``Scan`` to scan nearby WiFi access points.
       4. ``Manage Network`` tab shows you all the saved networks and options to manage those.
 
-      .. figure:: ../images/wpa_gui_step2.png
+      .. figure:: ../images/wpa_gui_step2.*
           :align: center
           :alt: wpa_gui interface
 
@@ -113,7 +113,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
       To scan the WiFi access points around you, just click on ``Scan`` button availale under 
       ``wpa_gui > Current Status > Scan``.
 
-      .. figure:: ../images/wpa_gui_step3a.png
+      .. figure:: ../images/wpa_gui_step3a.*
           :align: center
           :alt: Scanning WiFi access points
 
@@ -133,7 +133,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
           SSIDs and BSSIDs are not fully visible in screenshot below 
           but you can change the column length to see the WiFi names better.
 
-      .. figure:: ../images/wpa_gui_step3b.png
+      .. figure:: ../images/wpa_gui_step3b.*
           :align: center
           :alt: Selecting WiFi access point
 
@@ -204,13 +204,13 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
 
       Open up a terminal window either from ``Applications > Terminal Emulator`` Or from Task Manager.
 
-      .. figure:: ../images/wpa_cli_step1a.jpg
+      .. figure:: ../images/wpa_cli_step1a.*
           :align: center
           :alt: Open terminal from Applications > Terminal Emulator
 
           Open terminal from Applications > Terminal Emulator    
 
-      .. figure:: ../images/wpa_cli_step1b.jpg
+      .. figure:: ../images/wpa_cli_step1b.*
           :align: center
           :alt: Open terminal from Task Manager
 
@@ -222,7 +222,7 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
 
       1. Execute ``sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf``, 
       which will open up ``wpa_supplicant-wlan0.conf`` inside ``nano`` (terminal based) text editor.
-      1. Edit ``wpa_supplicant-wlan0.conf`` to add SSID (WiFi name) & PSK (WiFi password) of your WiFi access point.
+      2. Edit ``wpa_supplicant-wlan0.conf`` to add SSID (WiFi name) & PSK (WiFi password) of your WiFi access point.
 
       .. code-block::
 
@@ -236,19 +236,19 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
       1. Now save the details using ``ctrl + O`` then enter.
       2. To exit out of the ``nano`` text editor use ``ctrl + X``.
 
-      .. figure:: ../images/wpa_cli_step2a.jpg
+      .. figure:: ../images/wpa_cli_step2a.*
           :align: center
           :alt: Run: $ sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
 
           Run: $ sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
 
-      .. figure:: ../images/wpa_cli_step2b.jpg
+      .. figure:: ../images/wpa_cli_step2b.*
           :align: center
           :alt: Add SSID and PSK
 
           Add SSID and PSK
 
-      .. figure:: ../images/wpa_cli_step2c.jpg
+      .. figure:: ../images/wpa_cli_step2c.*
           :align: center
           :alt: Save credentials and Exit
 
@@ -281,13 +281,13 @@ You could also choose to `ssh` into your board via `ssh debian@192.168.8.1` and
           rtt min/avg/max/mdev = 5.281/6.445/9.043/1.274 ms
 
 
-      .. figure:: ../images/wpa_cli_step3a.jpg
+      .. figure:: ../images/wpa_cli_step3a.*
           :align: center
           :alt: Connect to WiFi by running $ sudo wpa_cli -i wlan0 reconfigure
 
           Connect to WiFi by running $ sudo wpa_cli -i wlan0 reconfigure
 
-      .. figure:: ../images/wpa_cli_step3b.jpg
+      .. figure:: ../images/wpa_cli_step3b.*
           :align: center
           :alt: To check connection try running $ ping 8.8.8.8
 

boards/beagleplay/demos-and-tutorials/understanding-boot.rst

@@ -8,17 +8,14 @@ the system is using :ref:`play-distro-boot`. It is simplest because it is very g
 not at all specific to BeaglePlay or AM62, and was included in the earliest BeagleBoard.org Debian
 images shipping pre-installed in the on-board flash.
 
-Over time, BeaglePlay images will include `SystemReady
-support <https://www.arm.com/architecture/system-architectures/systemready-certification-program>`_ to
-provide for the most generic boot support allowing execution of 
-
 .. _play-distro-boot:
 
 Distro Boot
 ***********
 
 For some background on distro boot, see `the u-boot documentation on
-distro boot <https://docs.u-boot.org/en/latest/develop/distro.html>`_.
+distro boot <https://docs.u-boot.org/en/latest/develop/distro.html>`_. There is
+also `BeaglePlay specific u-boot documentation <https://docs.u-boot.org/en/latest/board/ti/am62x_beagleplay.html>`_.
 
 In :ref:`play-typical-extlinux-conf`, you can see line 1 provides a label
 and subsequent indented lines provide parameters for that boot option.
@@ -76,33 +73,58 @@ The FAT32 partition in this setup is often referred to as the boot file system.
     /dev/mmcblk0p2      264192 30621695 30357504 14.5G 83 Linux
 
 
-To better understand BeaglePlay's U-Boot Distro Boot, let's install the kernel image
-we made in :ref:`play-kernel-development`. To do this, we need to have an uncompressed
-version of the kernel in the FAT32 file system and a ramdisk image we plan to use. The
-ramdisk image is utilized to make sure any kernel modules needed are available and to
-provide a bit of a recovery opportunity in case the root file system is corrupted. You
-can learn more about initrd on `the Debian Initrd Wiki page <https://wiki.debian.org/Initrd>`
-and `the Linux kernel documentation admin guide initrd
-entry <https://docs.kernel.org/admin-guide/initrd.html>`.
+To better understand BeaglePlay's U-Boot Distro Boot, let's install a Linux kernel and
+initramfs from the `Buildroot project <http://buildroot.org/>`_. There is a pre-built image
+release at https://git.beagleboard.org/beagleboard/buildroot/-/releases/2023.11-beagle1.
 
-In :ref:`play-copy-kernel`, we perform a copy of the kernel that was installed via
-:ref:`play-dpkg-install-kernel` and then reverted with ...
+Currently, the Linux kernel image needs to be uncompressed and stored in the FAT32 file
+system. An initramfs image is a simple way to provide a starting root file system. When
+running Linux, some kind of root file system is required.
 
-.. todo::
+An initramfs image is utilized on Debian systems to make sure any kernel modules needed are
+available and to provide a bit of a recovery opportunity in case the root file system is
+corrupted. You can learn more about initramfs and initrd on `the Debian Initrd Wiki
+page <https://wiki.debian.org/Initrd>` and `the Linux kernel documentation admin
+guide initrd entry <https://docs.kernel.org/admin-guide/initrd.html>`.
 
-   Put the step into play-kernel-development.rst to revert back to the Beagle kernel.
+In the case of utilizing Buildroot, the
+entire `Linux distribution <https://en.wikipedia.org/wiki/Linux_distribution>`_ is
+incorporated into the initramfs root file system image.
 
-The contents of the initrd can be read using ``lsinitramfs /boot/firmware/initrd.img-6.6.0``.
+The contents of the initrd can be read using ``lsinitramfs /boot/firmware/initrd.img``.
 
 .. _play-copy-kernel:
 
 .. code-block:: shell-session
     :caption: Copy kernel to FAT32 filesystem
 
-    debian@BeaglePlay:~$ sudo cp /boot/vmlinuz-6.6.0 /boot/firmware/Image-6.6.gz
-    [sudo] password for debian: 
-    debian@BeaglePlay:~$ sudo gunzip /boot/firmware/Image-6.6.gz 
-    debian@BeaglePlay:~$ sudo cp /boot/initrd.img-6.6.0 /boot/firmware/
+    debian@BeaglePlay:~$ wget https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/Image
+    --2023-12-19 22:17:54--  https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/Image
+    Resolving git.beagleboard.org (git.beagleboard.org)... 44.226.162.25
+    Connecting to git.beagleboard.org (git.beagleboard.org)|44.226.162.25|:443... connected.
+    HTTP request sent, awaiting response... 200 OK
+    Length: 32172544 (31M) [application/octet-stream]
+    Saving to: ‘Image’
+
+    Image               100%[===================>]  30.68M  1.78MB/s    in 18s     
+
+    2023-12-19 22:18:13 (1.74 MB/s) - ‘Image’ saved [32172544/32172544]
+
+    debian@BeaglePlay:~$ sudo cp Image /boot/firmware/Image-buildroot
+    [sudo] password for debian:
+    debian@BeaglePlay:~$ wget https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/rootfs.cpio.gz
+    --2023-12-19 22:16:44--  https://git.beagleboard.org/beagleboard/buildroot/-/jobs/19194/artifacts/raw/public/beagleplay/images/rootfs.cpio.gz
+    Resolving git.beagleboard.org (git.beagleboard.org)... 44.226.162.25
+    Connecting to git.beagleboard.org (git.beagleboard.org)|44.226.162.25|:443... connected.
+    HTTP request sent, awaiting response... 200 OK
+    Length: 30111086 (29M) [application/octet-stream]
+    Saving to: ‘rootfs.cpio.gz’
+
+    rootfs.cpio.gz      100%[===================>]  28.72M  21.5MB/s    in 1.3s    
+
+    2023-12-19 22:16:46 (21.5 MB/s) - ‘rootfs.cpio.gz’ saved [30111086/30111086]
+
+    debian@BeaglePlay:~$ sudo cp rootfs.cpio.gz /boot/firmware/rootfs.cpio.gz-buildroot
 
 .. _play-modified-extlinux-conf:
 
@@ -111,48 +133,55 @@ The contents of the initrd can be read using ``lsinitramfs /boot/firmware/initrd
     :linenos:
 
     menu title Select image to boot
-    timeout 30
-    default Linux 6.6
+    timeout 10
+    default Buildroot
 
-    label Linux default
+    label Debian
         kernel /Image
         append root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait net.ifnames=0 quiet
         fdtdir /
         #fdtoverlays /overlays/<file>.dtbo
         initrd /initrd.img
 
-    label Linux 6.6
-        kernel /Image-6.6
-        append root=/dev/mmcblk0p2 ro rootfstype=ext4 rootwait net.ifnames=0 quiet
+    label Buildroot
+        kernel /Image-buildroot
+        append rootwait net.ifnames=0 quiet
         fdtdir /
-        initrd /initrd.img-6.6.0
+        initrd /rootfs.cpio.gz-buildroot
 
 .. _play-boot-modified-kernel:
 
 .. code-block:: shell-session
-    :caption: Reboot into modified kernel
+    :caption: Reboot into modified kernel and rootfs
 
     debian@BeaglePlay:~$ sudo shutdown -r now
     Connection to 192.168.0.117 closed by remote host.
     Connection to 192.168.0.117 closed.
-    jkridner@slotcar:~$ ssh -Y debian@192.168.0.117
-    Debian GNU/Linux 11
-
-    BeagleBoard.org Debian Bullseye Xfce Image 2023-05-18
-    Support: https://bbb.io/debian
-    default username:password is [debian:temppwd]
-
-    debian@192.168.0.117's password: 
-
-    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: Tue Dec 12 15:33:21 2023 from 192.168.0.171
-    debian@BeaglePlay:~$ uname -a
-    Linux BeaglePlay 6.6.0 #4 SMP Tue Dec  5 13:50:59 UTC 2023 aarch64 GNU/Linux
+    jkridner@slotcar:~$ sudo nmap -n -p 22 192.168.0.0/24
+    Starting Nmap 7.94SVN ( https://nmap.org ) at 2023-12-19 17:32 EST
+    ...
+    PORT   STATE SERVICE
+    22/tcp open  ssh
+    MAC Address: 50:3E:AA:AD:78:06 (TP-Link Technologies)
+
+    Nmap scan report for 192.168.0.112
+    Host is up (0.00020s latency).
+    ...
+    jkridner@slotcar:~$ ssh root@192.168.0.112
+    The authenticity of host '192.168.0.112 (192.168.0.112)' can't be established.
+    ED25519 key fingerprint is SHA256:EZdvLkCNMyhy4RhvseUSC5EwaJR5Kgpk8JZG9kF+pmk.
+    This key is not known by any other names.
+    Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
+    Warning: Permanently added '192.168.0.112' (ED25519) to the list of known hosts.
+    root@192.168.0.112's password: 
+    # uname -a
+    Linux BeaglePlay 6.6.3 #1 SMP Tue Dec 19 21:32:06 UTC 2023 aarch64 GNU/Linux
+    # cat /etc/os-release 
+    NAME=Buildroot
+    VERSION=2023.11-beagle1
+    ID=buildroot
+    VERSION_ID=2023.11
+    PRETTY_NAME="Buildroot 2023.11"
 
 
 Booting U-Boot

boards/beagleplay/demos-and-tutorials/using-serial-console.rst

@@ -6,7 +6,7 @@ Using Serial Console
 To see the board boot log and access your BeaglePlay's console you can connect a USB-UART  
 cable as depicted in the image below and use applications like ``tio`` to access the console.
 
-.. figure:: images/serial-debug-connection.jpg
+.. figure:: images/serial-debug-connection.*
     :width: 1400
     :alt: Serial debug (USB-UART) cable connection.