Merge branch 'updateBasics' into 'main'

Update basics See merge request docs/docs.beagleboard.io!159

Merge branch 'updateBasics' into 'main'
Update basics See merge request docs/docs.beagleboard.io!159
3c8c182a · Deepak Khatri · d4f10464 · 7b18c00a · 3c8c182a · 3c8c182a
Commit 3c8c182a authored 5 months ago by Deepak Khatri
--- a/boards/beagley/ai/02-quick-start.rst
+++ b/boards/beagley/ai/02-quick-start.rst
@@ -321,7 +321,7 @@ Headless connection
 If you want to run your BeagleY-AI in headless mode, you need `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_ 
 or similar serial (USB to UART) adapter. Connect your UART debug probe to BeagleY-AI as shown in the image below. After making the connection you can use command 
-line utility like ``tio`` on Linux of Putty on any operating system. Check :ref:`beagley-ai-uart-connection` for more information.
+line utility like ``tio`` on Linux or Putty on any operating system. Check :ref:`beagley-ai-uart-connection` for more information.
 .. figure:: images/uart/rpi-debug-probe-connection.*
    :align: center

--- a/books/beaglebone-cookbook/01basics/basics.rst
+++ b/books/beaglebone-cookbook/01basics/basics.rst
@@ -20,12 +20,7 @@ There are many different BeagleBoards. How do you pick which one to use?
 Solution
 ---------
-.. todo
+Check out the current list of boards: :ref:`boards`
-Current list of boards: https://git.beagleboard.org/explore/projects/topics/boards
-Discussion
-----------
 .. _basics_out_of_the_box:
@@ -40,6 +35,11 @@ You just got your Bone, and you want to know what to do with it.
 Solution
 ---------
+Many of the Beagles (:ref:`beagley-all-home`, :ref:`beagleplay-home`, 
+:ref:`bbai64-home`, :ref:`bbai-home`, :ref:`beaglev-ahead-home` and
+:ref:`beaglev-fire-home`)
+have their own detailed **Quick start** guide.  Here we present
+general instructions that work for all Beagles. 
 Fortunately, you have all you need to get running: your Bone and a USB cable. 
 Plug the USB cable into your host computer (Mac, Windows, or Linux) and plug the 
 mini-USB connector side into the USB connector near the Ethernet connector on 
@@ -86,7 +86,7 @@ Wait a minute and try the URL again.
   Visual Studio Code
 Here, you'll find *Visual Studio Code*, a web-based integrated development environment (IDE) 
-that lets you edit and run code on your Bone!  See :ref: `basics_vsc` for more details.
+that lets you edit and run code on your Bone!  See :ref:`basics_vsc` for more details.
 .. WARNING:: 
    Make sure you turn off your Bone properly. 
@@ -132,19 +132,23 @@ following the instructions in :ref:`basics_out_of_the_box` to log into the Bone.
 .. code-block:: bash
    bone$ cat /etc/dogtag
-    BeagleBoard.org Debian Bullseye IoT Image 2023-06-03
+    BeagleBoard.org Debian Bookworm Minimal Image 2024-09-11
-I'm running the 2023-06-03 version.
+I'm running the **2024-09-11** version.
-Running the Python and JavaScript Examples
+Running the Python Examples
-===========================================
+===========================
 Problem
 --------
-You'd like to learn Python or JavaScript interact with the Bone to 
+You'd like to learn Python to interact with the Bone to 
 perform physical computing tasks without first learning Linux.
+.. note:: 
+   There are many JavaScript examples too, but they may not be as up to date as the Python examples.
 Solution
 ---------
@@ -154,6 +158,10 @@ http://192.168.7.2:3000 using Google Chrome or Firefox (as shown in
 column, click on *examples*, then *BeagleBone* and then *Black*. 
 Several sample scripts will appear.  Go and explore them.
+.. todo
+   examples are no longer on the board.
 .. tip::
    Explore the various demonstrations of Python and JavaScript. These are what come with the Bone. 
@@ -307,44 +315,56 @@ You want to find out the latest version of Debian that is available for your Bon
 Solution
 ************
-On your host computer, open a browser and go to https://forum.beagleboard.org/tag/latest-images 
+.. tab-set::
-This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
-.. todo 
+   .. tab-item:: bb-imager
-   Update for 2023-06-03
-.. _basics_deb1:
+      The easiest way to see what the current images are and update your SD card
+      is to use **bb-imager**.  :ref:`beagley-ai-bb-imager` gives details on how to us it.
-.. figure:: figures/deb1.png
+   .. tab-item:: forum
-   :align: center
-   :alt: Latest Debian images
-   Latest Debian images
+      Another way to see the available images is to visit the beagleboard forum. 
-At the time of writing, we are using the *Bullseye* image.  
+      On your host computer, open a browser and go to https://forum.beagleboard.org/tag/latest-images 
-Click on its link. Scrolling up you'll find :ref:`basics_deb2`. 
+      This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
-There are three types of snapshots, Minimal, IoT and Xfce Desktop. 
-IoT is the one we are running.
-.. _basics_deb2:
+      .. todo::
-.. figure:: figures/deb2.png
+         Update for 2023-06-03
-   :align: center
-   :alt: Latest Debian images
+      .. _basics_deb1:
+      .. figure:: figures/deb1.png
+         :align: center
+         :alt: Latest Debian images
+         Latest Debian images
+      At the time of writing, we are using the *Bullseye* image.  
+      Click on its link. Scrolling up you'll find :ref:`basics_deb2`. 
+      There are three types of snapshots, Minimal, IoT and Xfce Desktop. 
+      IoT is the one we are running.
+      .. _basics_deb2:
+      .. figure:: figures/deb2.png
+         :align: center
+         :alt: Latest Debian images
-   Latest Debian images
+         Latest Debian images
-These are the images you want to use if you are flashing a Rev C BeagleBone Black 
+      These are the images you want to use if you are flashing a Rev C BeagleBone Black 
-onboard flash, or flashing a 4 GB or bigger miscroSD card. The image beginning 
+      onboard flash, or flashing a 4 GB or bigger miscroSD card. The image beginning 
-with *am335x-debian-11.3-iot-* is used for the non-AI boards. The one beginning 
+      with *am335x-debian-11.3-iot-* is used for the non-AI boards. The one beginning 
-with *am57xx-debian-* is for programming the Beagle AI's.
+      with *am57xx-debian-* is for programming the Beagle AI's.
-.. note::
+      .. note::
-   The onboard flash is often called the *eMMC* memory. We just call it *onboard flash*, but you'll 
+         The onboard flash is often called the *eMMC* memory. We just call it *onboard flash*, but you'll 
-   often see *eMMC* appearing in filenames of images used to update the onboard flash.
+         often see *eMMC* appearing in filenames of images used to update the onboard flash.
-Click the image you want to use and it will download. 
+      Click the image you want to use and it will download. 
-The images are some 500M, so it might take a while.
+      The images are some 500M, so it might take a while.
 .. _basics_install_os:
@@ -423,7 +443,8 @@ Problem
 --------
 You've modified the state of your Bone 
-in a way that you'd like to preserve or share.
+in a way that you'd like to preserve or share.  Note, this doesn't apply to boards that
+don't have onboard flash (PocketBeagle and BeagleY-AI).
 Solution
 ---------
@@ -462,6 +483,8 @@ Problem
 --------
 You want to copy the microSD card to the onboard flash.
+Note, this doesn't apply to boards that
+don't have onboard flash (PocketBeagle and BeagleY-AI).
 Solution
 --------

--- a/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png
+++ b/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png
--- a/books/beaglebone-cookbook/02sensors/figures/pinout.png
+++ b/books/beaglebone-cookbook/02sensors/figures/pinout.png
--- a/books/beaglebone-cookbook/02sensors/sensors.rst
+++ b/books/beaglebone-cookbook/02sensors/sensors.rst
@@ -7,6 +7,12 @@ Sensors
 .. |ohm| replace:: Ω
 .. |deg| replace:: °
+.. note:: 
+   Although the examples given here are originally for the BeagleBone Black, many will also
+   work on the other Beagles too.  See the `tabs` for details on running the examples
+   on other boards.
 In this chapter, you will learn how to sense the physical world with BeagleBone Black. 
 Various types of electronic sensors, such as cameras and microphones, can be connected 
 to the Bone using one or more interfaces provided by the standard USB 2.0 host port, 
@@ -17,25 +23,42 @@ as shown in :ref:`sensors_host_port`.
   All the examples in the book assume you have cloned the Cookbook 
   repository on git.beagleboard.org. Go here :ref:`basics_repo` for instructions.
-.. _sensors_host_port:
-.. figure:: figures/black_hardware_details.*
+.. tab-set::
-   :align: center
-   :alt: USB Host Port
-   The USB 2.0 host port
+   .. tab-item:: BeagleBone Black
-The two 46-pin cape headers (called *P8* and *P9*) along the long 
+      .. _sensors_host_port:
-edges of the board (:ref:`sensors_P8P9_fig`) provide connections for 
-cape add-on boards, digital and analog sensors, and more.
-.. _sensors_P8P9_fig:
+      .. figure:: figures/black_hardware_details.*
+         :align: center
+         :alt: USB Host Port
-.. figure:: figures/P8P9_bb.png
+         The USB 2.0 host port
-   :align: center
-   :alt: Cape Headers P8 and P9
+      The two 46-pin cape headers (called *P8* and *P9*) along the long 
+      edges of the board (:ref:`sensors_P8P9_fig`) provide connections for 
+      cape add-on boards, digital and analog sensors, and more.
+      .. _sensors_P8P9_fig:
+      .. figure:: figures/P8P9_bb.png
+         :align: center
+         :alt: Cape Headers P8 and P9
+         Cape Headers P8 and P9
+   .. tab-item:: BeagleY-AI
-   Cape Headers P8 and P9
+      .. figure:: figures/beagleY-ai-front.png
+         :align: center
+         :alt: BeagleY-AI Front View
+         BeagleY-AI Front View
+      The 40-pin hat header along the long 
+      edge of the board provides connections for 
+      hat add-on boards, digital and analog sensors, and more.
 The simplest kind of sensor provides a single digital status, such as off or on, 
 and can be handled by an *input mode* of one of the Bone's 65 general-purpose input/output 
@@ -59,15 +82,43 @@ You want to acquire and attach a sensor and need to understand your basic option
 Solution
 --------
-:ref:`sensors_cape_headers` shows many of the possibilities for connecting a sensor.
+.. tab-set::
-.. _sensors_cape_headers:
+   .. tab-item:: BeagleBones
+      :ref:`sensors_cape_headers` shows many of the possibilities for connecting a sensor.
-.. figure:: figures/cape-headers.*
+      .. _sensors_cape_headers:
-   :align: center
-   :alt: Sensor Connection Modes
+      .. figure:: figures/cape-headers.*
+         :align: center
-   Some of the many sensor connection options on the Bone
+         :alt: Sensor Connection Modes
+         Some of the many sensor connection options on the Bone.
+   .. tab-item:: BeagleY-AI
+      :ref:`sensors_hat_headers` shows many of the possibilities for connecting a sensor.
+      You will see pins referenced in several ways. While this is confusing at first, in reality, 
+      we can pick our favorite way and stick to it.
+      The two main ways of referring to GPIOs is **by their number**, so GPIO2, GPIO3, GPIO4 etc. 
+      as seen in the diagram below. This corresponds
+      to the SoC naming convention. For broad compatibility, BeagleY-AI re-uses the Broadcom GPIO numbering scheme used by RaspberryPi. 
+      The second (and arguably easier) way we will use for this tutorial is to use the **actual pin header number** (shown in dark grey).  So, for the rest of the tutorial, if we refer to **hat-08-gpio** we mean the **8th pin of the GPIO header**. Which, if you referenced
+      the image below, can see refers to **GPIO14 (UART TXD)**
+      .. _sensors_hat_headers:
+      .. figure:: figures/pinout.png
+         :align: center
+         :alt: BeagleY-AI pinout
+         BeagleY-AI pinout
+      Go to https://pinout.beagleboard.io/ to see an interactive version  of the figure.
 Choosing the simplest solution available enables you to move on quickly to 
 addressing other system aspects. By exploring each connection type, you can 
@@ -127,13 +178,14 @@ By default, it takes you to your home directory. Notice that the prompt has chan
 .. code-block:: bash
  debian@beaglebone:beaglebone-cookbook/code/02sensors$ ./pushbutton.py
-  data= 0
+  data = 0
-  data= 0
+  data = 0
-  data= 1
+  data = 1
-  data= 1
+  data = 1
  ^C
 This process will work for any script in this book.
+(See the following sections for instructions on how to wire the pushbutton.)
 .. _sensors_pushbutton:
@@ -169,6 +221,11 @@ or both on the Bone, as shown in :ref:`js_pushbutton_fig`.
 The code below reads GPIO port *P9_42*, which is attached to the pushbutton. 
+.. note:: 
+   If you are using a BeagleY-AI, wire the button to **GPIO23** which is **hat-16**.  
+   This also appears at **gpiochip0** and line **7**.
 .. tab-set::
   .. tab-item:: Python
@@ -230,7 +287,9 @@ You have a sensor attached to the P8 or P9 header and need to know which gpio pi
 Solution
 ---------
-The *gpioinfo* command displays information about all the P8 and P9 header pins. To see the info for just one pin, use *grep*.
+The *gpioinfo* command displays information about all the P8 and P9 header pins. 
+(Or the HAT header pins if you are on the BeagleY-AI.)
+To see the info for just one pin, use *grep*.
 .. code-block:: bash
@@ -241,7 +300,17 @@ The *gpioinfo* command displays information about all the P8 and P9 header pins.
  gpiochip2 - 32 lines:
  gpiochip3 - 32 lines:
-This shows P9_42  is on  chip 0 and pin 7.  To find the gpio number multiply 
+Or, if on the BeagleY-AI.
+.. code-block:: bash
+  bone$ gpioinfo | grep -e chip -e GPIO23
+  gpiochip0 - 24 lines:
+      line   7:     "GPIO23"       unused   input  active-high 
+   gpiochip1 - 87 lines:
+   gpiochip2 - 73 lines:
+This shows P9_42 (GPIO32) is on  chip 0 and pin 7.  To find the gpio number multiply 
 the chip number by 32 and add it to the pin number.  This gives 0*32+7=7.  
 For P9_26 you get:
@@ -270,6 +339,10 @@ and you want to read their value with the Bone.
 Solution
 --------
+.. note:: 
+   The BeagleY-AI doesn't have ADC's, so you can skip this section.
 Use the Bone's analog-to-digital converters (ADCs) and a resistor 
 divider circuit to detect the resistance in the sensor.
@@ -366,6 +439,10 @@ which outputs a voltage in proportion to the distance.
 Solution
 --------
+.. note:: 
+   The BeagleY-AI doesn't have ADC's, so you can skip this section.
 To make this recipe, you will need:
 * Breadboard and jumper wires.
@@ -474,6 +551,10 @@ Accurately Reading the Position of a Motor or Dial
 Problem
 --------
+.. todo::
+   Update for BeagleY-AI
 You have a motor or dial and want to detect rotation using a rotary encoder.
 Solution
@@ -684,28 +765,54 @@ To make this recipe, you will need:
 * Two 4.7 |kohm| resistors.
 * TMP101 temperature sensor.
-Wire the TMP101, as shown in :ref:`sensors_i2cTemp_fig`.
+.. tab-set::
-.. _sensors_i2cTemp_fig:
+   .. tab-item:: BeagleBone
-.. figure:: figures/i2cTemp_bb.png
+      Wire the TMP101, as shown in :ref:`sensors_i2cTemp_fig`.
-   :align: center
-   :alt: |I2C| Temp
-   Wiring an |I2C| TMP101 temperature sensor
+      .. _sensors_i2cTemp_fig:
-There are two |I2C| buses brought out to the headers. 
+      .. figure:: figures/i2cTemp_bb.png
-:ref:`sensors_cape_headers_i2c` 
+         :align: center
-shows that you have wired your device to |I2C| bus *2*.
+         :alt: |I2C| Temp
-.. _sensors_cape_headers_i2c:
+         Wiring an |I2C| TMP101 temperature sensor
-.. figure:: figures/cape-headers-i2c.png
+      There are two |I2C| buses brought out to the headers. 
-   :align: center
+      :ref:`sensors_cape_headers_i2c` 
-   :alt: Table of |I2C| outputs
+      shows that you have wired your device to |I2C| bus *2*.
+      .. _sensors_cape_headers_i2c:
+      .. figure:: figures/cape-headers-i2c.png
+         :align: center
+         :alt: Table of |I2C| outputs
+         Table of |I2C| outputs
+   .. tab-item:: BeagleY-AI
-   Table of |I2C| outputs
+      Running the following on the BeagleY-AI shows it has five i2c buses.
+      .. code-block:: shell-session
+         bone$ ls /sys/bus/i2c/devices/
+         2-0030  2-0050  2-0068  4-004c  i2c-1  i2c-2  i2c-3  i2c-4  i2c-5
+      But running https://pinout.beagleboard.io/ show only buses 1 and 4 are exposed on the HAT header.
+      Here we'll use bus 2 whose clock appears on `hat-03` and data on `hat-05`.
+      Wire your **tmp101** as shown in the table.
+      ======== === ======
+      Function hat tmp101
+      ======== === ======
+      Ground   09  2
+      3.3V     01  5
+      data     03  6
+      clock    05  1
+      ======== === ======
 Once the |I2C| device is wired up, you can use a couple handy |I2C| 
 tools to test the device. Because these are Linux command-line tools, 
@@ -716,13 +823,18 @@ the value. It returns the temperature in hexadecimal and degrees C.
 In this example, 0x18 = 24{deg}C, which is 75.2{deg}F. (Hmmm, the office is a bit warm today.) 
 Try warming up the TMP101 with your finger and running *i2cget* again.
-.. todo:: fix deg
+.. todo:: 
+   fix deg
 .. _js_i2cTools:
 |I2C| tools
 ============
+One way to see what devices are on a given |I2C| bus is to use `i2cdetect`.
+Here is bus 2 on the BeagleBone.
 .. code-block:: bash
  bone$ i2cdetect -y -r 2
@@ -739,6 +851,23 @@ Try warming up the TMP101 with your finger and running *i2cget* again.
  bone$ i2cget -y 2 0x49
    0x18
+Here is bus 1 on the BeagleY-AI.
+.. code-block:: bash
+  bone$ i2cdetect -y -r 1
+    0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
+    00:          -- -- -- -- -- -- -- -- -- -- -- -- -- 
+    10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
+    20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
+    30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
+    40: -- -- -- -- -- -- -- -- -- 49 -- -- -- -- -- -- 
+    50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
+    60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
+    70: -- -- -- -- -- -- -- --
+  bone$ i2cget -y 1 0x49
+    0x18
 Reading the temperature via the kernel driver
 ==============================================
@@ -747,6 +876,10 @@ The cleanest way to read the temperature from at TMP101 sensor is to use the ker
 Assuming the TMP101 is on bus 2 (the last digit is the bus number)
+.. note:: 
+   Switch bus 2 to bus 1 if you are using the BeagleY-AI.
 .. _js_i2cKernel:
 |I2C| TMP101 via Kernel
@@ -773,8 +906,13 @@ Assuming the TMP101 is at address 0x49
 .. code-block:: bash
-  bone$ echo tmp101 0x49 > new_device
+   bone$ echo tmp101 0x49 > new_device
+.. note:: 
+   If this returns `new_device: Permission denied`, you will need to run the following first.
+      bone$ sudo chown debian:gpio *
 This tells the kernel you have a TMP101 sensor at address 0x49. Check the log to be sure.
@@ -854,8 +992,7 @@ using the kernel driver. First you need to install the i2c module.
 .. code-block:: bash
-  bone$ pip install smbus
+  bone$ sudo apt install python3-smbus
 .. _js_i2ctmp101_code:
@@ -881,12 +1018,7 @@ You want to measure a temperature using a Dallas Semiconductor DS18B20 temperatu
 Solution
 ---------
-.. I need to double-check how we provide attribution for recipes, but we'll need to have 
+.. todo::  Update for BeagleY-AI
-.. something more than "From" followed by a link. For now, we should at least do 
-.. something like what I've changed it to. --BS
-.. --may A bigger question is, when do we need attribution?  
-.. I pull bits and pieces from everywhere and try to keep good records of sources.
 The DS18B20 is an interesting temperature sensor that uses Dallas 
 Semiconductor's 1-wire interface. The data communication requires only 
@@ -1124,7 +1256,13 @@ such as the one shown in :ref:`usb_audio_dongle`.
  A USB audio dongle
 Drivers for the `Advanced Linux Sound Architecture <http://bit.ly/1MrAJUR>`_ (ALSA) 
-are already installed on the Bone. You can list the recording and playing devices on 
+may already installed on the Bone. If not, run the following:
+.. code-block:: bash
+   bone$ sudo apt install alsa-utils
+You can list the recording and playing devices on 
 your Bone by using *aplay* and *arecord*, as shown in :ref:`sensors_alsa`. BeagleBone Black 
 has audio-out on the HDMI interface. It's listed as *card 0* in 
 :ref:`sensors_alsa`. *card 1* is my USB audio adapter's audio out.

--- a/books/beaglebone-cookbook/04motors/figures/pwm.png
+++ b/books/beaglebone-cookbook/04motors/figures/pwm.png
--- a/books/beaglebone-cookbook/04motors/motors.rst
+++ b/books/beaglebone-cookbook/04motors/motors.rst
@@ -83,13 +83,7 @@ Wire up your servo, as shown in :ref:`motors_servoMotor`.
    Driving a servo motor with the 3.3 V power supply
 The code for controlling the servo motor is in ``servoMotor.py``, shown 
-in :ref:`py_servoMotor_code`. You need to configure the pin for PWM.
+in :ref:`py_servoMotor_code`. 
-.. code-block:: bash
-    bone$ cd ~/beaglebone-cookbook-code/04motors
-    bone$ config-pin P9_16 pwm
-    bone$ ./servoMotor.py
 .. tab-set::
@@ -115,6 +109,85 @@ in :ref:`py_servoMotor_code`. You need to configure the pin for PWM.
        :download:`servoMotor.js <../code/04motors/servoMotor.js>`
+You need to configure the pin for PWM.
+.. tab-set::
+    .. tab-item:: BeagleBone
+        .. code-block:: bash
+            bone$ cd ~/beaglebone-cookbook-code/04motors
+            bone$ config-pin P9_16 pwm
+            bone$ ./servoMotor.py
+    .. tab-item:: BeagleY-AI
+        Configuring the PWM on the BeagleY-AI takes a little more effort than on the Bone.
+        First select which PWM you want to use. https://pinout.beagleboard.io/pinout/pwm
+        shows you have many to choose from. 
+        .. figure:: figures/pwm.png
+            :align: center
+            :alt: BeagleY-AI PWMs
+            BeagleY-AI PWMs
+        Let's use **PWM0** on **GPIO12**.  Note this is Hat pin 32 as shown in the figure (**hat-32**).
+        The instructions at :ref:`beagley-ai-using-pwm` give details on how to configure the PWM pin. A shorter version is given here.
+        To enable any of the PWM Pins, we have to modify the file: ``/boot/firmware/extlinux/extlinux.conf``. We can check the available list of Device Tree Overlays using the command:
+        .. code:: console
+            debian@BeagleBone:~$ ls /boot/firmware/overlays/ | grep "beagley-ai-pwm"
+            k3-am67a-beagley-ai-pwm-ecap0-gpio12.dtbo
+            k3-am67a-beagley-ai-pwm-ecap1-gpio16.dtbo
+            k3-am67a-beagley-ai-pwm-ecap1-gpio21.dtbo
+            ...
+        Add the line shown below to ``/boot/firmware/extlinux/extlinux.conf`` to load the gpio12 pwm device tree overlay:
+        .. code:: bash
+            fdtoverlays /overlays/k3-am67a-beagley-ai-pwm-epwm0-ecap0-gpio12.dtbo
+        Your ``/boot/firmware/extlinux/extlinux.conf`` file should look something like:
+        .. code:: bash
+            label microSD (default)
+                kernel /Image
+                append console=ttyS2,115200n8 root=/dev/mmcblk1p3 ro rootfstype=ext4 resume=/dev/mmcblk1p2 rootwait net.ifnames=0 quiet
+                fdtdir /
+                fdt /ti/k3-am67a-beagley-ai.dtb
+                fdtoverlays /overlays/k3-am67a-beagley-ai-pwm-ecap0-gpio12.dtbo
+                initrd /initrd.img
+        Now reboot you BeagleY-AI to load the overlay:
+        .. code:: console
+            beagle$ sudo reboot
+        To configure HAT pin32 (GPIO12) PWM symlink pin using ``beagle-pwm-export`` execute the command below,
+        .. code:: console
+            beagle$ sudo beagle-pwm-export --pin hat-32
+        We've changed the PWM pin that's being used so we need to modfiy ``servoMotor.py``.  
+        Around line 16 you will see:
+            PWMPATH='/dev/bone/pwm/'+pwm+'/'+channel
+        Change it to:
+            PWMPATH='/dev/hat/pwm/GPIO12'
+        Now run your code:
+            beagle$ ./servoMotor.py
 Running the code causes the motor to move back and forth, progressing to successive  
 positions between the two extremes.  You will need to press ^C (Ctrl-C) to stop the script.

--- a/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg
+++ b/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg
--- a/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg
+++ b/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg
--- a/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg
+++ b/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg
--- a/books/beaglebone-cookbook/05tips/tips.rst
+++ b/books/beaglebone-cookbook/05tips/tips.rst
@@ -153,7 +153,7 @@ Solution
 However, the Bone has Secure Shell (SSH) enabled right out of the box, so you can easily 
 connect by using the following command to log in as user *debian*, (note the *$* at the end of the prompt):
-.. code-block:: bash
+.. code-block:: shell-session
   host$ ssh debian@192.168.7.2
   Warning: Permanently added '192.168.7.2' (ED25519) to the list of known hosts.
@@ -180,7 +180,7 @@ Default password
 *debian* has the default password *temppwd*. It's best to change the password:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ password
   Changing password for debian.
@@ -203,7 +203,7 @@ Solution
 The contents of the files `/etc/motd`, `/etc/issue` and `/etc/issue.net` are displayed 
 everytime you long it.  You can prevent them from being displayed by moving them elsewhere.
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo mv /etc/motd /etc/motd.orig
   bone$ sudo mv /etc/issue /etc/issue.orig
@@ -234,7 +234,7 @@ shows a way that works even if you don't have a network working over USB, but it
 First, check to ensure that the serial port is there. On the host computer, run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ ls -ls /dev/ttyACM0
   0 crw-rw---- 1 root dialout 166, 0 Jun 19 11:47 /dev/ttyACM0
@@ -244,14 +244,14 @@ First, check to ensure that the serial port is there. On the host computer, run
 The letters *crw-rw----* show that you can't access it as a normal user. However, you can 
 access it if you are part of *dialout* group. See if you are in the *dialout* group:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ groups
   yoder adm tty uucp dialout cdrom sudo dip plugdev lpadmin sambashare
 Looks like I'm already in the group, but if you aren't, just add yourself to the group:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ sudo adduser $USER dialout
@@ -259,7 +259,7 @@ Looks like I'm already in the group, but if you aren't, just add yourself to the
 You have to run *adduser* only once. Your host computer will remember the next 
 time you boot up. Now, install and run the *screen* command:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ sudo apt install screen
   host$ screen /dev/ttyACM0 115200
@@ -316,6 +316,7 @@ To make this recipe, you will need:
 Look for a small triangle at the end of the FTDI cable (:ref:`tips_FTDIconnector_fig`). 
 It's often connected to the black wire. 
 .. _tips_FTDIconnector_fig:
 .. figure:: figures/FTDIconnector.jpg
@@ -323,25 +324,63 @@ It's often connected to the black wire.
   :alt: FTDI Connector
   FTDI connector
+.. tab-set::
-Next, look for the FTDI pins of the Bone (labeled *J1* on the Bone), shown in 
+   .. tab-item:: BeagleBone
-:ref:`tips_black_hardware_details_fig`. They are next to the P9 header 
-and begin near pin 20. There is a white dot near P9_20. 
-.. _tips_black_hardware_details_fig:
-.. figure:: figures/FTDIPins.png
+      Next, look for the FTDI pins of the Bone (labeled *J1* on the Bone), shown in 
-   :align: center
+      :ref:`tips_black_hardware_details_fig`. They are next to the P9 header 
-   :alt: Serial Debug Pins
+      and begin near pin 20. There is a white dot near P9_20. 
+      .. _tips_black_hardware_details_fig:
+      .. figure:: figures/FTDIPins.png
+         :align: center
+         :alt: Serial Debug Pins
+         FTDI pins for the FTDI connector 
+      Plug the FTDI connector into the FTDI pins, being sure to connect 
+      the ``triangle`` pin on the connector to the ``white dot`` pin of the *FTDI* connector.
+   .. tab-item:: BeagleY-AI FTDI Cable
+      When using the BeagleY-AI, if you already have an FTDI cable,
+      all you'll need is a JST SH Compatible 1mm Pitch 3 Pin to Male Headers Cable
+      (https://www.adafruit.com/product/5755).
+      .. figure:: figures/jst-sh-3-pin.jpg
+         :align: center
+         :alt:    JST SH to 3 Pin Male
-   FTDI pins for the FTDI connector 
+         JST SH Compatible 1mm Pitch 3 Pin to Male Headers Cable
+      Attach the JST cable to the FTDI cable as shown below.
-Plug the FTDI connector into the FTDI pins, being sure to connect 
+      .. figure:: figures/jst-fdti.jpg
-the ``triangle`` pin on the connector to the ``white dot`` pin of the *FTDI* connector.
+         :align: center
+         :alt: JST to FDTI connection
+         JST to FDTI connection
+   .. tab-item:: BeagleY-AI Debug Probe
+      If you don't have an FTDI cable, you can use a 
+      `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_ 
+      or similar serial (USB to UART) adapter. Connect your UART debug probe to BeagleY-AI as shown in the image below. After making the connection you can use command 
+      line utility like ``tio`` on Linux or Putty on any operating system. Check :ref:`beagley-ai-headless` for more information.
+      .. figure:: figures/rpi-debug-probe-connection.*
+         :align: center
+         :alt: Connecting Raspberry Pi debug probe to BeagleY-AI
+         Connecting Raspberry Pi debug probe to BeagleY-AI
 Now, run the following commands on your host computer:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ ls -ls /dev/ttyUSB0
   0 crw-rw---- 1 root dialout 188, 0 Jun 19 12:43 /dev/ttyUSB0
@@ -374,7 +413,7 @@ Solution
 Log in to your Bone and enter the following command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ cat /etc/dogtag
   BeagleBoard.org Debian Bullseye IoT Image 2023-06-03
@@ -399,7 +438,7 @@ Install and run a Virtual Network Computing (VNC) server:
 .. todo  
   Check this with desktop installed
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt update
   bone$ sudo apt install tightvncserver
@@ -473,7 +512,7 @@ Click Connect to start graphical access to your Bone, as shown in :ref:`tips_vnc
 .. todo  
   This isn't working as of 8-June-2023
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ bone$ sudo apt install bbb.io-xfce4-desktop
   bone$ sdo cp /etc/bbb.io/templates/fbdev.xorg.conf /etc/X11/xorg.conf
@@ -585,7 +624,7 @@ Solution
 The Bone comes with a number of editors. The simplest to learn is *nano*. 
 Just enter the following command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ nano file
@@ -642,7 +681,7 @@ it will automatically assign an IP address to the Bone.
 To find the IP address, open a terminal window and run the *ip* command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ ip a
   1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
@@ -748,7 +787,7 @@ First, plug in the WiFi adapter and the 5 V external power supply and reboot.
 Then run *lsusb* to ensure that your Bone found the adapter:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ lsusb
   Bus 001 Device 002: ID 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS 802.11n 
@@ -768,7 +807,7 @@ Then run *lsusb* to ensure that your Bone found the adapter:
 Next, run *networkctl* to find your adapter's name. Mine is 
 called *wlan0*, but you might see other names, such as *ra0*.
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ networkctl
   IDX LINK    TYPE     OPERATIONAL SETUP
@@ -786,7 +825,7 @@ called *wlan0*, but you might see other names, such as *ra0*.
 If no name appears, try *ip a*:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ ip a
   ...
@@ -809,7 +848,7 @@ If no name appears, try *ip a*:
   Next edit the configuration file */etc/wpa_supplicant/wpa_supplicant-wlan0.conf*.
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
@@ -830,7 +869,7 @@ In the file you'll see:
 Change the *ssid* and *psk* entries for your network. Save your file, then run:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo systemctl restart systemd-networkd
   bone$  ip a
@@ -888,7 +927,7 @@ file called ``ipMasquerade.sh`` on your host computer.
 Then, on your host, run the following commands:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ chmod +x ipMasquerade.sh
   host$ ./ipMasquerade.sh eth0
@@ -911,7 +950,7 @@ in :ref:`tips_setDNS` to ``setDNS.sh`` on your host computer.
 Then, on your host, run the following commands:
-.. code-block:: bash
+.. code-block:: shell-session
   host$ chmod +x setDNS.sh
   host$ ./setDNS.sh
@@ -940,7 +979,7 @@ Web servers typically listen to port *80*. First, look up the IP address of your
 .. todo::
   switch to ip address
-.. code-block:: bash
+.. code-block:: shell-session
   host$ ip a
   1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
@@ -967,7 +1006,7 @@ Then run the following, using your host's IP address:
 .. todo:: 
   check this iptables, convert to ufw
-.. code-block:: bash
+.. code-block:: shell-session
   host$ sudo iptables -t nat -A PREROUTING -p tcp -s 0/0 \
        -d 172.31.43.210 --dport 1080 -j DNAT --to 192.168.7.2:80
@@ -997,7 +1036,7 @@ I'll summarize the initial setup here.
 First install and check the status:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt update
   bone$ sudo apt install ufw
@@ -1007,7 +1046,7 @@ First install and check the status:
 Now turn off everything coming in and leave on all outgoing. 
 Note, this won't take effect until *ufw* is enabled.
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo ufw default deny incoming
   bone$ sudo ufw default allow outgoing
@@ -1015,14 +1054,14 @@ Note, this won't take effect until *ufw* is enabled.
 Don't enable yet, make sure *ssh* still has access
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo ufw allow 22
 Just to be sure, you can install *nmap* on your host computer to see what ports are currently open.
-.. code-block:: bash
+.. code-block:: shell-session
   host$ sudo apt update
   host$ sudo apt install nmap
@@ -1041,7 +1080,7 @@ Just to be sure, you can install *nmap* on your host computer to see what ports
 Currently there are three ports visible:  22, 80 and 3000 (visual studio code). 
 Now turn on the firewall and see what happens.
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo ufw enable
   Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
@@ -1062,7 +1101,7 @@ Only port 22 (ssh) is accessible now.
 The firewall will remain on, even after a reboot. Disable it now if you don't want it on.
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo ufw disable
   Firewall stopped and disabled on system startup
@@ -1089,7 +1128,7 @@ Solution
 The easiest way to install more software is to use **apt**:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt update
   bone$ sudo apt install "name of software"
@@ -1102,7 +1141,7 @@ The second command fetches the software and installs it and all packages it depe
 How do you find out what software you can install?  Try running this:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ apt-cache pkgnames | sort > /tmp/list
   bone$ wc /tmp/list
@@ -1118,7 +1157,7 @@ list, one page at a time. Press the space bar to go to the next page. Press **q*
 Suppose that you would like to install an online dictionary (*dict*). Just run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt install dict
@@ -1141,7 +1180,7 @@ Solution
 *apt* has a *remove* option, so you can run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt remove dict
   Reading package lists... Done
@@ -1167,9 +1206,33 @@ You want to move files between the onboard flash and the microSD card.
 Solution
 ---------
+First, make sure your Beagle has eMMC.  Run ``lsblk``.
+.. code-block:: shell-session
+   beagle:~$ lsblk
+   NAME         MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
+   mmcblk1      179:0    0  3.6G  0 disk 
+   └─mmcblk1p1  179:1    0  3.6G  0 part 
+   mmcblk1boot0 179:256  0    2M  1 disk 
+   mmcblk1boot1 179:512  0    2M  1 disk 
+   mmcblk0      179:768  0  7.4G  0 disk 
+   └─mmcblk0p1  179:769  0  7.4G  0 part /
+If the results show ``mmcblk0`` and ``mmcblk1`` like above, you have eMMC and can do the
+rest of this recipe.  If your results are like below, you don't have eMMC.
+.. code-block:: shell-session
+   beagle:~$ lsblk
+   NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
+   mmcblk1     179:0    0  7.5G  0 disk 
+   ├─mmcblk1p1 179:1    0  256M  0 part /boot/firmware
+   └─mmcblk1p2 179:2    0  7.3G  0 part /
 If you booted from the microSD card, run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ df -h
   Filesystem      Size  Used Avail Use% Mounted on
@@ -1198,7 +1261,7 @@ The *ls* command shows what devices are available to mount. Because *mmcblk0* is
 .. todo:: 
   update
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ cd /mnt
   bone$ sudo mkdir onboard
@@ -1219,7 +1282,7 @@ These are the contents of the onboard flash, which can be copied to and from lik
 This same process should also work if you have booted from the onboard flash. When you are done 
 with the onboard flash, you can unmount it by using this command:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo umount /mnt/onboard
@@ -1253,7 +1316,7 @@ things as OpenCV, the Chromium web browser, and some documentation.
 Here's how you can remove these:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt remove bb-node-red-installer (171M)
   bone$ sudo apt autoremove
@@ -1266,7 +1329,7 @@ Discovering big files
 The *du* (disk usage) command offers a quick way to discover big files:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo du -shx /*
   12M	/bin
@@ -1309,7 +1372,7 @@ of things disappeared while the command was running and thus produced some error
 The ``/var`` directory appears to be the biggest user of space at 1.9 GB. You can then run the 
 following command to see what's taking up the space in ``/var``:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo du -sh /var/*
   4.0K	/var/backups
@@ -1329,7 +1392,7 @@ following command to see what's taking up the space in ``/var``:
 A more interactive way to explore your disk usage is by installing *ncdu* (ncurses disk usage):
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ sudo apt install ncdu
   bone$ ncdu /
@@ -1337,7 +1400,7 @@ A more interactive way to explore your disk usage is by installing *ncdu* (ncurs
 After a moment, you'll see the following:
-.. code-block:: bash
+.. code-block:: shell-session
   ncdu 1.15.1 ~ Use the arrow keys to navigate, press ? for help          
   --- / ------------------------------------------------------------------
@@ -1409,7 +1472,7 @@ For this example P9_14 is used, which the table shows in gpio 50.
 Compile and run the code:
-.. code-block:: bash
+.. code-block:: shell-session
   bone$ gcc -o blinkLED blinkLED.c 
   bone$ ./blinkLED

--- a/books/beaglebone-cookbook/06iot/iot.rst
+++ b/books/beaglebone-cookbook/06iot/iot.rst
@@ -764,7 +764,7 @@ Run this by using the following commands:
 .. code-block:: bash
-  bone$ ./weather.js
+  bone$ ./weather.py
  Getting weather
  Temp:  73.72
  Humid: 31