diff --git a/boards/beagley/ai/02-quick-start.rst b/boards/beagley/ai/02-quick-start.rst
index ae7e00d77c51f08ef07b12f69a8c7d9586efdd33..2672c2442d8cd75022e1f35011fe1f905fa491f8 100644
--- 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
diff --git a/books/beaglebone-cookbook/01basics/basics.rst b/books/beaglebone-cookbook/01basics/basics.rst
index 5f8c39b84fef154cf40963d9b735d5f6b786b771..b6fd0beaae38a6a73fec50237469812f19e04a8b 100644
--- 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
-
-Current list of boards: https://git.beagleboard.org/explore/projects/topics/boards
-
-Discussion
------------
+Check out the current list of boards: :ref:`boards`
.. _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
-This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
+.. tab-set::
-.. todo
- Update for 2023-06-03
+ .. tab-item:: bb-imager
-.. _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
- :align: center
- :alt: Latest Debian images
+ .. tab-item:: forum
- 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.
-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.
+ On your host computer, open a browser and go to https://forum.beagleboard.org/tag/latest-images
+ This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
-.. _basics_deb2:
+ .. todo::
-.. figure:: figures/deb2.png
- :align: center
- :alt: Latest Debian images
+ Update for 2023-06-03
+
+ .. _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
-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 *am57xx-debian-* is for programming the Beagle AI's.
+ 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
+ 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.
-.. note::
- 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.
+ .. note::
+ 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.
-Click the image you want to use and it will download.
-The images are some 500M, so it might take a while.
+ Click the image you want to use and it will download.
+ 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
--------
diff --git a/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png b/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png
new file mode 100644
index 0000000000000000000000000000000000000000..45a560d3c9d67afa2974845a2fcc589f39bc9a50
Binary files /dev/null and b/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png differ
diff --git a/books/beaglebone-cookbook/02sensors/figures/pinout.png b/books/beaglebone-cookbook/02sensors/figures/pinout.png
new file mode 100644
index 0000000000000000000000000000000000000000..162a67743f499849b69519143d9d0621951d825d
Binary files /dev/null and b/books/beaglebone-cookbook/02sensors/figures/pinout.png differ
diff --git a/books/beaglebone-cookbook/02sensors/sensors.rst b/books/beaglebone-cookbook/02sensors/sensors.rst
index 71087c50cb762fb035453afe7925d5e77ca17feb..c0d195b6d0e668a0dd3039fa41a3d70c6081ec5d 100644
--- 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.*
- :align: center
- :alt: USB Host Port
+.. tab-set::
- The USB 2.0 host port
+ .. tab-item:: BeagleBone Black
-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_host_port:
-.. _sensors_P8P9_fig:
+ .. figure:: figures/black_hardware_details.*
+ :align: center
+ :alt: USB Host Port
-.. figure:: figures/P8P9_bb.png
- :align: center
- :alt: Cape Headers P8 and P9
+ The USB 2.0 host port
+
+ 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.*
- :align: center
- :alt: Sensor Connection Modes
-
- Some of the many sensor connection options on the Bone
+ .. _sensors_cape_headers:
+
+ .. figure:: figures/cape-headers.*
+ :align: center
+ :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= 1
- data= 1
+ data = 0
+ data = 0
+ 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
- :align: center
- :alt: |I2C| Temp
+ Wire the TMP101, as shown in :ref:`sensors_i2cTemp_fig`.
- Wiring an |I2C| TMP101 temperature sensor
+ .. _sensors_i2cTemp_fig:
-There are two |I2C| buses brought out to the headers.
-:ref:`sensors_cape_headers_i2c`
-shows that you have wired your device to |I2C| bus *2*.
+ .. figure:: figures/i2cTemp_bb.png
+ :align: center
+ :alt: |I2C| Temp
-.. _sensors_cape_headers_i2c:
+ Wiring an |I2C| TMP101 temperature sensor
-.. figure:: figures/cape-headers-i2c.png
- :align: center
- :alt: Table of |I2C| outputs
+ There are two |I2C| buses brought out to the headers.
+ :ref:`sensors_cape_headers_i2c`
+ 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
-.. 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.
+.. todo:: Update for BeagleY-AI
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.
diff --git a/books/beaglebone-cookbook/04motors/figures/pwm.png b/books/beaglebone-cookbook/04motors/figures/pwm.png
new file mode 100644
index 0000000000000000000000000000000000000000..7d6fc18af74584d453e4f80beafda365e732ddcb
Binary files /dev/null and b/books/beaglebone-cookbook/04motors/figures/pwm.png differ
diff --git a/books/beaglebone-cookbook/04motors/motors.rst b/books/beaglebone-cookbook/04motors/motors.rst
index e9f85273699a4743d6056a9da85d657785416634..09d2b58e92249cd82957be7633754defeab6620e 100644
--- 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.
-
-.. code-block:: bash
-
- bone$ cd ~/beaglebone-cookbook-code/04motors
- bone$ config-pin P9_16 pwm
- bone$ ./servoMotor.py
+in :ref:`py_servoMotor_code`.
.. 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.
diff --git a/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg b/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..b747916a0b2ffe41b4acbca003ba40390b2e5214
Binary files /dev/null and b/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg differ
diff --git a/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg b/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..6a40e2d116c5d628e6d1a4a42ecc558d64db6cae
Binary files /dev/null and b/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg differ
diff --git a/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg b/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..e8b1ae61c7123527927b32018f058ae47487709d
Binary files /dev/null and b/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg differ
diff --git a/books/beaglebone-cookbook/05tips/tips.rst b/books/beaglebone-cookbook/05tips/tips.rst
index 30c4d831a7f25d6266815bd5c64293bc3feb01f6..8da817b52d31b4edd85eb988037fc6743157d762 100644
--- 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
-: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.
+ .. tab-item:: BeagleBone
-.. _tips_black_hardware_details_fig:
-.. figure:: figures/FTDIPins.png
- :align: center
- :alt: Serial Debug Pins
+ Next, look for the FTDI pins of the Bone (labeled *J1* on the Bone), shown in
+ :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
+ :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
-the ``triangle`` pin on the connector to the ``white dot`` pin of the *FTDI* connector.
+ .. figure:: figures/jst-fdti.jpg
+ :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
diff --git a/books/beaglebone-cookbook/06iot/iot.rst b/books/beaglebone-cookbook/06iot/iot.rst
index 2b06b712d63ac39a7ed21897213fec8795cf4d8a..7c6f4a8143951fe447e1fbfeb6828cdec6109efb 100644
--- 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