From 0cb472dc5e5dffee6b7436505a29c41437d1bd37 Mon Sep 17 00:00:00 2001
From: Deepak Khatri <lorforlinux@beagleboard.org>
Date: Mon, 5 Sep 2022 19:09:38 +0530
Subject: [PATCH] Update BeagleBone CookBook
---
books/beaglebone-cookbook/01basics/basics.rst | 300 +++++-----
.../beaglebone-cookbook/02sensors/sensors.rst | 562 ++++++++----------
.../03displays/displays.rst | 328 +++++-----
books/beaglebone-cookbook/04motors/motors.rst | 255 ++++----
books/beaglebone-cookbook/05tips/tips.rst | 550 ++++++++---------
books/beaglebone-cookbook/06iot/iot.rst | 560 ++++++++---------
books/beaglebone-cookbook/07kernel/kernel.rst | 298 +++++-----
.../08realtime/realtime.rst | 323 +++++-----
books/beaglebone-cookbook/09capes/capes.rst | 528 ++++++++--------
books/beaglebone-cookbook/10parts/parts.rst | 207 +++----
10 files changed, 1853 insertions(+), 2058 deletions(-)
diff --git a/books/beaglebone-cookbook/01basics/basics.rst b/books/beaglebone-cookbook/01basics/basics.rst
index b85bd045..e60dcd0a 100644
--- a/books/beaglebone-cookbook/01basics/basics.rst
+++ b/books/beaglebone-cookbook/01basics/basics.rst
@@ -4,77 +4,75 @@ Basics
#######
Introduction
-=============
+*************
When you buy BeagleBone Black, pretty much everything you need to get going comes with it.
You can just plug it into the USB of a host computer, and it works. The goal of this
chapter is to show what you can do with your Bone, right out of the box. It has enough
-information to carry through the next three chapters on sensors (:ref:`sensors <beaglebone-cookbook-sensors>`),
-displays (:ref:`display <beaglebone-cookbook-display>`), and motors (:ref:`motors <beaglebone-cookbook-motors>`).
+information to carry through the next three chapters on sensors (:ref:`beaglebone-cookbook-sensors`),
+displays (:ref:`beaglebone-cookbook-displays`), and motors (:ref:`beaglebone-cookbook-motors`).
Picking Your Beagle
----------------------
+=====================
Problem
-*********
+--------
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
+.. todo
+
+Current list of boards: https://git.beagleboard.org/explore/projects/topics/boards
Discussion
-************
+-----------
.. _basics_out_of_the_box:
Getting Started, Out of the Box
----------------------------------
+================================
Problem
-**********
+--------
+
You just got your Bone, and you want to know what to do with it.
Solution
-**********
+---------
+
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
-the Bone, as shown in :ref:`figure below <basics_pluggingIn_fig>`.
+the Bone, as shown in :ref:`basics_pluggingIn_fig`.
.. _basics_pluggingIn_fig:
.. figure:: figures/pluggingIn.jpg
:align: center
:alt: Plugging BeagleBone Black into a USB port
+
+ Plugging BeagleBone Black into a USB port
- Plugging BeagleBone Black into a USB port
-
-The four blue +USER+ LEDs will begin to blink, and in 10 or 15 seconds, you'll see
-a new USB drive appear on your host computer. :ref:`figure below <basics_01gettingStarted_fig>`
+The four blue **USER LEDs** will begin to blink, and in 10 or 15 seconds, you'll see
+a new USB drive appear on your host computer. :ref:`basics_01gettingStarted_fig`
shows how it will appear on a Windows host, and Linux and Mac hosts will look similar.
The Bone acting like a USB drive and the files you see are located on the Bone.
-.. todo::
- Update
-
.. _basics_01gettingStarted_fig:
-The Bone appears as a USB drive
-
.. figure:: figures/01GettingStarted.png
:align: center
:alt: A new USB drive
- A new USB drive
-
+ The Bone appears as a USB drive
.. _basics_open_vsc:
Browse to http://192.168.7.2:3000 from your
-host computer (:ref:`figure below <basics_05gettingStarted_fig>`).
+host computer (:ref:`basics_05gettingStarted_fig`).
.. _basics_05gettingStarted_fig:
@@ -85,22 +83,23 @@ host computer (:ref:`figure below <basics_05gettingStarted_fig>`).
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<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. It's best to run the +halt+ command:
+ Make sure you turn off your Bone properly.
+ It's best to run the *halt* command:
-.. code-block:: bash
-
- bone$ sudo halt
+ .. code-block:: bash
+
+ bone$ sudo halt
- The system is going down for system halt NOW! (pts/0)
+ The system is going down for system halt NOW! (pts/0)
This will ensure that the Bone shuts down correctly. If you just pull the power,
it is possible that open files would not close properly and might become corrupt.
Discussion
-***********
+-----------
The rest of this book goes into the details behind this quick out-of-the-box demo.
Explore your Bone and then start exploring the book.
@@ -108,22 +107,24 @@ Explore your Bone and then start exploring the book.
.. _basics_latest_os:
Verifying You Have the Latest Version of the OS on Your Bone
----------------------------------------------------------------
+=============================================================
Problem
-********
+--------
-You just got BeagleBone Black, and you want to know which version of the operating system it's running.
+You just got BeagleBone Black, and you want to
+know which version of the operating system it's running.
Solution
-*********
+---------
-.. todo:: update version
+.. todo
+ update version
-This book uses https://www.debian.org[Debian], the Linux distribution that currently ships on the Bone.
+This book uses `Debian <https://www.debian.org>`_, the Linux distribution that currently ships on the Bone.
However this book is based on a newer version (BeagleBoard.org Debian Bullseye IoT Image 2022-07-01)
than what is shipping at the time of this writing. You can see which version your Bone is running by
-following the instructions in `basics out of the box<basics_out_of_the_box>` to log into the Bone. Then run:
+following the instructions in :ref:`basics_out_of_the_box` to log into the Bone. Then run:
.. code-block:: bash
@@ -132,21 +133,41 @@ following the instructions in `basics out of the box<basics_out_of_the_box>` to
I'm running the 2022-07-01 version.
-Discussion
-***********
+Running the Python and JavaScript Examples
+===========================================
+
+Problem
+--------
+
+You'd like to learn Python and JavaScript interact with the Bone to
+perform physical computing tasks without first learning Linux.
+
+Solution
+---------
+
+Plug your board into the USB of your host computer and browse to
+http://192.168.7.2:3000 using Google Chrome or Firefox (as shown in
+:ref:`basics_out_of_the_box`). In the left
+column, click on *EXAMPLES*, then *BeagleBone* and then *Black*.
+Several sample scripts will appear. Go and explore them.
+
+.. tip::
+
+ Explore the various demonstrations of Python and JavaScript. These are what come with the Bone.
+ In :ref:`basics_repo` you see how to load the examples for the Cookbook.
.. _basics_repo:
Cloning the Cookbook Repository
-----------------------------------
+================================
Problem
-********
+-------
You want to run the Cookbook examples.
Solution
-**********
+--------
Connect your Bone to the Internet and log into it. From the command line run:
@@ -162,123 +183,95 @@ select BoneCookbook/docs. Then explore. You'll find there is a directory
for each chapter and most chapters have a *code* directory for the sample
scripts and a *figures* directory for the figures.
-Running the Python and JavaScript Examples
---------------------------------------------
-
-Problem
-**********
-
-You'd like to learn Python and JavaScript interact with the Bone to
-perform physical computing tasks without first learning Linux.
-
-Solution
-***********
-
-Plug your board into the USB of your host computer and browse to
-http://192.168.7.2:3000 using Google Chrome or Firefox (as shown in
-:ref:`basics of out of the box <basics_out_of_the_box>`). In the left
-column, click on *EXAMPLES*, then *BeagleBone* and then *Black*.
-Several sample scripts will appear. Go and explore them.
-
-.. tip::
-
- Explore the various demonstrations of Python and JavaScript. These are what come with the Bone.
- In :ref:`basics repo <basics_repo>` you see how to load the examples for the Cookbook.
-
-Discussion
-************
-
-.. _basics_wire_breadboard
+.. _basics_wire_breadboard:
Wiring a Breadboard
----------------------
+====================
Problem
-********
+--------
You would like to use a breadboard to wire things to the Bone.
Solution
-*********
+---------
Many of the projects in this book involve interfacing things to the Bone.
Some plug in directly, like the USB port. Others need to be wired. If it's simple,
-you might be able to plug the wires directly into the +P8+ or +P9+ headers.
+you might be able to plug the wires directly into the *P8* or *P9* headers.
Nevertheless, many require a breadboard for the fastest and simplest wiring.
To make this recipe, you will need:
-- Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
+- Breadboard and jumper wires
-:ref:`Basic breadboard template <basics_breadboard_template>` shows a breadboard wired to the Bone.
-All the diagrams in this book assume that the ground pin (+P9_1+ on the Bone) is wired to the
-negative rail and 3.3 V (+P9_3+) is wired to the positive rail.
+The :ref:`basics_breadboard_template` shows a breadboard wired to the Bone.
+All the diagrams in this book assume that the ground pin (*P9_1* on the Bone) is wired to the
+negative rail and 3.3 V (*P9_3*) is wired to the positive rail.
.. _basics_breadboard_template:
+Breadboard wired to BeagleBone Black
+-------------------------------------
+
.. figure::figures/template_bb.png
:align: center
- :alt: Breadboard wired to BeagleBone Black
-
+ :alt: Breadboard
+
Breadboard wired to BeagleBone Black
-Discussion
-***********
-
.. _basics_vsc:
Editing Code Using Visual Studio Code
---------------------------------------
+======================================
Problem
-********
+--------
You want to edit and debug files on the Bone.
Solution
-*********
+---------
Plug your Bone into a host computer via the USB cable. Open a browser
(either Google Chrome or FireFox will work) on your host computer
-(as shown in :ref:`basics out of box <basics_out_of_the_box>`). After the Bone has booted up,
+(as shown in :ref:`basics_out_of_the_box`). After the Bone has booted up,
browse to http://192.168.7.2:3000 on your host. You will see something
-like :ref:`basic getting started <basics_05gettingStarted_fig>`.
+like :ref:`basics_05gettingStarted_fig`.
Click the *EXAMPLES* folder on the left and then click *BeagleBoard* and then *Black*,
-finally double-click *seqLEDs.py*. You can now edit the file.
+finally double-click ``seqLEDs.py``. You can now edit the file.
.. note::
- If you edit lines 33 and 37 of the _seqLEDs.py_ file (time.sleep(0.25)),
- changing +0.25+ to +0.1+, the LEDs next to the Ethernet port on your
+ If you edit lines 33 and 37 of the ``seqLEDs.py`` file (time.sleep(0.25)),
+ changing *0.25* to *0.1*, the LEDs next to the Ethernet port on your
Bone will flash roughly twice as fast.
-Discussion
-************
-
.. _basics_vsc_IDE:
Running Python and JavaScript Applications from Visual Studio Code
--------------------------------------------------------------------
+===================================================================
Problem
-*********
+--------
You have a file edited in VS Code, and you want to run it.
Solution
-**********
+---------
-VS Code has a +bash+ command window built in at the bottom of the window.
+VS Code has a *bash* command window built in at the bottom of the window.
If it's not there, hit Ctrl-Shift-P and then type *terminal create new*
then hit *Enter*. The terminal will appear at the bottom of the screen.
You can run your code from this window. To do so, add
-*#!/usr/bin/env python* at the top of the file that you want to run and save.
+``#!/usr/bin/env python`` at the top of the file that you want to run and save.
-.. tip:: If you are running JavaScript, replace the word +python+ in the line with *node*.
+.. tip::
+ If you are running JavaScript, replace the word **python** in the line with **node**.
-At the bottom of the VS Code window are a series of tabs (:ref:`basic bsc bash <basics_vscBash_fig>`).
-Click the +TERMINAL+ tab. Here, you have a command prompt.
+At the bottom of the VS Code window are a series of tabs (:ref:`basics_vscBash_fig`).
+Click the *TERMINAL* tab. Here, you have a command prompt.
.. _basics_vscBash_fig:
@@ -300,9 +293,6 @@ The *cd* is the change directory command. After you *cd*,
you are in a new directory. Finally, *./seqLEDs.py* instructs the
python script to run. You will need to press ^C (Ctrl-C) to stop your program.
-Discussion
-************
-
.. _basics_find_image:
Finding the Latest Version of the OS for Your Bone
@@ -317,7 +307,7 @@ 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:`basic deb <basics_deb1>`).
+This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
.. _basics_deb1:
@@ -325,19 +315,21 @@ This shows you a list of dates of the most recent Debian images (:ref:`basic deb
:align: center
:alt: Latest Debian images
+ Latest Debian images
+
At the time of writing, we are using the *Bullseye* image.
-Click on it's link. Scrolling up you'll find :ref:`basic deb<basics_deb2>`.
+Click on it's 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:
-.Latest Debian images
-
.. figure:: figures/deb2.png
:align: center
:alt: 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
@@ -351,22 +343,19 @@ with *am57xx-debian-* is for programming the Beagle AI's.
Click the image you want to use and it will download.
The images are some 500M, so it might take a while.
-Discussion
-************
-
.. _basics_install_os:
Running the Latest Version of the OS on Your Bone
---------------------------------------------------
+==================================================
Problem
-************
+--------
You want to run the latest version of the operating system on your
Bone without changing the onboard flash.
Solution
-************
+---------
This solution is to flash an external microSD card and run the Bone from it.
If you boot the Bone with a microSD card inserted with a valid boot image,
@@ -374,35 +363,35 @@ it will boot from the microSD card. If you boot without the microSD card
installed, it will boot from the onboard flash.
.. tip::
- If you want to reflash the onboard flash memory,
- see :ref:`basic onboard flash <basics_onboard_flash>`.
+
+ If you want to reflash the onboard flash memory, see :ref:`basics_onboard_flash`.
.. note::
+
I instruct my students to use the microSD for booting. I suggest they
keep an extra microSD flashed with the current OS. If they mess up the
one on the Bone, it takes only a moment to swap in the extra microSD,
boot up, and continue running. If they are running off the onboard flash,
it will take much longer to reflash and boot from it.
-Download the image you found in :ref:`basic find image <basics_find_image>`. It's more than 500 MB,
+Download the image you found in :ref:`basics_find_image`. It's more than 500 MB,
so be sure to have a fast Internet connection. Then go to http://beagleboard.org/getting-started#update and
follow the instructions there to install the image you downloaded.
-Discussion
-************
-
Updating the OS on Your Bone
------------------------------
+=============================
Problem
-************
+--------
+
You've installed the latest version of Debian on your Bone
-(:ref:`basic istall os <basics_install_os>``), and you
-want to be sure it's up-to-date.
+(:ref:`basics_install_os`), and you want to be sure it's up-to-date.
Solution
-************
-Ensure that your Bone is on the network and then run the following command on the Bone:
+---------
+
+Ensure that your Bone is on the network and then run the
+following command on the Bone:
.. code-block:: bash
@@ -413,70 +402,83 @@ If there are any new updates, they will be installed.
.. note::
- If you get the error +The following signatures were invalid: KEYEXPIRED 1418840246+,
- see `eLinux support page http://bit.ly/1EXocb6` for advice on how to fix it.
+ If you get the error *The following signatures were invalid: KEYEXPIRED 1418840246*,
+ see `eLinux support page <http://bit.ly/1EXocb6>`_ for advice on how to fix it.
Discussion
-************
+-----------
After you have a current image running on the Bone, it's not at all difficult to keep it upgraded.
Backing Up the Onboard Flash
------------------------------
+=============================
-.. todo:: keep?
+.. todo
+ keep?
Problem
-************
+--------
-You've modified the state of your Bone in a way that you'd like to preserve or share.
+You've modified the state of your Bone
+in a way that you'd like to preserve or share.
Solution
-************
+---------
-The `eLinux wiki <The http://elinux.org/Beagleboard>`_ page on `BeagleBone Black Extracting eMMC contents <http://bit.ly/1C57I0a>`
+The `eLinux wiki <The http://elinux.org/Beagleboard>`_ page on `BeagleBone Black Extracting eMMC contents <http://bit.ly/1C57I0a>`_
provides some simple steps for copying the contents of the onboard flash to a file on a microSD card:
- Get a 4 GB or larger microSD card that is FAT formatted.
- If you create a FAT-formatted microSD card, you must edit the partition and ensure that it is a bootable partition.
- Download `beagleboneblack-save-emmc.zip <http://bit.ly/1wtXwNP>`_ and uncompress and copy the contents onto your microSD card.
- Eject the microSD card from your computer, insert it into the powered-off BeagleBone Black, and apply power to your board.
-- You'll notice +USER0+ (the LED closest to the S1 button in the corner) will (after about 20 seconds) begin to blink steadily, rather than the double-pulse "heartbeat" pattern that is typical when your BeagleBone Black is running the standard Linux kernel configuration.
-- It will run for a bit under 10 minutes and then +USER0+ will stay on steady. That's your cue to remove power, remove the microSD card, and put it back into your computer.
+- You'll notice *USER0* (the LED closest to the S1 button in the corner) will (after about 20 seconds) begin to blink steadily, rather than the double-pulse "heartbeat" pattern that is typical when your BeagleBone Black is running the standard Linux kernel configuration.
+- It will run for a bit under 10 minutes and then *USER0* will stay on steady. That's your cue to remove power, remove the microSD card, and put it back into your computer.
- You will see a file called *BeagleBoneBlack-eMMC-image-XXXXX.img*, where *XXXXX* is a set of random numbers. Save this file to use for restoring your image later.
-.. note:: Because the date won't be set on your board, you might want to adjust the date on the file to remember when you made it. For storage on your computer, these images will typically compress very well, so use your favorite compression tool.
+.. note::
-.. tip:: `eLinux wiki <The http://elinux.org/Beagleboard>`_ is the definitive place for the BeagleBoard.org community to share information about the Beagles. Spend some time looking around for other helpful information.
+ Because the date won't be set on your board, you might want to
+ adjust the date on the file to remember when you made it. For
+ storage on your computer, these images will typically compress
+ very well, so use your favorite compression tool.
-Discussion
-************
+.. tip::
+
+ The `eLinux wiki <The http://elinux.org/Beagleboard>`_ is the
+ definitive place for the BeagleBoard.org community to
+ share information about the Beagles. Spend some time
+ looking around for other helpful information.
.. _basics_onboard_flash:
Updating the Onboard Flash
----------------------------
+===========================
Problem
-************
+--------
+
You want to copy the microSD card to the onboard flash.
Solution
-************
+--------
If you want to update the onboard flash with the contents of the microSD card,
-- Repeat the steps in :ref:`basics install os<basics_install_os>` to update the OS.
+- Repeat the steps in :ref:`basics_install_os` to update the OS.
- Attach to an external 5 V source. *you must be powered from an external 5 V source*. The flashing process requires more current than what typically can be pulled from USB.
- Boot from the microSD card.
-- Log on to the bone and edit +/boot/uEnv.txt+.
-- Uncomment out the last line +cmdline=init=/usr/sbin/init-beagle-flasher+.
+- Log on to the bone and edit */boot/uEnv.txt*.
+- Uncomment out the last line *cmdline=init=/usr/sbin/init-beagle-flasher*.
- Save the file and reboot.
- The USR LEDs will flash back and forth for a few minutes.
- When they stop flashing, remove the SD card and reboot.
- You are now running from the newly flashed onboard flash.
-.. warning:: If you write the onboard flash, _be sure to power the Bone from an external 5 V source_. The USB might not supply enough current.
+.. warning::
+ If you write the onboard flash, **be sure to power the
+ Bone from an external 5 V source**. The USB might not
+ supply enough current.
When you boot from the microSD card, it will copy the image to the onboard flash.
When all four *USER* LEDs turn off (in some versions, they all turn on), you can
diff --git a/books/beaglebone-cookbook/02sensors/sensors.rst b/books/beaglebone-cookbook/02sensors/sensors.rst
index 1a92078c..c41b82ad 100644
--- a/books/beaglebone-cookbook/02sensors/sensors.rst
+++ b/books/beaglebone-cookbook/02sensors/sensors.rst
@@ -4,27 +4,28 @@ Sensors
########
Introduction
-=============
+*************
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,
-as shown in :ref:`sensor host port <sensors_host_port>`.
+as shown in :ref:`sensors_host_port`.
.. note::
+
All the examples in the book assume you have cloned the Cookbook
- repository on www.github.com. Go here :ref:`basic repo <basics_repo>` for instructions.
+ repository on www.github.com. Go here :ref:`basics_repo` for instructions.
.. _sensors_host_port:
-The USB 2.0 host port
-
.. figure:: figures/black_hardware_details.png
:align: center
:alt: USB Host Port
-The two 46-pin cape headers (called +P8+ and +P9+) along the long edges of the
-board (:ref:`sensors P8 & P9 <sensors_P8P9_fig>`) provide connections for
+ 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:
@@ -38,92 +39,89 @@ cape 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
(GPIO) pins. More complex sensors can be connected by using one of the Bone's seven
-analog-to-digital converter (ADC) inputs or several I^2^C buses.
+analog-to-digital converter (ADC) inputs or several |I2C| buses.
-:ref:`display <displays>` discusses some of the *output mode* usages of the GPIO pins.
+:ref:`beaglebone-cookbook-displays` discusses some of the *output mode* usages of the GPIO pins.
-All these examples assume that you know how to edit a file (:ref:`basic vsc <basics_vsc>`) and run
+All these examples assume that you know how to edit a file (:ref:`basics_vsc`) and run
it, either within the Visual Studio Code (VSC) integrated development environment (IDE) or from
-the command line (:ref:`shell tips <tips_shell>`).
+the command line (:ref:`tips_shell`).
Choosing a Method to Connect Your Sensor
-----------------------------------------
+=========================================
Problem
-********
+-------
You want to acquire and attach a sensor and need to understand your basic options.
Solution
-*********
+--------
-:ref:`sensor cape headers<sensors_cape_headers>`
-shows many of the possibilities for connecting a sensor.
+:ref:`sensors_cape_headers` shows many of the possibilities for connecting a sensor.
.. _sensors_cape_headers:
.. figure:: figures/cape-headers.png
:align: center
- :alt: Some of the many sensor connection options on the Bone
-
- Sensor Connection Modes
+ :alt: Sensor Connection Modes
+
+ Some of the many sensor connection options on the Bone
Choosing the simplest solution available enables you to move on quickly to
addressing other system aspects. By exploring each connection type, you can
make more informed decisions as you seek to optimize and troubleshoot your design.
-Discussion
-***********
-
.. _sensors_getting_started:
Input and Run a Python or JavaScript Application for Talking to Sensors
-------------------------------------------------------------------------
+=========================================================================
Problem
-*********
+--------
You have your sensors all wired up and your Bone booted up, and you need to know how to enter and run your code.
Solution
-*********
+--------
You are just a few simple steps from running any of the recipes in this book.
-- Plug your Bone into a host computer via the USB cable (:ref:`basic out of the box<basics_out_of_the_box>`).
-- Start Visual Studio Code (:ref:`basic vsc <basics_vsc>`).
-- In the +bash+ tab (as shown in :ref:`sensors vsc bash <sensors_vsc_bash>`), run the following commands:
+- Plug your Bone into a host computer via the USB cable (:ref:`basics_out_of_the_box`).
+- Start Visual Studio Code (:ref:`basics_vsc`).
+- In the *bash* tab (as shown in :ref:`sensors_vsc_bash`), run the following commands:
.. code-block:: bash
bone$ cd
-
bone$ cd BoneCookbook/docs/02sensors/code
.. _sensors_vsc_bash:
.. figure:: figures/vsc-bash-tab.png
:align: center
- :alt: Entering commands in the VSC bash tab
+ :alt: VSC bash tab
- VSC bash tab
+ Entering commands in the VSC bash tab
-Here, we issued the *change directory* (+cd+) command without specifying a target directory.
+Here, we issued the *change directory* (*cd*) command without specifying a target directory.
By default, it takes you to your home directory. Notice that the prompt has changed to reflect the change.
.. note::
- If you log in as +debian+, your home is */home/debian*. If you were to create a new user
+
+ If you log in as *debian*, your home is */home/debian*. If you were to create a new user
called *newuser*, that user's home would be */home/newuser*. By default, all non-root
(non-superuser) users have their home directories in */home*.
.. note::
+
All the examples in the book assume you have cloned the
Cookbook repository on www.github.com. Go here
- :ref:`basic repo <basics_repo>` for instructions.
+ :ref:`basics_repo` for instructions.
- Double-click the *pushbutton.py* file to open it.
- Press ^S (Ctrl-S) to save the file. (You can also go to the File menu in VSC and select Save to save the file, but Ctrl-S is easier.) Even easier, VSC can be configured to autosave every so many seconds.
-- In the +bash+ tab, enter the following commands:
+- In the *bash* tab, enter the following commands:
.. code-block::
@@ -136,63 +134,58 @@ By default, it takes you to your home directory. Notice that the prompt has chan
This process will work for any script in this book.
-Discussion
-***********
-
.. _sensors_pushbutton:
Reading the Status of a Pushbutton or Magnetic Switch (Passive On/Off Sensor)
-------------------------------------------------------------------------------
+==============================================================================
Problem
-********
+--------
You want to read a pushbutton, a magnetic switch, or other sensor that is electrically open or closed.
Solution
-*********
+---------
Connect the switch to a GPIO pin and read from the proper place in */sys/class/gpio*.
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* Pushbutton switch (see :ref:`app misc <app_misc>`)
-* Magnetic reed switch (optional, see :ref:`<app misc app_misc>`)
+* Breadboard and jumper wires.
+* Pushbutton switch.
+* Magnetic reed switch.
You can wire up either a pushbutton, a magnetic reed switch,
-or both on the Bone, as shown in :ref:`figure below <js_pushbutton_fig>`.
+or both on the Bone, as shown in :ref:`js_pushbutton_fig`.
.. _js_pushbutton_fig:
.. figure:: figures/pushbutton_bb.png
:align: center
- :alt: Diagram for wiring a pushbutton and magnetic reed switch input
+ :alt: Bone with pushbutton
- Bone with pushbutton
+ Diagram for wiring a pushbutton and magnetic reed switch input
-The code in :ref:`js pushbutton code<js_pushbutton_code>`
+The code in :ref:`js_pushbutton_code`
reads GPIO port *P9_42*, which is attached to the pushbutton.
.. _py_pushbutton_code:
-Monitoring a pushbutton (pushbutton.py)
-
-.. code-block:: python
-
- include::code/pushbutton.py
+.. literalinclude:: code/pushbutton.py
+ :caption: Monitoring a pushbutton (pushbutton.py)
+ :linenos:
+:download:`pushbutton.py <code/pushbutton.py>`
.. _js_pushbutton_code:
-Monitoring a pushbutton (pushbutton.js)
-
-.. code-block:: javascript
+.. literalinclude:: code/pushbutton.js
+ :caption: Monitoring a pushbutton (pushbutton.js)
+ :linenos:
- include::code/pushbutton.js
+:download:`pushbutton.js <code/pushbutton.js>`
-Put this code in a file called *pushbutton.js* following the steps in
-:ref:`sensor getting started <sensors_getting_started>`.
+Put this code in a file called *pushbutton.js* following the steps in :ref:`sensors_getting_started`.
In the VSC *bash* tab, run it by using the following commands:
.. code-block:: bash
@@ -208,23 +201,21 @@ The command runs it. Try pushing the button. The code reads the pin and prints i
You will have to press ^C (Ctrl-C) to stop the code.
-If you want to use the magnetic reed switch wired as shown in :ref:`javascript pushbutton <js_pushbutton_fig>`, change +P9_42+ to +P9_26+ which is gpio +14+.
-
-Discussion
-***********
+If you want to use the magnetic reed switch wired as shown in
+:ref:`js_pushbutton_fig`, change *P9_42* to *P9_26* which is gpio *14*.
Mapping Header Numbers to gpio Numbers
----------------------------------------
+=======================================
Problem
-********
+--------
You have a sensor attached to the P8 or P9 header and need to know which gpio pin it's using.
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. To see the info for just one pin, use *grep*.
.. code-block:: bash
@@ -252,43 +243,43 @@ For P9_26 you get:
0*32+14=14, so the P9_26 pin is gpio 14.
Reading a Position, Light, or Force Sensor (Variable Resistance Sensor)
--------------------------------------------------------------------------
+========================================================================
Problem
-*********
+--------
You have a variable resistor, force-sensitive resistor, flex sensor, or any of a
number of other sensors that output their value as a variable resistance,
and you want to read their value with the Bone.
Solution
-*********
+--------
Use the Bone's analog-to-digital converters (ADCs) and a resistor
divider circuit to detect the resistance in the sensor.
The Bone has seven built-in analog inputs that can easily read a
-resistive value. :ref:`cape header analog sensors <sensors_cape_headers_analog>` shows them
-on the lower part of the +P9+ header.
+resistive value. :ref:`sensors_cape_headers_analog` shows them
+on the lower part of the *P9* header.
.. _sensors_cape_headers_analog:
.. figure:: figures/cape-headers-analog.png
:align: center
- :alt: Seven analog inputs on the +P9+ header
+ :alt: Seven analog inputs on the *P9* header
Seven analog inputs on P9 header
To make this recipe, you will need:
-- Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-- 10 kΩ trimpot (see :ref:`app resistor <app_resistor>`) or
-- Flex resistor (optional, see :ref:`app resistor <app_resistor>`)
-- 22 kΩ resistor (see :ref:`app resistor<app_resistor>`)
+- Breadboard and jumper wires.
+- 10k trimpot or
+- Flex resistor (optional)
+- 22k resistor
A variable resistor with three terminals
-:ref:`sensor analogIn<sensors_analogIn_fig>` shows a simple variable resistor (trimpot)
+:ref:`sensors_analogIn_fig` shows a simple variable resistor (trimpot)
wired to the Bone. One end terminal is wired to the ADC 1.8 V power supply on pin *P9_32*,
and the other end terminal is attached to the ADC ground (*P9_34*). The middle terminal
is wired to one of the seven analog-in ports (*P9_36*).
@@ -297,78 +288,75 @@ is wired to one of the seven analog-in ports (*P9_36*).
.. figure:: figures/analogIn_bb.png
:align: center
- :alt: Wiring a 10k variable resistor (trimpot) to an ADC port
+ :alt: Analog
Wiring a 10k variable resistor (trimpot) to an ADC port
-:ref:`sensor analogIn code <sensors_analogIn_code>` shows the BoneScript code used to read the variable resistor.
+:ref:`sensors_analogIn_code` shows the BoneScript code used to read the variable resistor.
Add the code to a file called _analogIn.js_ and run it; then change the resistor and run it again. The voltage read will change.
.. _py_analogIn_code:
-Reading an analog voltage (analogIn.py)
+.. literalinclude:: code/analogIn.py
+ :caption: Reading an analog voltage (analogIn.py)
+ :linenos:
-.. code-block:: python
-
- include::code/analogIn.py
+:download:`analogIn.py <code/analogIn.py>`
.. _sensors_analogIn_code:
-Reading an analog voltage (analogIn.js)
-
-.. code-block:: javascript
+.. literalinclude:: code/analogIn.js
+ :caption: Reading an analog voltage (analogIn.js)
+ :linenos:
- include::code/analogIn.js[]
+:download:`analogIn.js <code/analogIn.js>`
.. note::
- The code in :ref:`sensor analogIn code<sensors_analogIn_code>`
+
+ The code in :ref:`sensors_analogIn_code`
outputs a value between 0 and 4096.
A variable resistor with two terminals
-Some resistive sensors have only two terminals, such as the flex sensor in
-:ref:`sensor flex resistor<sensors_flexResistor_fig>`
+Some resistive sensors have only two terminals, such as the flex sensor in :ref:`sensors_flexResistor_fig`
The resistance between its two terminals changes when it is flexed.
-In this case, we need to add a fixed resistor in series with the flex sensor.
-:ref:`sensor flex resistor <sensors_flexResistor_fig>`
-shows how to wire in a 22 kΩ resistor to give a voltage to measure
+In this case, we need to add a fixed resistor in series with the flex sensor. :ref:`sensors_flexResistor_fig`
+shows how to wire in a 22k resistor to give a voltage to measure
across the flex sensor.
.. _sensors_flexResistor_fig:
.. figure:: figures/flexResistor_bb.png
:align: center
- :alt: Reading a two-terminal flex resistor
+ :alt: Flex Resistor
- Flex Resistor
-
-The code in :ref:`py analogIn code <py_analogIn_code>` and
-:ref:`sensors analogIn code <sensors_analogIn_code>` also works for this setup.
+ Reading a two-terminal flex resistor
-Discussion
-************
+The code in :ref:`py_analogIn_code` and
+:ref:`sensors_analogIn_code` also works for this setup.
Reading a Distance Sensor (Analog or Variable Voltage Sensor)
---------------------------------------------------------------
+=============================================================
Problem
-********
+--------
You want to measure distance with a `LV-MaxSonar-EZ1 Sonar Range Finder <http://bit.ly/1Mt5Elr>`_,
which outputs a voltage in proportion to the distance.
Solution
-*********
+--------
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* LV-MaxSonar-EZ1 Sonar Range Finder (see :ref:`app musc <app_misc>`)
+* Breadboard and jumper wires.
+* LV-MaxSonar-EZ1 Sonar Range Finder
All you have to do is wire the EZ1 to one of the Bone's *analog-in* pins,
-as shown in `this figure<sensors_ultrasonic_fig>`. The device outputs ~6.4 mV/in when powered from 3.3 V.
+as shown in :ref:`sensors_ultrasonic_fig`. The device outputs ~6.4 mV/in when powered from 3.3 V.
+
+.. WARNING::
-.. _WARNING:
Make sure not to apply more than 1.8 V to the Bone's *analog-in*
pins, or you will likely damage them. In practice, this circuit should follow that rule.
@@ -376,47 +364,44 @@ as shown in `this figure<sensors_ultrasonic_fig>`. The device outputs ~6.4 mV/in
.. figure:: figures/ultrasonicRange_bb.png
:align: center
- :alt: Wiring the LV-MaxSonar-EZ1 Sonar Range Finder to the *P9_33* analog-in port
+ :alt: Analog
Wiring the LV-MaxSonar-EZ1 Sonar Range Finder to the *P9_33* analog-in port
-:ref:`Ultrasonic sensor range code <sensors_ultrasonicRange_code>`
+:ref:`sensors_ultrasonicRange_code`
shows the code that reads the sensor at a fixed interval.
.. _py_ultrasonicRange_code:
-Reading an analog voltage (ultrasonicRange.py)
+.. literalinclude:: code/ultrasonicRange.py
+ :caption: Reading an analog voltage (ultrasonicRange.py)
+ :linenos:
-.. code-block:: python
-
- include::code/ultrasonicRange.py[]
+:download:`ultrasonicRange.py <code/ultrasonicRange.py>`
.. _sensors_ultrasonicRange_code:
-Reading an analog voltage (ultrasonicRange.js)
-
-.. code-block:: javascript
- include::code/ultrasonicRange.js[]
+.. literalinclude:: code/ultrasonicRange.js
+ :caption: Reading an analog voltage (ultrasonicRange.js)
+ :linenos:
-Discussion
-***********
+:download:`ultrasonicRange.js <code/ultrasonicRange.js>`
.. _sensors_hc-sr04:
Reading a Distance Sensor (Variable Pulse Width Sensor)
---------------------------------------------------------
-
-// TODO
+========================================================
Problem
-**********
+--------
You want to use a HC-SR04 Ultrasonic Range Sensor with BeagleBone Black.
Solution
-**********
-The HC-SR04 Ultrasonic Range Sensor (shown in `hc sr04 sensor image <sensors_hc_sr04_image_fig>`)
+---------
+
+The HC-SR04 Ultrasonic Range Sensor (shown in :ref:`sensors_hc_sr04_image_fig`)
works by sending a trigger pulse to the *Trigger* input and then measuring the
pulse width on the *Echo* output. The width of the pulse tells you the distance.
@@ -430,11 +415,11 @@ pulse width on the *Echo* output. The width of the pulse tells you the distance.
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* 10 kΩ and 20 kΩ resistors (see :ref:`app resistor <app_resistor>`)
-* HC-SR04 Ultrsonic Range Sensor (see :ref:`app misc <app_misc>`)
+* Breadboard and jumper wires.
+* 10 k and 20 k resistors
+* HC-SR04 Ultrsonic Range Sensor.
-Wire the sensor as shown in :ref:`hc sr04 sensor<sensors_hc-sr04_fig>`.
+Wire the sensor as shown in :ref:`sensors_hc-sr04_fig`.
Note that the HC-SR04 is a 5 V device, so the *banded* wire (running from
*P9_7* on the Bone to VCC on the range finder) attaches the
HC-SR04 to the Bone's 5 V power supply.
@@ -447,37 +432,33 @@ HC-SR04 to the Bone's 5 V power supply.
Wiring an HC-SR04 Ultrasonic Sensor
-:ref:`hc sr04 <sensors_hc-sr04_code>` shows
-BoneScript code used to drive the HC-SR04.
+:ref:`sensors_hc-sr04_code` shows BoneScript code used to drive the HC-SR04.
.. _sensors_hc-sr04_code:
-Driving a HC-SR04 ultrasound sensor (hc-sr04-ultraSonic.js)
-
-.. code-block:: javascript
+.. literalinclude:: code/hc-sr04-ultraSonic.js
+ :caption: Driving a HC-SR04 ultrasound sensor (hc-sr04-ultraSonic.js)
+ :linenos:
- include::code/hc-sr04-ultraSonic.js[]
+:download:`hc-sr04-ultraSonic.js <code/hc-sr04-ultraSonic.js>`
This code is more complex than others in this chapter,
because we have to tell the device when to start
measuring and time the return pulse.
-Discussion
-**********
-
Accurately Reading the Position of a Motor or Dial
-----------------------------------------------------
+===================================================
Problem
-**********
+--------
You have a motor or dial and want to detect rotation using a rotary encoder.
Solution
-**********
+---------
Use a rotary encoder (also called a *quadrature encoder*) connected to one of
-the Bone's eQEP ports, as shown in :ref:`digital rotary encoder figure<digital_rotaryEncoder_fig>`.
+the Bone's eQEP ports, as shown in :ref:`digital_rotaryEncoder_fig`.
.. _digital_rotaryEncoder_fig:
@@ -487,9 +468,7 @@ the Bone's eQEP ports, as shown in :ref:`digital rotary encoder figure<digital_r
Wiring a rotary encoder using eQEP2
-On the BeagleBone and PocketBeage the three encoders are:
-
-.. table::
+.. table:: On the BeagleBone and PocketBeage the three encoders are:
+-------------+------------------------------------+
| eQEP0 | P9.27 and P9.42 OR P1_33 and P2_34 |
@@ -499,9 +478,7 @@ On the BeagleBone and PocketBeage the three encoders are:
|eQEP2 | P8.11 and P8.12 OR P2_24 and P2_33 |
+-------------+------------------------------------+
-On the AI it's:
-
-.. table::
+.. table:: On the AI it's:
+-------------+------------------------------------+
|eQEP1 | P8.33 and P8.35 |
@@ -513,8 +490,8 @@ On the AI it's:
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* Rotary encoder (see :ref:`app misc <app_misc>`)
+* Breadboard and jumper wires.
+* Rotary encoder.
We are using a quadrature rotary encoder, which has two switches inside
that open and close in such a manner that you can tell which way the shaft
@@ -522,11 +499,10 @@ is turning. In this particular encoder, the two switches have a common lead,
which is wired to ground. It also has a pushbutton switch wired to the other
side of the device, which we aren't using.
-Wire the encoder to +P8_11+ and +P8_12+, as shown in
-:ref:`digital rotary encoder <digital_rotaryEncoder_fig>`.
+Wire the encoder to *P8_11* and *P8_12*, as shown in :ref:`digital_rotaryEncoder_fig`.
BeagleBone Black has built-in hardware for reading up to three encoders.
-Here, we'll use the *eQEP2* encoder via the Linux +count+ subsystem.
+Here, we'll use the *eQEP2* encoder via the Linux *count* subsystem.
Then run the following commands:
@@ -539,29 +515,30 @@ Then run the following commands:
P8.12 12 fast rx up 4 qep 2 in A ocp/P8_12_pinmux (pinmux_P8_12_qep_pin)
P8.11 13 fast rx up 4 qep 2 in B ocp/P8_11_pinmux (pinmux_P8_11_qep_pin)
-This will enable *eQEP2* on pins +P8_11+ and *P8_12*.
-The *2* after the +qep+ returned by *show-pins* shows it's *eQEP2*.
+This will enable *eQEP2* on pins *P8_11* and *P8_12*.
+The *2* after the *qep* returned by *show-pins* shows it's *eQEP2*.
-Finally, add the code in :ref:`digital rotary encoder<digital_rotaryEncoder_js>`
+Finally, add the code in :ref:`digital_rotaryEncoder_js`
to a file named *rotaryEncoder.js* and run it.
.. _digital_rotaryEncoder_py:
-Reading a rotary encoder (rotaryEncoder.py)
+.. literalinclude:: code/rotaryEncoder.py
+ :caption: Reading a rotary encoder (rotaryEncoder.py)
+ :linenos:
-.. code-block:: bash
-
- include::code/rotaryEncoder.py
+:download:`rotaryEncoder.py <code/rotaryEncoder.py>`
.. _digital_rotaryEncoder_js:
-Reading a rotary encoder (rotaryEncoder.js)
+.. literalinclude:: code/rotaryEncoder.js
+ :caption: Reading a rotary encoder (rotaryEncoder.js)
+ :linenos:
-.. code-block::javascript
+:download:`rotaryEncoder.js <code/rotaryEncoder.js>`
- include::code/rotaryEncoder.js
-
-Try rotating the encoder clockwise and counter-clockwise. You'll see an output like this:
+Try rotating the encoder clockwise and counter-clockwise.
+You'll see an output like this:
.. code-block::bash
@@ -578,32 +555,28 @@ Try rotating the encoder clockwise and counter-clockwise. You'll see an output l
^C
-The values you get for +data+ will depend on which way you are
+The values you get for *data* will depend on which way you are
turning the device and how quickly. You will need to press ^C (Ctrl-C) to end.
-Discussion
-**********
See Also
-**********
+---------
-You can also measure rotation by using a variable resistor (see :ref:`sensors analogIn <sensors_analogIn_fig>`).
+You can also measure rotation by using a variable resistor (see :ref:`sensors_analogIn_fig`).
.. _sensors_GPS:
Acquiring Data by Using a Smart Sensor over a Serial Connection
------------------------------------------------------------------
-
-// TODO
+================================================================
Problem
-**********
+--------
You want to connect a smart sensor that uses a built-in microcontroller to stream data,
such as a global positioning system (GPS), to the Bone and read the data from it.
Solution
-**********
+--------
The Bone has several serial ports (UARTs) that you can use to read data from an external
microcontroller included in smart sensors, such as a GPS. Just wire one up, and you'll
@@ -611,10 +584,10 @@ soon be gathering useful data, such as your own location.
Here's what you'll need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* GPS receiver (see :ref:`app musc <app_misc>`)
+* Breadboard and jumper wires.
+* GPS receiver
-Wire your GPS, as shown in :ref:`digital GPS<digital_GPS_fig>`.
+Wire your GPS, as shown in :ref:`digital_GPS_fig`.
.. _digital_GPS_fig:
@@ -633,31 +606,27 @@ human-readable form. For this GPS, run the following command to load a NMEA pars
bone$ npm install -g nmea
-Running the code in :ref:`digital GPD code <digital_GPS_code>`
+Running the code in :ref:`digital_GPS_code`
will print the current location every time the GPS outputs it.
.. _digital_GPS_code:
-Talking to a GPS with UART 4 (GPS.js)
-
-.. code-block:: javascript
+.. literalinclude:: code/GPS.js
+ :caption: Talking to a GPS with UART 4 (GPS.js)
+ :linenos:
- include::code/GPS.js[]
+:download:`GPS.js <code/GPS.js>`
If you don't need the NMEA formatting, you can skip the *npm* part and remove the lines in the code that refer to it.
-.. note:: If you get an error like this
-
-.. TypeError:: Cannot call method 'readline' of undefined+
+.. note::
+ If you get an error like this
+ TypeError: Cannot call method 'readline' of undefined
-add this line to the end of file */usr/local/lib/node_modules/bonescript/serial.js*:
+add this line to the end of file ``/usr/local/lib/node_modules/bonescript/serial.js``:
*exports.serialParsers = m.module.parsers;*
-Discussion
-**********
-
-
.. _cape-headers-serial_fig:
.. figure:: figures/cape-headers-serial.png
@@ -669,60 +638,63 @@ Discussion
.. _sensors_i2c_temp:
Measuring a Temperature
----------------------------
+=======================
Problem
-**********
+-------
You want to measure a temperature using a digital temperature sensor.
Solution
-**********
+---------
The TMP101 sensor is a common digital temperature
-sensor that uses a standard I^2^C-based serial protocol.
+sensor that uses a standard |I2C|-based serial protocol.
+
+.. |I2C| replace:: I\ :sub:`2`\ C
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* Two 4.7 kΩ resistors (see :ref:`app resistor <app_resistor>`)
-* TMP101 temperature sensor (see :ref:`app ic<app_ic>`)
+* Breadboard and jumper wires.
+* Two 4.7 k resistors.
+* TMP101 temperature sensor.
-Wire the TMP101, as shown in :ref:`i2c temprature sensor<sensors_i2cTemp_fig>`.
+Wire the TMP101, as shown in :ref:`sensors_i2cTemp_fig`.
.. _sensors_i2cTemp_fig:
.. figure:: figures/i2cTemp_bb.png
:align: center
- :alt: Wiring an I^2^C TMP101 temperature sensor
+ :alt: |I2C| Temp
- Wiring an I^2^C TMP101 temperature sensor
+ Wiring an |I2C| TMP101 temperature sensor
-There are two I^2^C buses brought out to the headers.
-:ref:`sensor cap headers i2c <sensors_cape_headers_i2c>`
-shows that you have wired your device to I^2^C bus +2+.
+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 I^2^C outputs
+ :alt: Table of |I2C| outputs
- Table of I^2^C outputs
+ Table of |I2C| outputs
-Once the I^2^C device is wired up, you can use a couple handy I^2^C
+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,
-you have to use +2+ as the bus number. +i2cdetect+, shown in `javascript I2C tools <js_i2cTools>`,
-shows which I^2^C devices are on the bus. The +-r+ flag indicates which bus to use.
-Our TMP101 is appearing at address *0x498. You can use the +i2cget+ command to read
+you have to use *2* as the bus number. *i2cdetect*, shown in :ref:`js_i2cTools`,
+shows which |I2C| devices are on the bus. The *-r* flag indicates which bus to use.
+Our TMP101 is appearing at address *0x498*. You can use the *i2cget* command to read
the value. It returns the temperature in hexidecimal 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.
.. _js_i2cTools:
-I^2^C tools
+|I2C| tools
+============
.. code-block:: bash
@@ -742,7 +714,7 @@ I^2^C tools
Reading the temperature via the kernel driver
-**********************************************
+==============================================
The cleanest way to read the temperature from at TMP101 sensor is to use the kernel drive.
@@ -750,7 +722,7 @@ Assuming the TMP101 is on bus 2 (the last digit is the bus number)
.. _js_i2cKernel:
-I^2^C TMP101 via Kernel
+|I2C| TMP101 via Kernel
.. code-block:: bash
@@ -812,26 +784,24 @@ Other i2c devices are supported by the kernel.
You can try the Linux Kernel Driver Database,
https://cateee.net/lkddb/ to see them.
-Once the driver is in place, you can read it via code.
-:ref:`i2c temprature python code <py_i2cTemp_code>`
-shows how to read the TMP101 from BoneScript.
+Once the driver is in place, you can read it via code.
+:ref:`py_i2cTemp_code` shows how to read the TMP101 from BoneScript.
.. _py_i2cTemp_code:
-Reading an I^2^C device (i2cTemp.py)
-
-.. code-block:: python
-
- include::code/i2cTemp.py[]
+.. literalinclude:: code/i2cTemp.py
+ :caption: Reading an |I2C| device (i2cTemp.py)
+ :linenos:
+:download:`i2cTemp.py <code/i2cTemp.py>`
.. _js_i2cTemp_code:
-.Reading an I^2^C device (i2cTemp.js)
+.. literalinclude:: code/i2cTemp.js
+ :caption: Reading an |I2C| device (i2cTemp.js)
+ :linenos:
-.. code-block:: javascript
-
- include::code/i2cTemp.js[]
+:download:`i2cTemp.js <code/i2cTemp.js>`
Run the code by using the following command:
@@ -848,9 +818,10 @@ Run the code by using the following command:
Notice using the kernel interface gets you more digits of accuracy.
Reading i2c device directly
-*******************************
+===========================
-The TMP102 sensor can be read directly with i2c commands rather than using the kernel driver. First you need to install the i2c module.
+The TMP102 sensor can be read directly with i2c commands rather than
+using the kernel driver. First you need to install the i2c module.
.. code-block:: bash
@@ -859,34 +830,32 @@ The TMP102 sensor can be read directly with i2c commands rather than using the k
.. _js_i2ctmp101_code:
-Reading an I^2^C device (i2cTemp.py)
-.. code-block:: python
-
- include::code/i2ctmp101.py[]
+.. literalinclude:: code/i2ctmp101.py
+ :caption: Reading an |I2C| device (i2cTemp.py)
+ :linenos:
-This gets only 8 bits for the temperature. See the TMP101 datasheet for details on how to get up to 12 bits.
-
-Discussion
-**********
+:download:`i2ctmp101.py <code/i2ctmp101.py>`
+This gets only 8 bits for the temperature. See the TMP101 datasheet
+for details on how to get up to 12 bits.
Reading Temperature via a Dallas 1-Wire Device
-----------------------------------------------------
+===============================================
Problem
-**********
+--------
You want to measure a temperature using a Dallas Semiconductor DS18B20 temperature sensor.
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
+.. 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.
+.. --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
@@ -895,23 +864,25 @@ You can wire it to any GPIO port.
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* 4.7 kΩ resistor (see :ref:`app resistor <app_resistor>`)
-* DS18B20 1-wire temperature sensor (see :ref:`app ic<app_ic>`)
+* Breadboard and jumper wires.
+* 4.7 k resistor
+* DS18B20 1-wire temperature sensor.
-Wire up as shown in :ref:`1 wire sensor <sensors_1-wire_fig>`.
+Wire up as shown in :ref:`sensors_1-wire_fig`.
.. _sensors_1-wire_fig:
-.. note:: This solution, written by Elias Bakken (@AgentBrum), originally appeared on`Hipstercircuits http://bit.ly/1FaRbbK`_.
-
.. figure:: figures/onewire_bb.png
:align: center
:alt: 1-wire
Wiring a Dallas 1-Wire temperature sensor
-Edit the file +/boot/uEnt.txt+.
+.. note::
+ This solution, written by Elias Bakken (@AgentBrum),
+ originally appeared on`Hipstercircuits <http://bit.ly/1FaRbbK>`_.
+
+Edit the file */boot/uEnt.txt*.
Go to about line 19 and edit as shown:
.. code-block:: bash
@@ -921,7 +892,7 @@ Go to about line 19 and edit as shown:
19 uboot_overlay_addr4=BB-W1-P9.12-00A0.dtbo
20 #uboot_overlay_addr5=<file5>.dtbo
-Be sure to remove the +#+ at the beginning of the line.
+Be sure to remove the *#* at the beginning of the line.
Reboot the bone:
@@ -929,7 +900,6 @@ Reboot the bone:
bone$ reboot
-
Now run the following command to discover the serial number on your device:
.. code-block:: bash
@@ -941,27 +911,25 @@ Now run the following command to discover the serial number on your device:
I have two devices wired in parallel on the same P9_12 input.
This shows the serial numbers for all the devices.
-Finally, add the code in
-:ref:`onewire sensor code <sensors_onewire__code>` in to a
-file named *w1.py*, edit the path assigned to +w1+ so
+Finally, add the code in :ref:`sensors_onewire__code` in to a
+file named *w1.py*, edit the path assigned to *w1* so
that the path points to your device, and then run it.
.. _py_onewire__code:
-Reading a temperature with a DS18B20 (w1.py)
+.. literalinclude:: code/w1.py
+ :caption: Reading a temperature with a DS18B20 (w1.py)
+ :linenos:
-.. code-block:: python
-
- include::code/w1.py[]
+:download:`w1.py <code/w1.py>`
.. _sensors_onewire__code:
-Reading a temperature with a DS18B20 (w1.js)
-
-.. code-block:: javascript
-
- include::code/w1.js[]
+.. literalinclude:: code/w1.js
+ :caption: Reading a temperature with a DS18B20 (w1.js)
+ :linenos:
+:download:`w1.js <code/w1.js>`
.. code-block:: bash
@@ -972,10 +940,6 @@ Reading a temperature with a DS18B20 (w1.js)
temp (C) = 31.0
^C
-
-Discussion
-**********
-
Each temperature sensor has a unique serial number, so you can have several all sharing the same data line.
.. // .. _sensors_sensortag:
@@ -998,8 +962,8 @@ Each temperature sensor has a unique serial number, so you can have several all
.. // To make this recipe, you will need:
-.. // * BLE USB dongle (see :ref:`app musc <app_misc>`)
-.. // * SensorTag (see :ref:`app musc <app_misc>`)
+.. // * BLE USB dongle
+.. // * SensorTag
.. // * 5 V adapter for the Bone
.. // Power up your Bone using the 5 V adapter. You need the adapter because the BLE dongle needs extra power for the radios it contains. After it is booted up, log in (:ref:`shell tips <tips_shell>`) and run the following commands:
@@ -1028,11 +992,11 @@ Each temperature sensor has a unique serial number, so you can have several all
.. // ====
.. // <1> Read in the various packages that are needed.
-.. // <2> +SensorTag.discover+ checks what SensorTags are out there. When found, it calls the inline function that follows.
+.. // <2> *SensorTag.discover* checks what SensorTags are out there. When found, it calls the inline function that follows.
.. // <3> pass:[<span id="callout_list_item_3">This</span>] function is called when the SensorTag is disconnected.
-.. // <4> Normally JavaScript does everything synchronously. Here, we want to do the following asynchronously--that is, step-by-step, one after the other. We are passing an array to +async.series()+, which contains the functions to run in the order in which they appear in the array.
+.. // <4> Normally JavaScript does everything synchronously. Here, we want to do the following asynchronously--that is, step-by-step, one after the other. We are passing an array to *async.series()*, which contains the functions to run in the order in which they appear in the array.
.. // <5> Connect to the SensorTag.
@@ -1042,17 +1006,17 @@ Each temperature sensor has a unique serial number, so you can have several all
.. // <8> Wait a bit for the first temperatures to be read.
-.. // <9> This specifies the function to call every time a temperature is ready. The callback is passed +objectTemperature+ (what's read by the touchless IR sensors) and +ambientTemperature+ (the temperature inside the SensorTag). Try putting your hand in front of the device; the +objectTemperature+ should go up.
+.. // <9> This specifies the function to call every time a temperature is ready. The callback is passed *objectTemperature* (what's read by the touchless IR sensors) and *ambientTemperature* (the temperature inside the SensorTag). Try putting your hand in front of the device; the *objectTemperature* should go up.
.. // <10> Define the callback for when the temperature changes.
.. // <11> This commented-out code is used when you want to turn off the temperature readings.
-.. // <12> Assign a callback to respond to the +left+ and +right+ button pushes.
+.. // <12> Assign a callback to respond to the *left* and *right* button pushes.
-.. // <13> If both buttons are pushed, pass the +callback+ function to +sensorTag.notifySimpleKey()+.
+.. // <13> If both buttons are pushed, pass the *callback* function to *sensorTag.notifySimpleKey()*.
-.. // <14> +sensorTag.notifySimpleKey()+ doesn't do anything in this case, but it does evaluate +callback+, allowing it to progress to the next and final state.
+.. // <14> *sensorTag.notifySimpleKey()* doesn't do anything in this case, but it does evaluate *callback*, allowing it to progress to the next and final state.
.. // <15> When we get to here, we disconnect from the SensorTag, which causes the code to exit (see pass:[<a href="#callout_list_item_3"><img src="callouts/3.png" alt="3"/></a>]).
@@ -1099,38 +1063,40 @@ Each temperature sensor has a unique serial number, so you can have several all
.. _sensors_audio:
Playing and Recording Audio
-------------------------------
+============================
-.. TODO:: Remove?
+.. TODO
+ Remove?
Problem
-**********
+--------
BeagleBone doesn't have audio built in, but you want to play and record files.
Solution
-**********
+--------
-One approach is to buy an audio cape (:ref:`app capes <app_capes>`), but another, possibly cheaper approach is to buy a USB audio adapter,
-such as the one shown in :ref:`usb audio dongle<usb_audio_dongle>`. Some adapters that I've tested are provided in :ref:`app musc <app_misc>`.
+One approach is to buy an audio cape (:ref:`app_capes`), but another, possibly cheaper approach is to buy a USB audio adapter,
+such as the one shown in :ref:`usb_audio_dongle`. Some adapters that I've tested are provided in :ref:`app_misc`.
.. _usb_audio_dongle:
-A USB audio dongle
-
.. figure:: figures/audioDongle.jpg
:align: center
:alt: Audio Dongle
+
+ A USB audio dongle
-Drivers for the `Advanced Linux Sound Architecture http://bit.ly/1MrAJUR`_ (ALSA)
+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
-your Bone by using +aplay+ and +arecord+, as shown in :ref:`alsa sensors <sensors_alsa>`. BeagleBone Black
+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:`also sensor <sensors_alsa>`. *card 1* is my USB audio adapter's audio out.
+:ref:`sensors_alsa`. *card 1* is my USB audio adapter's audio out.
.. _sensors_alsa:
Listing the ALSA audio output and input devices on the Bone
+============================================================
.. code-block:: bash
@@ -1150,28 +1116,27 @@ Listing the ALSA audio output and input devices on the Bone
Subdevice #0: subdevice #0
-In the *aplay* output shown in :ref:`alsa sensor <sensors_alsa>`, you can see the
+In the *aplay* output shown in :ref:`sensors_alsa`, you can see the
USB adapter's audio out. By default, the Bone will send audio to the HDMI. You
can change that default by creating a file in your home directory called
-*~/.asoundrc* and adding the code in :ref:`asoundrc <sensors_asoundrc>` to it.
+*~/.asoundrc* and adding the code in :ref:`sensors_asoundrc` to it.
.. _sensors_asoundrc:
-Change the default audio out by putting this in ~/.asoundrc (audio.asoundrc)
-
-.. code-block:: javascript
+.. literalinclude:: code/audio.asoundrc
+ :caption: Change the default audio out by putting this in ~/.asoundrc (audio.asoundrc)
+ :linenos:
- include::code/audio.asoundrc
+:download:`audio.asoundrc <code/audio.asoundrc>`
-
-You can easily play _.wav_ files with +aplay+:
+You can easily play ``.wav`` files with *aplay*:
.. code-block:: bash
bone$ aplay test.wav
-You can play other files in other formats by installing +mplayer+:
+You can play other files in other formats by installing *mplayer*:
.. code-block:: bash
@@ -1179,8 +1144,7 @@ You can play other files in other formats by installing +mplayer+:
bone$ sudo apt install mplayer
bone$ mplayer test.mp3
-
Discussion
-**********
+-----------
Adding the simple USB audio adapter opens up a world of audio I/O on the Bone.
diff --git a/books/beaglebone-cookbook/03displays/displays.rst b/books/beaglebone-cookbook/03displays/displays.rst
index c796ba35..eae831d3 100644
--- a/books/beaglebone-cookbook/03displays/displays.rst
+++ b/books/beaglebone-cookbook/03displays/displays.rst
@@ -4,17 +4,16 @@ Displays and Other Outputs
###########################
Introduction
---------------------------
+*************
In this chapter, you will learn how to control physical hardware via
BeagleBone Black's general-purpose input/output (GPIO) pins. The Bone has
65 GPIO pins that are brought out on two 46-pin headers, called
-+P8+ and +P9+, as shown in :ref:`<js_P8P9_fig>>.
+*P8* and *P9*, as shown in :ref:`js_P8P9_fig`.
.. note::
- All the examples in the book assume you have cloned the
- Cookbook repository on www.github.com. Go here :ref:`<basics_repo>` for instructions.
-
+ All the examples in the book assume you have cloned the Cookbook
+ repository on www.github.com. Go here :ref:`basics_repo` for instructions.
.. _js_P8P9_fig:
@@ -27,59 +26,55 @@ BeagleBone Black's general-purpose input/output (GPIO) pins. The Bone has
The purpose of this chapter is to give simple examples that show how to use
various methods of output. Most solutions require a breadboard and some jumper wires.
-All these examples assume that you know how to edit a file (:ref:`basic vsc<basics_vsc>`) and
+All these examples assume that you know how to edit a file (:ref:`basics_vsc`) and
run it, either within Visual Studio Code (VSC) integrated development
-environment (IDE) or from the command line (:ref:`<tips_shell>>).
+environment (IDE) or from the command line (:ref:`tips_shell`).
.. _displays_onboardLED:
Toggling an Onboard LED
---------------------------
+========================
Problem
-*************
+--------
You want to know how to flash the four LEDs that are next to the Ethernet port on the Bone.
Solution
-*************
+---------
-Locate the four onboard LEDs shown in :ref:`<js_internLED_fig>>.
-They are labeled +USR0+ through +USR3+, but we'll refer to them as the +USER+ LEDs.
+Locate the four onboard LEDs shown in :ref:`js_internLED_fig`. They are labeled *USR0*
+through *USR3*, but we'll refer to them as the *USER* LEDs.
.. _js_internLED_fig:
-The four +USER+ LEDs
-
.. figure:: figures/internLED.png
:align: center
:alt: USER LEDs
-Place the code shown in :ref:`<js_internLED_code>` in a file called _internLED.js_.
-You can do this using VSC to edit files (as shown in :ref:`basic vsc<basics_vsc>`) or with
-a more traditional editor (as shown in :ref:`<tips_editing_files>>).
+ The four *USER* LEDs
-.. _py_internLED_code:
-
-Using an internal LED (internLED.py)
-
-.. code-block:: python
+Place the code shown in :ref:`js_internLED_code` in a file called ``internLED.js``.
+You can do this using VSC to edit files (as shown in :ref:`basics_vsc`) or with
+a more traditional editor (as shown in :ref:`tips_editing_files`).
- include::code/internLED.py
+.. _py_internLED_code:
+.. literalinclude:: code/internLED.py
+ :caption: Using an internal LED (internLED.py)
+ :linenos:
+:download:`internLED.py <code/internLED.py>`
.. _js_internLED_code:
-Using an internal LED (internLED.js)
-
-.. code-block:: JavaScript
+.. literalinclude:: code/internLED.js
+ :caption: Using an internal LED (internLED.js)
+ :linenos:
- include::code/internLED.js
+:download:`internLED.js <code/internLED.js>`
-
-
-In the +bash+ command window, enter the following commands:
+In the *bash* command window, enter the following commands:
.. code-block:: bash
@@ -87,168 +82,157 @@ In the +bash+ command window, enter the following commands:
bone$ ./internLED.js
-The +USER0+ LED should now be flashing.
-
-Discussion
-*************
-
+The *USER0* LED should now be flashing.
.. _displays_externalLED:
Toggling an External LED
---------------------------
+========================
Problem
-*************
+--------
You want to connect your own external LED to the Bone.
Solution
-*************
-Connect an LED to one of the GPIO pins using a series resistor to limit the current. To make this recipe, you will need:
+---------
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* 220 Ω to 470 Ω resistor (see :ref:`app resistor <app_resistor>`)
-* LED (see :ref:`app opto <app_opto>`)
+Connect an LED to one of the GPIO pins using a series resistor
+to limit the current. To make this recipe, you will need:
+
+* Breadboard and jumper wires.
+* 220R to 470R resistor.
+* LED
.. WARNING::
+
The value of the current limiting resistor depends on the LED you are using.
The Bone can drive only 4 to 6 mA, so you might need a larger resistor to keep
- from pulling too much current. A 330 Ω or 470 Ω resistor might be better.
+ from pulling too much current. A 330R or 470R resistor might be better.
-
-:ref:`<displays_externLED_fig>` shows how you can wire the LED to pin 14 of
-the +P9+ header (+P9_14+). Every circuit in this book (:ref:`<basics_wire_breadboard>>)
-assumes you have already wired the rightmost bus to ground (+P9_1+) and the next bus to
-the left to the 3.3 V (+P9_3+) pins on the header. Be sure to get the polarity right on
+:ref:`displays_externLED_fig` shows how you can wire the LED to pin 14 of
+the *P9* header (*P9_14*). Every circuit in this book (:ref:`basics_wire_breadboard`)
+assumes you have already wired the rightmost bus to ground (*P9_1*) and the next bus to
+the left to the 3.3 V (*P9_3*) pins on the header. Be sure to get the polarity right on
the LED. The _short_ lead always goes to ground.
.. _displays_externLED_fig:
-Diagram for using an external LED
-
.. figure:: figures/externLED_bb.png
:align: center
:alt: External LED
-After you've wired it, start VSC (see :ref:`basic vsc<basics_vsc>`)
-and find the code shown in :ref:`<py_externLED_code>>.
+ Diagram for using an external LED
-.. _py_externLED_code:
+After you've wired it, start VSC (see :ref:`basics_vsc`)
+and find the code shown in :ref:`py_externLED_code`.
-Code for using an external LED (externLED.py)
-
-.. code-block:: python
+.. _py_externLED_code:
- include::code/externLED.py
+.. literalinclude:: code/externLED.py
+ :caption: Code for using an external LED (externLED.py)
+ :linenos:
+:download:`externLED.py <code/externLED.py>`
.. _js_externLED_code:
-Code for using an external LED (externLED.js)
+.. literalinclude:: code/externLED.js
+ :caption: Code for using an external LED (externLED.js)
+ :linenos:
-.. code-block:: JavaScript
+:download:`externLED.js <code/externLED.js>`
- include::code/externLED.js
-
-
-Save your file and run the code as before (:ref:`<displays_onboardLED>>).
-
-Discussion
-*************
+Save your file and run the code as before (:ref:`displays_onboardLED`).
.. _displays_powerSwitch:
Toggling a High-Voltage External Device
------------------------------------------
+========================================
Problem
-*************
+-------
You want to control a device that runs at 120 V.
Solution
-*************
+---------
-Working with 120 V can be tricky--even dangerous--if
-you aren't careful. Here's a safe way to do it.
+Working with 120 V can be tricky --even dangerous-- if
+you aren't careful. Here's a safe way to do it.
To make this recipe, you will need:
-* PowerSwitch Tail II (see :ref:`<app_misc>>)
+* PowerSwitch Tail II
-:ref:`<displays_powerSwitch_fig>` shows how you can wire
-the PowerSwitch Tail II to pin +P9_14+.
+:ref:`displays_powerSwitch_fig` shows how you can wire
+the PowerSwitch Tail II to pin *P9_14*.
.. _displays_powerSwitch_fig:
-Diagram for wiring PowerSwitch Tail II
-
.. figure:: figures/powerSwitch_bb.png
:align: center
:alt: Power Switch Tail II
-After you've wired it, because this uses the same output pin as
-:ref:`<displays_externalLED>>, you can run the same code (:ref:`<py_externLED_code>>).
+ Diagram for wiring PowerSwitch Tail II
-Discussion
-*************
+After you've wired it, because this uses the same output pin as
+:ref:`displays_externalLED`, you can run the same code (:ref:`py_externLED_code`).
.. _displays_PWMdiscussion:
Fading an External LED
---------------------------
+=======================
Problem
-*************
+--------
+
You want to change the brightness of an LED from the Bone.
Solution
-*************
+---------
Use the Bone's pulse width modulation (PWM) hardware to fade an LED. We'll use
-the same circuit as before (:ref:`<displays_externLED_fig>>). Find the code in
-:ref:`<py_fadeLED_code>>Next configure the pins. We are using P9_14 so run:
+the same circuit as before (:ref:`displays_externLED_fig`). Find the code in
+:ref:`py_fadeLED_code` Next configure the pins. We are using P9_14 so run:
.. code-block:: bash
- bone$ config-pin P9_14 pwm
+ bone$ config-pin P9_14 pwm
Then run it as before.
.. _py_fadeLED_code:
-Code for using an external LED (fadeLED.py)
-
-.. code-block:: python
+.. literalinclude:: code/fadeLED.py
+ :caption: Code for using an external LED (fadeLED.py)
+ :linenos:
- include::code/fadeLED.py
+:download:`fadeLED.py <code/fadeLED.py>`
.. _js_fadeLED_code:
-Code for using an external LED (fadeLED.js)
-
-.. code-block:: JavaScript
+.. literalinclude:: code/fadeLED.js
+ :caption: Code for using an external LED (fadeLED.js)
+ :linenos:
- include::code/fadeLED.js
-
-Discussion
-*************
+:download:`fadeLED.js <code/fadeLED.js>`
-The Bone has several outputs that can be use as pwm's as shown in :ref:`<cape-headers-pwm_fig>>.
-There are three +EHRPWM+'s which each has a pair of pwm channels. Each pair must have the same period.
+The Bone has several outputs that can be use as pwm's as shown in :ref:`cape-headers-pwm_fig`.
+There are three *EHRPWM's* which each has a pair of pwm channels. Each pair must have the same period.
.. _cape-headers-pwm_fig:
-Table of PWM outputs
-
.. figure:: figures/cape-headers-pwm.png
:align: center
:alt: PWM outputs
-The pwm's are accessed through +/dev/bone/pwm+
+ Table of PWM outputs
+
+The pwm's are accessed through */dev/bone/pwm*
-.. todo:: Should this be /dev/bone/pwm?
+.. todo
+ Should this be /dev/bone/pwm?
.. code-block:: bash
@@ -256,7 +240,7 @@ The pwm's are accessed through +/dev/bone/pwm+
bone$ ls
0 1 2
-Here we see six pwmchips that can be used, each has two channels. Explore one.
+Here we see six pwmchips that can be used, each has two channels. Explore one.
.. code-block:: bash
@@ -278,14 +262,12 @@ Here we see six pwmchips that can be used, each has two channels. Explore one.
Your LED should now be flashing.
-:ref:`<display_pwm_mapping>` are the mapping I've figured out
+:ref:`display_pwm_mapping` are the mapping I've figured out
so far. I don't know how to get to the timers.
.. _display_pwm_mapping:
-Headers to pwm channel mapping.
-
-.. table::
+.. table:: Headers to pwm channel mapping
+-------+-----+-----------+
| Pin | pwm | channel |
@@ -305,42 +287,45 @@ Headers to pwm channel mapping.
Writing to an LED Matrix
---------------------------
+=========================
Problem
-*************
+--------
-You have an I^2^C-based LED matrix to interface.
+You have an |I2C|-based LED matrix to interface.
Solution
-*************
+--------
There are a number of nice LED matrices that allow you to control several LEDs via one interface.
-This solution uses an `Adafruit Bicolor 8x8 LED Square Pixel Matrix w/I^2^C Backpack <http://www.adafruit.com/products/902>`_.
+This solution uses an `Adafruit Bicolor 8x8 LED Square Pixel Matrix w/|I2C| Backpack <http://www.adafruit.com/products/902>`_.
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* Two 4.7 kΩ resistors (see :ref:`app resistor <app_resistor>`)
-* I^2^C LED matrix (see :ref:`app opto <app_opto>`)
+* Breadboard and jumper wires
+* Two 4.7 R resistors.
+* |I2C| LED matrix
-The LED matrix is a 5 V device, but you can drive it from 3.3 V. Wire, as shown in :ref:`<displays_i2cMatrix_fig>>.
+The LED matrix is a 5 V device, but you can drive it from 3.3 V. Wire, as shown in :ref:`displays_i2cMatrix_fig`.
.. _displays_i2cMatrix_fig:
-Wiring an I^2^C LED matrix
-
.. figure:: figures/i2cMatrix_bb.png
:align: center
- :alt: I^2^C LED matrix
+ :alt: |I2C| LED matrix
+
+ Wiring an |I2C| LED matrix
+
+:ref:`sensors_i2c_temp` shows how to use *i2cdetect* to discover the address of an |I2C| device.
-:ref:`<sensors_i2c_temp>` shows how to use +i2cdetect+ to discover the address of an I^2^C device.
+.. |I2C| replace:: I\ :sub:`2`\ C
-Run the +i2cdetect -y -r 2+ command to discover the address of the display on I^2^C bus 2, as shown in :ref:`<displays_i2cdetect>>.
+Run the *i2cdetect -y -r 2* command to discover the address of the display on |I2C| bus 2, as shown in :ref:`displays_i2cdetect`.
.. _displays_i2cdetect:
-Using I^2^C command-line tools to discover the address of the display
+Using |I2C| command-line tools to discover the address of the display
+======================================================================
.. code-block:: bash
@@ -355,10 +340,10 @@ Using I^2^C command-line tools to discover the address of the display
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
70: 70 -- -- -- -- -- -- --
-Here, you can see a device at +0x49+ and +0x70+. I know I have a temperature
-sensor at +0x49+, so the LED matrix must be at +0.70+.
+Here, you can see a device at *0x49* and *0x70*. I know I have a temperature
+sensor at *0x49*, so the LED matrix must be at *0.70*.
-Find the code in :ref:`<displays_matrix_i2c>` and run it by using the following command:
+Find the code in :ref:`displays_matrix_i2c` and run it by using the following command:
.. code-block:: bash
@@ -368,91 +353,90 @@ Find the code in :ref:`<displays_matrix_i2c>` and run it by using the following
.. _displays_matrix_i2c:
LED matrix display (matrixLEDi2c.py)
+=====================================
.. code-block:: C
include::code/matrixLEDi2c.py
-<1> This line states which bus to use. The last digit gives the BoneScript bus number.
+1. This line states which bus to use. The last digit gives the BoneScript bus number.
-<2> This specifies the address of the LED matrix, +0x70+ in our case.
+2. This specifies the address of the LED matrix, *0x70* in our case.
-<3> This indicates which LEDs to turn on. The first byte is for the first column of _green_ LEDs. In this case, all are turned off. The next byte is for the first column of _red_ LEDs. The hex +0x3c+ number is +0b00111100+ in binary. This means the first two red LEDs are off, the next four are on, and the last two are off. The next byte (+0x00+) says the second column of _green_ LEDs are all off, the fourth byte (+0x42+ = +0b01000010+) says just two +red+ LEDs are on, and so on. Declarations define four different patterns to display on the LED matrix, the last being all turned off.
+3. This indicates which LEDs to turn on. The first byte is for the first column of ``green`` LEDs. In this case, all are turned off. The next byte is for the first column of ``red`` LEDs. The hex *0x3c* number is *0b00111100* in binary. This means the first two red LEDs are off, the next four are on, and the last two are off. The next byte (*0x00*) says the second column of *green* LEDs are all off, the fourth byte (*0x42* = *0b01000010*) says just two *red* LEDs are on, and so on. Declarations define four different patterns to display on the LED matrix, the last being all turned off.
-<4> Send three commands to the matrix to get it ready to display.
+4. Send three commands to the matrix to get it ready to display.
-<5> Now, we are ready to display the various patterns. After each pattern is displayed, we sleep a certain amount of time so that the pattern can be seen.
+5. Now, we are ready to display the various patterns. After each pattern is displayed, we sleep a certain amount of time so that the pattern can be seen.
-<6> Finally, send commands to the LED matrix to set the brightness. This makes the disply fade out and back in again.
-
-Discussion
-*************
+6. Finally, send commands to the LED matrix to set the brightness. This makes the disply fade out and back in again.
.. _displays_drive5V:
Driving a 5 V Device
---------------------------
+=====================
Problem
-*************
+--------
+
You have a 5 V device to drive, and the Bone has 3.3 V outputs.
Solution
-*************
+---------
+
If you are lucky, you might be able to drive a 5 V device from the Bone's 3.3 V output.
Try it and see if it works. If not, you need a level translator.
What you will need for this recipe:
-* A PCA9306 level translator (see :ref:`app ic<app_ic>`)
+* A PCA9306 level translator (see :ref:`app_ic`)
* A 5 V power supply (if the Bone's 5 V power supply isn't enough)
The PCA9306 translates signals at 3.3 V to 5 V in both directions. It's meant to work with
-I^2^C devices that have a pull-up resistor, but it can work with anything needing translation.
+|I2C| devices that have a pull-up resistor, but it can work with anything needing translation.
-:ref:`<displays_i2cMatrixLevelTrans_fig>` shows how to wire a PCA9306 to an LED matrix.
-The left is the 3.3 V side and the right is the 5 V side. Notice that we are using the Bone's built-in 5 V power supply.
+:ref:`displays_i2cMatrixLevelTrans_fig` shows how to wire a PCA9306 to an LED matrix.
+The left is the 3.3 V side and the right is the 5 V side. Notice that we are using
+the Bone's built-in 5 V power supply.
.. _displays_i2cMatrixLevelTrans_fig:
-Wiring a PCA9306 level translator to an LED matrix
-
.. figure:: figures/i2cMatrixLevelTrans_bb.png
:align: center
:alt: PCA9306 level translator
-.. note:: If your device needs more current than the Bone's 5 V power supply provides, you can wire in an external power supply.
-
+ Wiring a PCA9306 level translator to an LED matrix
-Discussion
-*************
+.. note::
+ If your device needs more current than the Bone's 5 V power
+ supply provides, you can wire in an external power supply.
Writing to a NeoPixel LED String Using the PRUs
---------------------------
+================================================
Problem
-*************
+--------
-You have an :ref:`Adafruit NeoPixel LED string <http://www.adafruit.com/products/1138>`_ or
+You have an `Adafruit NeoPixel LED string <http://www.adafruit.com/products/1138>`_ or
`Adafruit NeoPixel LED matrix <http://www.adafruit.com/products/1487>`_ and want to light it up.
Solution
-*************
+---------
The PRU Cookbook has a nice discussion
-(https://markayoder.github.io/PRUCookbook/05blocks/blocks.html#blocks_ws2812[WS2812 (NeoPixel) driver]) on driving NeoPixels.
+(`WS2812 (NeoPixel) driver <https://markayoder.github.io/PRUCookbook/05blocks/blocks.html#blocks_ws2812>`_) on driving NeoPixels.
.. _py_neoPixelMatrix_fig:
-Wiring an Adafruit NeoPixel LED matrix to +P9_29+
-
.. figure:: figures/neo_bb.png
:align: center
:alt: NeoPixel Ring
+ Wiring an Adafruit NeoPixel LED matrix to *P9_29*
+
Writing to a NeoPixel LED String Using LEDscape
-------------------------------------------------
+================================================
.. // .. todo:: Remove?
.. // Problem
@@ -462,7 +446,7 @@ Writing to a NeoPixel LED String Using LEDscape
.. // Solution
.. *************
-.. // Wire up an Adafruit NeoPixel LED 8-by-8 matrix as shown in :ref:`<js_neoPixelMatrix_fig>>.
+.. // Wire up an Adafruit NeoPixel LED 8-by-8 matrix as shown in :ref:`js_neoPixelMatrix_fig`.
.. // .. _js_neoPixelMatrix_fig:
@@ -471,7 +455,7 @@ Writing to a NeoPixel LED String Using LEDscape
.. :align: center
.. :alt: NeoPixel Matrix
-.. // :ref:`<js_neoPixel_code>` shows how to install LEDscape and run the LEDs.
+.. // :ref:`js_neoPixel_code` shows how to install LEDscape and run the LEDs.
.. // .. _js_neoPixel_code:
@@ -489,34 +473,30 @@ Writing to a NeoPixel LED String Using LEDscape
.. *************
Making Your Bone Speak
---------------------------
+=======================
Problem
-*************
+--------
+
Your Bone wants to talk.
Solution
-*************
-Just install the _flite_ text-to-speech program:
+---------
+
+Just install the ``flite`` text-to-speech program:
.. code-block:: bash
bone$ sudo apt install flite
-
-Then add the code from :ref:`<speak_code>` in a file called _speak.js_ and run.
+Then add the code from :ref:`speak_code` in a file called ``speak.js`` and run.
.. _speak_code:
-A program that talks (speak.js)
-
-.. code-block:: JavaScript
+.. literalinclude:: code/speak.js
+ :caption: A program that talks (speak.js)
+ :linenos:
- include::code/speak.js
+:download:`speak.js <code/speak.js>`
-
-
-See :ref:`<sensors_audio>` to see how to use a USB audio dongle and set your default audio out.
-
-Discussion
-*************
+See :ref:`sensors_audio` to see how to use a USB audio dongle and set your default audio out.
diff --git a/books/beaglebone-cookbook/04motors/motors.rst b/books/beaglebone-cookbook/04motors/motors.rst
index b5fb69ab..eff2f3e0 100644
--- a/books/beaglebone-cookbook/04motors/motors.rst
+++ b/books/beaglebone-cookbook/04motors/motors.rst
@@ -4,10 +4,10 @@ Motors
########
Introduction
---------------
+**************
One of the many fun things about embedded computers is that you can move physical things with motors.
-But there are so many different kinds of motors (_servo_, _stepper_, _DC_), so how do you select the right one?
+But there are so many different kinds of motors (``servo``, ``stepper``, ``DC``), so how do you select the right one?
The type of motor you use depends on the type of motion you want:
@@ -15,7 +15,7 @@ The type of motor you use depends on the type of motion you want:
Can be quickly positioned at various absolute angles, but some don't spin. In fact, many can turn only about 180{deg}.
- Stepper motor
- Spins and can also rotate in precise relative angles, such as turning 45{deg}. Stepper motors come in two types: _bipolar_ (which has four wires) and _unipolar_ (which has five or six wires).
+ Spins and can also rotate in precise relative angles, such as turning 45{deg}. Stepper motors come in two types: ``bipolar`` (which has four wires) and ``unipolar`` (which has five or six wires).
- DC motor
Spins either clockwise or counter-clockwise and can have the greatest speed of the three. But a DC motor can't easily be made to turn to a given angle.
@@ -24,7 +24,7 @@ When you know which type of motor to use, interfacing is easy. This chapter show
.. note::
Motors come in many sizes and types. This chapter presents some of the more popular
types and shows how they can interface easily to the Bone. If you need to turn on and
- off a 120 V motor, consider using something like the PowerSwitch presented in :ref:`<displays_powerSwitch>`.
+ off a 120 V motor, consider using something like the PowerSwitch presented in :ref:`displays_powerSwitch`.
.. note::
The Bone has built-in 3.3 V and 5 V supplies, which can supply enough current to drive
@@ -33,39 +33,39 @@ When you know which type of motor to use, interfacing is easy. This chapter show
.. note::
All the examples in the book assume you have cloned the Cookbook repository on
- www.github.com. Go here :ref:`<basics_repo>` for instructions.
+ www.github.com. Go here :ref:`basics_repo` for instructions.
.. _motors_servo:
Controlling a Servo Motor
-----------------------------
+==========================
Problem
-**************
+--------
You want to use BeagleBone to control the absolute position of a servo motor.
Solution
-**************
+--------
-We'll use the pulse width modulation (PWM) hardware of the Bone to control a
-servo motor.
+We'll use the pulse width modulation (PWM)
+hardware of the Bone to control a servo motor.
To make the recipe, you will need:
-* Servo motor (see :ref:`<app_misc>`)
-* Breadboard and jumper wires (see :ref:`<app_proto>`)
-* 1 kΩ resistor (optional, see :ref:`<app_resistor>`)
-* 5 V power supply (optional, see :ref:`<app_misc>`)
+* Servo motor.
+* Breadboard and jumper wires.
+* 1 kΩ resistor (optional)
+* 5 V power supply (optional)
The 1 kΩ resistor isn't required, but it provides some protection to the general-purpose
input/output (GPIO) pin in case the servo fails and draws a large current.
-Wire up your servo, as shown in :ref:`<motors_servoMotor>`.
+Wire up your servo, as shown in :ref:`motors_servoMotor`.
.. note::
There is no standard for how servo motor wires are colored. One of my servos is wired
- like :ref:`<motors_servoMotor>`: red is 3.3 V, black is ground, and yellow is the control line.
+ like :ref:`motors_servoMotor` red is 3.3 V, black is ground, and yellow is the control line.
I have another servo that has red as 3.3 V and ground is brown, with the control line being orange.
Generally, though, the 3.3 V is in the middle. Check the datasheet for your servo before wiring.
@@ -75,10 +75,10 @@ Wire up your servo, as shown in :ref:`<motors_servoMotor>`.
:align: center
:alt: Servo Motor
-Driving a servo motor with the 3.3 V power supply
+ 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.
+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
@@ -86,44 +86,38 @@ in :ref:`<py_servoMotor_code>`. You need to configure the pin for PWM.
bone$ <strong>config-pin P9_16 pwm</strong>
bone$ <strong>./servoMotor.py</strong>
-
-
.. _py_servoMotor_code:
-Code for driving a servo motor (servoMotor.py)
-
-.. code-block:: python
-
- include::code/servoMotor.py[]
+.. literalinclude:: code/servoMotor.py
+ :caption: Code for driving a servo motor (servoMotor.py)
+ :linenos:
+:download:`servoMotor.py <code/servoMotor.py>`
.. _motors_servoMotor_code:
-Code for driving a servo motor (servoMotor.js)
-
-.. code-block:: JavaScript
+.. literalinclude:: code/servoMotor.js
+ :caption: Code for driving a servo motor (servoMotor.js)
+ :linenos:
- include::code/servoMotor.js[]
+:download:`servoMotor.js <code/servoMotor.js>`
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.
-Discussion
-**************
-
Controlling a Servo with an Rotary Encoder
---------------------------------------------
+==========================================
Problem
-**************
+--------
-You have a rotary encoder from :ref:`<digital_rotaryEncoder_js>` that you want to control a servo motor.
+You have a rotary encoder from :ref:`digital_rotaryEncoder_js` that you want to control a servo motor.
Solution
-**************
+---------
-Combine the code from :ref:`<digital_rotaryEncoder_js>` and :ref:`<motors_servo>`.
+Combine the code from :ref:`digital_rotaryEncoder_js` and :ref:`motors_servo`.
.. code-block:: bash
@@ -135,47 +129,47 @@ Combine the code from :ref:`<digital_rotaryEncoder_js>` and :ref:`<motors_servo>
.. _py_servoEncoder_code:
-Code for driving a servo motor with a rotary encorder(servoEncoder.py)
+.. literalinclude:: code/servoEncoder.py
+ :caption: Code for driving a servo motor with a rotary encorder(servoEncoder.py)
+ :linenos:
-.. code-block:: python
-
- include::code/servoEncoder.py[]
+:download:`servoEncoder.py <code/servoEncoder.py>`
.. _motors_dcSpeed:
Controlling the Speed of a DC Motor
--------------------------------------
+===================================
Problem
-**************
+--------
You have a DC motor (or a solenoid) and want a simple way to control its speed, but not the direction.
Solution
-**********
+---------
It would be nice if you could just wire the DC motor to BeagleBone Black and have it work,
but it won't. Most motors require more current than the GPIO ports on the Bone can supply.
Our solution is to use a transistor to control the current to the bone.
Here we configure the encoder to returns value between 0 and 180 inclusive. This value is then
-mapped to a value between +min+ (0.6 ma) and +max+ (2.5 ms). This number is converted from
+mapped to a value between *min* (0.6 ma) and *max* (2.5 ms). This number is converted from
milliseconds and nanoseconds (time 1000000) and sent to the servo motor via the pwm.
Here's what you will need:
* 3 V to 5 V DC motor
-* Breadboard and jumper wires (see :ref:`<app_proto>`)
-* 1 kΩ resistor (see :ref:`<app_resistor>`)
-* Transistor 2N3904 (see :ref:`<app_transistor>`)
-* Diode 1N4001 (see :ref:`<app_transistor>`)
+* Breadboard and jumper wires.
+* 1 kΩ resistor.
+* Transistor 2N3904.
+* Diode 1N4001.
* Power supply for the motor (optional)
If you are using a larger motor (more current),
you will need to use a larger transistor.
-Wire your breadboard as shown in :ref:`<motors_dcMotor_fig>`.
+Wire your breadboard as shown in :ref:`motors_dcMotor_fig`.
.. _motors_dcMotor_fig:
@@ -183,63 +177,55 @@ Wire your breadboard as shown in :ref:`<motors_dcMotor_fig>`.
:align: center
:alt: DC Motor
-Wiring a DC motor to spin one direction
-
-Use the code in :ref:`<motors_dcMotor_code>`
-(_dcMotor.js_) to run the motor.
+ Wiring a DC motor to spin one direction
+Use the code in :ref:`motors_dcMotor_code` (``dcMotor.js``) to run the motor.
.. _py_dcMotor_code:
-Driving a DC motor in one direction (dcMotor.py)
+.. literalinclude:: code/dcMotor.py
+ :caption: Driving a DC motor in one direction (dcMotor.py)
+ :linenos:
-.. code-block:: python
-
- include::code/dcMotor.py[]
+:download:`dcMotor.py <code/dcMotor.py>`
.. _motors_dcMotor_code:
-Driving a DC motor in one direction (dcMotor.js)
-
-.. code-block:: JavaScript
-
- include::code/dcMotor.js[]
-
-Discussion
-**************
+.. literalinclude:: code/dcMotor.js
+ :caption: Driving a DC motor in one direction (dcMotor.js)
+ :linenos:
+:download:`dcMotor.js <code/dcMotor.js>`
See Also
-**************
+=========
-How do you change the direction of the motor? See :ref:`<motors_dcDirection>`.
+How do you change the direction of the motor? See :ref:`motors_dcDirection`.
.. _motors_dcDirection:
Controlling the Speed and Direction of a DC Motor
---------------------------------------------------
-
-// TODO
+==================================================
Problem
-**************
+--------
You would like your DC motor to go forward and backward.
Solution
-**************
+---------
Use an H-bridge to switch the terminals on the motor so that it will run both backward
-and forward. We'll use the _L293D_: a common, single-chip H-bridge.
+and forward. We'll use the ``L293D`` a common, single-chip H-bridge.
Here's what you will need:
-* 3 V to 5 V motor (see :ref:`<app_misc>`)
-* Breadboard and jumper wires (see :ref:`<app_proto>`)
-* L293D H-Bridge IC (see :ref:`<app_ic>`)
+* 3 V to 5 V motor.
+* Breadboard and jumper wires.
+* L293D H-Bridge IC.
* Power supply for the motor (optional)
-Lay out your breadboard as shown in :ref:`<motors_h-bridge_fig>`. Ensure that the L293D is positioned correctly.
+Lay out your breadboard as shown in :ref:`motors_h-bridge_fig`. Ensure that the L293D is positioned correctly.
There is a notch on one end that should be pointed up.
.. _motors_h-bridge_fig:
@@ -248,45 +234,40 @@ There is a notch on one end that should be pointed up.
:align: center
:alt: H-bridge Motor
-Driving a DC motor with an H-bridge
+ Driving a DC motor with an H-bridge
-The code in :ref:`<motors_h-bridge_code>` (_h-bridgeMotor.js_) looks much like the code for driving the DC
-motor with a transistor (:ref:`<motors_dcMotor_code>`).
-The additional code specifies which direction to spin the motor.
+The code in :ref:`motors_h-bridge_code` (``h-bridgeMotor.js``) looks much like the code for driving the DC
+motor with a transistor (:ref:`motors_dcMotor_code`). The additional code specifies which direction to spin the motor.
.. _motors_h-bridge_code:
-Code for driving a DC motor with an H-bridge (h-bridgeMotor.js)
-
-.. code-block:: JavaScript
-
- include::code/h-bridgeMotor.js[]
+.. literalinclude:: code/h-bridgeMotor.js
+ :caption: Code for driving a DC motor with an H-bridge (h-bridgeMotor.js)
+ :linenos:
-
-Discussion
-**************
+:download:`h-bridgeMotor.js <code/h-bridgeMotor.js>`
Driving a Bipolar Stepper Motor
----------------------------------
+===============================
Problem
-**************
+--------
You want to drive a stepper motor that has four wires.
Solution
-**************
+---------
Use an L293D H-bridge. The bipolar stepper motor requires
us to reverse the coils, so we need to use an H-bridge.
Here's what you will need:
-* Breadboard and jumper wires (see :ref:`<app_proto>`)
-* 3 V to 5 V bipolar stepper motor (see :ref:`<app_misc>`)
-* L293D H-Bridge IC (see :ref:`<app_ic>`)
+* Breadboard and jumper wires.
+* 3 V to 5 V bipolar stepper motor.
+* L293D H-Bridge IC.
-Wire as shown in :ref:`<motors_bipolar_fig>`.
+Wire as shown in :ref:`motors_bipolar_fig`.
.. _motors_bipolar_fig:
@@ -294,62 +275,52 @@ Wire as shown in :ref:`<motors_bipolar_fig>`.
:align: center
:alt: Bipolar Stepper Motor
-Bipolar stepper motor wiring
+ Bipolar stepper motor wiring
-Use the code in :ref:`<motors_stepperMotor_code>` to drive the motor.
+Use the code in :ref:`motors_stepperMotor_code_py` to drive the motor.
.. _motors_stepperMotor_code_py:
-Driving a bipolar stepper motor (bipolarStepperMotor.py)
-
-.. code-block:: python
-
- include::code/bipolarStepperMotor.py[]
-
-.. _motors_stepperMotor_code:
-
-Driving a bipolar stepper motor (bipolarStepperMotor.js)
-
-.. code-block:: JavaScript
-
- include::code/bipolarStepperMotor.js[]
-
+.. literalinclude:: code/bipolarStepperMotor.py
+ :caption: Driving a bipolar stepper motor (bipolarStepperMotor.py)
+ :linenos:
+:download:`bipolarStepperMotor.py <code/bipolarStepperMotor.py>`
When you run the code, the stepper motor will rotate back and forth.
-Discussion
-**************
-
Driving a Unipolar Stepper Motor
------------------------------------
+=================================
Problem
-**************
+--------
You want to drive a stepper motor that has five or six wires.
Solution
-**************
+---------
-If your stepper motor has five or six wires, it's a _unipolar_ stepper and
+If your stepper motor has five or six wires, it's a ``unipolar`` stepper and
is wired differently than the bipolar. Here, we'll use
-a _ULN2003 Darlington Transistor Array IC_ to drive the motor.
+a ``ULN2003 Darlington Transistor Array IC`` to drive the motor.
Here's what you will need:
-* Breadboard and jumper wires (see :ref:`<app_proto>`)
-* 3 V to 5 V unipolar stepper motor (see :ref:`<app_misc>`)
-* ULN2003 Darlington Transistor Array IC (see :ref:`<app_ic>`)
+* Breadboard and jumper wires.
+* 3 V to 5 V unipolar stepper motor.
+* ULN2003 Darlington Transistor Array IC.
-Wire, as shown in :ref:`<motors_unipolar_fig>`.
+Wire, as shown in :ref:`motors_unipolar_fig`.
-.. note:: The IC in :ref:`<motors_unipolar_fig>` is illustrated upside down from the way it is usually displayed.
+.. note::
+
+ The IC in :ref:`motors_unipolar_fig` is illustrated
+ upside down from the way it is usually displayed.
That is, the notch for pin 1 is on the bottom. This made drawing the diagram much cleaner.
-Also, notice the _banded_ wire running the +P9_7+ (5 V) to the UL2003A.
+Also, notice the ``banded`` wire running the *P9_7* (5 V) to the UL2003A.
The stepper motor I'm using runs better at 5 V, so I'm using the Bone's 5 V power supply.
The signal coming from the GPIO pins is 3.3 V, but the U2003A will step them up to 5 V to drive the motor.
@@ -361,29 +332,31 @@ The signal coming from the GPIO pins is 3.3 V, but the U2003A will step them up
Unipolar stepper motor wiring
-The code for driving the motor is in _unipolarStepperMotor.js_; however, it is almost identical to the bipolar stepper code (:ref:`<motors_stepperMotor_code>`), so :ref:`<motors_unistepperMotor_code>` shows only the lines that you need to change.
+The code for driving the motor is in ``unipolarStepperMotor.js`` however, it is
+almost identical to the bipolar stepper code (:ref:`motors_stepperMotor_code_py`),
+so :ref:`motors_unistepperMotor_code` shows only the lines that you need to change.
.. _motors_unistepperMotor_js_code:
-Changes to bipolar code to drive a unipolar stepper motor (unipolarStepperMotor.py.diff)
-
-.. code-block:: python
+.. literalinclude:: code/unipolarStepperMotor.py.diff
+ :caption: Changes to bipolar code to drive a unipolar stepper motor (unipolarStepperMotor.py.diff)
+ :linenos:
- include::code/unipolarStepperMotor.py.diff[]
+:download:`unipolarStepperMotor.py.diff <code/unipolarStepperMotor.py.diff>`
.. _motors_unistepperMotor_code:
-Changes to bipolar code to drive a unipolar stepper motor (unipolarStepperMotor.js.diff)
+.. literalinclude:: code/unipolarStepperMotor.js.diff
+ :caption: Changes to bipolar code to drive a unipolar stepper motor (unipolarStepperMotor.js.diff)
+ :linenos:
-.. code-block:: JavaScript
-
- include::code/unipolarStepperMotor.js.diff[]
+:download:`unipolarStepperMotor.js.diff <code/unipolarStepperMotor.js.diff>`
The code in this example makes the following changes:
-* The +states+ are different. Here, we have two pins high at a time.
-* The time between steps (+ms+) is shorter, and the number of steps per direction (+max+) is bigger. The unipolar stepper I'm using has many more steps per rotation, so I need more steps to make it go around.
+* The *states* are different. Here, we have two pins high at a time.
+* The time between steps (*ms*) is shorter, and the number of steps per
-Discussion
-**************
+direction (*max*) is bigger. The unipolar stepper I'm using has many
+more steps per rotation, so I need more steps to make it go around.
diff --git a/books/beaglebone-cookbook/05tips/tips.rst b/books/beaglebone-cookbook/05tips/tips.rst
index 89ff503d..a78e2dcf 100644
--- a/books/beaglebone-cookbook/05tips/tips.rst
+++ b/books/beaglebone-cookbook/05tips/tips.rst
@@ -4,63 +4,67 @@ Beyond the Basics
##################
Introduction
----------------
+*************
-In :ref:`<basics>`, you learned how to set up BeagleBone Black, and
-:ref:`<sensors>`, :ref:`<displays>`, and :ref:`<motors>` showed how to
+In :ref:`beaglebone-cookbook-basics`, you learned how to set up BeagleBone Black, and
+:ref:`beaglebone-cookbook-sensors`, :ref:`beaglebone-cookbook-displays`,
+and :ref:`beaglebone-cookbook-motors` showed how to
interface to the physical world. The remainder of the book moves into some
more exciting advanced topics, and this chapter gets you ready for them.
The recipes in this chapter assume that you are running Linux on your host
-computer (:ref:`<tips_pick_os>`) and are comfortable with using Linux. We
-continue to assume that you are logged in as +debian+ on your Bone.
+computer (:ref:`tips_pick_os`) and are comfortable with using Linux. We
+continue to assume that you are logged in as *debian* on your Bone.
.. _tips_hdmi:
Running Your Bone Standalone
------------------------------
+=============================
Problem
-*********
+--------
You want to use BeagleBone Black as a desktop computer with keyboard, mouse, and an HDMI display.
Solution
-*************
+---------
The Bone comes with USB and a microHDMI output. All you need to do is connect your keyboard, mouse, and HDMI display to it.
To make this recipe, you will need:
-* Standard HDMI cable and female HDMI-to-male microHDMI adapter (see :ref:`<app_misc>`), or
-* MicroHDMI-to-HDMI adapter cable (see :ref:`<app_misc>`)
-* HDMI monitor (see :ref:`<app_misc>`)
+* Standard HDMI cable and female HDMI-to-male microHDMI adapter, or
+* MicroHDMI-to-HDMI adapter cable
+* HDMI monitor
* USB keyboard and mouse
-* Powered USB hub (see :ref:`<app_misc>`)
+* Powered USB hub
+
+.. note::
-.. note::
The microHDMI adapter is nice because it allows you to use a regular HDMI cable
with the Bone. However, it will block other ports and can damage the Bone if you
aren't careful. The microHDMI-to-HDMI cable won't have these problems.
.. tip::
- You can also use an HDMI-to-DVI cable (:ref:`<app_misc>`)
+
+ You can also use an HDMI-to-DVI cable
and use your Bone with a DVI-D display.
-The adapter looks something like :ref:`<tips_HDMI_adaptor_fig>`.
+The adapter looks something like :ref:`tips_HDMI_adaptor_fig`.
.. _tips_HDMI_adaptor_fig:
-
.. figure:: figures/hdmiConverter.jpg
:align: center
:alt: HDMI Adaptor
Female HDMI-to-male microHDMI adapter
-Plug the small end into the microHDMI input on the Bone and plug your HDMI cable into the other end of the adapter and your monitor. If nothing displays on your Bone, reboot.
+Plug the small end into the microHDMI input on the Bone and plug your HDMI cable into the other end of the
+adapter and your monitor. If nothing displays on your Bone, reboot.
-If nothing appears after the reboot, edit the _/boot/uEnv.txt_ file. Search for the line containing +disable_uboot_overlay_video=1 and make sure it's commented out:
+If nothing appears after the reboot, edit the ``/boot/uEnv.txt`` file. Search for the line containing
+``disable_uboot_overlay_video=1`` and make sure it's commented out:
.. code-block:: bash
@@ -71,74 +75,79 @@ If nothing appears after the reboot, edit the _/boot/uEnv.txt_ file. Search for
Then reboot.
-.. PRODUCTION: in the following tip, we're trying to display the hash symbol (#), all by itself, in constant width. Using +#+ produces an empty space in the build, and I don't know how to escape special characters within what should be literal strings.
+.. PRODUCTION: in the following tip, we're trying to display the hash symbol (#), all by itself, in constant width. Using *#* produces an empty space in the build, and I don't know how to escape special characters within what should be literal strings.
.. Adding to my confusion, the # signs are dropped in the first paragraph of the tip, but not in the second, which is formatted in the same exact way.
.. Also, using ## in the code italicizes the second # and everything after it in the line, which should not happen.
-The _/boot/uEnv.txt_ file contains a number of configuration commands that are executed at boot time. The +#+ character is used to add comments; that is, everything to the right of a +# is ignored by the Bone and is assumed to be for humans to read. In the previous example, +###Disable auto loading+ is a comment that informs us the next line(s) are for disabling things. Two +disable_uboot_overlay+ commands follow. Both should be commented-out and won't be executed by the Bon
-Why not just remove the line? Later, you might decide you need more general-purpose input/output (GPIO) pins and don't need the HDMI display. If so, just remove the +#+ from the +disable_uboot_overlay_video=1+ command. If you had completely removed the line earlier, you would have to look up the details somewhere to re-create it.
+The ``/boot/uEnv.txt`` file contains a number of configuration commands that are executed at boot time.
+The *#* character is used to add comments; that is, everything to the right of a +# is ignored by the
+Bone and is assumed to be for humans to read. In the previous example, *###Disable auto loading* is
+a comment that informs us the next line(s) are for disabling things. Two *disable_uboot_overlay*
+commands follow. Both should be commented-out and won't be executed by the Bon
-When in doubt, comment-out; don't delete.
+Why not just remove the line? Later, you might decide you need more general-purpose input/output
+(GPIO) pins and don't need the HDMI display. If so, just remove the *#* from the ``disable_uboot_overlay_video=1``
+command. If you had completely removed the line earlier, you would have to look up the details somewhere to re-create it.
+
+When in doubt, comment-out don't delete.
.. note::
+
If you want to re-enable the HDMI audio, just comment-out the line you added.
-The Bone has only one USB port, so you will need to get either a keyboard with a USB hub (see :ref:`<app_misc>`) or a USB hub. Plug the USB hub into the Bone and then plug your keyboard and mouse in to the hub. You now have a Beagle workstation; no host computer is needed.
+The Bone has only one USB port, so you will need to get either a keyboard with a USB hub or a USB hub.
+Plug the USB hub into the Bone and then plug your keyboard and mouse in to the hub.
+You now have a Beagle workstation no host computer is needed.
.. tip::
- A powered hub is recommended because USB can supply only 500 mA, and you'll want to plug many things into the Bone.
-
-Discussion
-*************
+ A powered hub is recommended because USB can supply only
+ 500 mA, and you'll want to plug many things into the Bone.
This recipe disables the HDMI audio, which allows the Bone to try other resolutions.
-If this fails, see http://bit.ly/1GEPcOH[BeagleBoneBlack HDMI] for how to force the
+If this fails, see `BeagleBoneBlack HDMI <http://bit.ly/1GEPcOH>`_ for how to force the
Bone's resolution to match your monitor.
.. _tips_pick_os:
Selecting an OS for Your Development Host Computer
----------------------------------------------------
+===================================================
Problem
-*************
+--------
Your project needs a host computer, and you need to select an operating system (OS) for it.
Solution
-*************
+--------
For projects that require a host computer, we assume that you are running
-http://bit.ly/1wXOwkw[Linux Ubuntu 20.04 LTS]. You can be running either a native installation,
-through https://docs.microsoft.com/en-us/windows/wsl/[Windows Subsystem for Linux], via a virtual
-machine such as https://www.virtualbox.org/[VirtualBox], or in the cloud (https://portal.azure.com/[Microsoft Azure]
-or http://aws.amazon.com/ec2/[Amazon Elastic Compute Cloud] [EC2], for example).
+`Linux Ubuntu 20.04 LTS <http://bit.ly/1wXOwkw>`_. You can be running either a native installation,
+through `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/>`_, via a virtual
+machine such as `VirtualBox <https://www.virtualbox.org/>`_, or in the cloud (`Microsoft Azure <https://portal.azure.com/>`_
+or `Amazon Elastic Compute Cloud <http://aws.amazon.com/ec2/>`_, EC2, for example).
-Recently I've been prefering https://docs.microsoft.com/en-us/windows/wsl/[Windows Subsystem for Linux].
-
-Discussion
-*************
+Recently I've been prefering `Windows Subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/>`_.
.. _tips_shell:
Getting to the Command Shell via SSH
-------------------------
+=====================================
Problem
-*************
+--------
You want to connect to the command shell of a remote Bone from your host pass:[<span class="keep-together">computer</span>].
Solution
-*************
+---------
-:ref:`<basics_vsc_IDE>` shows how to run shell commands in the Visual Studio Code +bash+ tab.
+:ref:`basics_vsc_IDE` shows how to run shell commands in the Visual Studio Code *bash* tab.
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):
+connect by using the following command to log in as user *debian*, (note the *$* at the end of the prompt):
.. code-block:: bash
@@ -147,8 +156,10 @@ connect by using the following command to log in as user +debian+, (note the +$+
Last login: Mon Dec 22 07:53:06 2014 from yoder-linux.local
bone$
+.. _tips_passwords:
-+debian+ has the default password +tempped+ It's best to change the password:
+*debian* has the default password *tempped* It's best to change the password:
+==============================================================================
.. code-block:: bash
@@ -160,23 +171,22 @@ connect by using the following command to log in as user +debian+, (note the +$+
passwd: password updated successfully
-Discussion
-*************
-
.. _tips_serial:
Getting to the Command Shell via the Virtual Serial Port
-------------------------
+==========================================================
Problem
-*************
+--------
You want to connect to the command shell of a remote Bone from your host computer without using SSH.
Solution
-*************
+---------
-Sometimes, you can't connect to the Bone via SSH, but you have a network working over USB to the Bone. There is a way to access the command line to fix things without requiring extra hardware. (:ref:`<tips_FTDI>` shows a way that works even if you don't have a network working over USB, but it requires a special serial-to-USB cable.)
+Sometimes, you can't connect to the Bone via SSH, but you have a network working over USB to the Bone.
+There is a way to access the command line to fix things without requiring extra hardware. (:ref:`tips_FTDI`
+shows a way that works even if you don't have a network working over USB, but it requires a special serial-to-USB cable.)
First, check to ensure that the serial port is there. On the host computer, run the following command:
@@ -186,8 +196,9 @@ First, check to ensure that the serial port is there. On the host computer, run
0 crw-rw---- 1 root dialout 166, 0 Jun 19 11:47 /dev/ttyACM0
-_/dev/ttyACM0_ is a serial port on your host computer that the Bone creates when it boots up.
-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:
+``/dev/ttyACM0`` is a serial port on your host computer that the Bone creates when it boots up.
+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
@@ -201,7 +212,8 @@ Looks like I'm already in the group, but if you aren't, just add yourself to the
host$ sudo adduser $USER dialout
-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:
+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
@@ -217,33 +229,31 @@ You have to run +adduser+ only once. Your host computer will remember the next t
beaglebone login:
-The +/dev/ttyACM0+ parameter specifies which serial port to connect to, and +115200+
+The ``/dev/ttyACM0`` parameter specifies which serial port to connect to, and *115200*
tells the speed of the connection. In this case, it's 115,200 bits per second.
-Discussion
-*************
-
.. _tips_FTDI:
Viewing and Debugging the Kernel and u-boot Messages at Boot Time
-------------------------
+==================================================================
Problem
-*************
+--------
You want to see the messages that are logged by BeagleBone Black as it comes to life.
Solution
-*************
+---------
-There is no network in place when the Bone first boots up, so :ref:`<tips_shell>` and :ref:`<tips_serial>` won't work. This recipe uses some extra hardware (FTDI cable) to attach to the Bone's console serial port.
+There is no network in place when the Bone first boots up, so :ref:`tips_shell` and :ref:`tips_serial`
+won't work. This recipe uses some extra hardware (FTDI cable) to attach to the Bone's console serial port.
To make this recipe, you will need:
-* 3.3 V FTDI cable (see :ref:`<app_misc>`)
+* 3.3 V FTDI cable
.. warning::
- Be sure to get a 3.3 V FTDI cable (shown in :ref:`<tips_FTDIcable_fig>`),
+ Be sure to get a 3.3 V FTDI cable (shown in :ref:`tips_FTDIcable_fig`),
because the 5 V cables won't work.
.. tip::
@@ -259,25 +269,23 @@ To make this recipe, you will need:
FTDI cable
-Look for a small triangle at the end of the FTDI cable (:ref:`<tips_FTDIconnector_fig>`).
+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
:align: center
:alt: FTDI Connector
FTDI connector
-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
+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
@@ -285,7 +293,7 @@ and begin near pin 20. There is a white dot near P9_20.
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.
+the ``triangle`` pin on the connector to the ``white dot`` pin of the *FTDI* connector.
Now, run the following commands on your host computer:
@@ -309,19 +317,16 @@ Now, run the following commands on your host computer:
Your screen might initially be blank. Press Enter
a couple times to see the login prompt.
-Discussion
-*************
-
Verifying You Have the Latest Version of the OS on Your Bone from the Shell
------------------------------------------------------------------------------
+============================================================================
Problem
-*************
+--------
You are logged in to your Bone with a command prompt and want to know what version of the OS you are running.
Solution
-*************
+--------
Log in to your Bone and enter the following command:
@@ -331,25 +336,20 @@ Log in to your Bone and enter the following command:
BeagleBoard.org Debian Bullseye IoT Image 2022-07-01
-Discussion
-*************
-
-:ref:`<basics_latest_os>` shows how to open the _ID.txt_ file to see the OS version.
-The _/etc/dogtag_ file has the same contents and is easier to find if you already
-have a command prompt. See :ref:`<basics_install_os>` if you need to update your OS.
+:ref:`basics_latest_os` shows how to open the ``ID.txt`` file to see the OS version.
+The ``/etc/dogtag`` file has the same contents and is easier to find if you already
+have a command prompt. See :ref:`basics_install_os` if you need to update your OS.
Controlling the Bone Remotely with a VNC
-------------------------
-
-// TODO check this
+=========================================
Problem
-*************
+--------
You want to access the BeagleBone's graphical desktop from your host computer.
Solution
-*************
+---------
Run the installed Virtual Network Computing (VNC) server:
@@ -371,31 +371,29 @@ Run the installed Virtual Network Computing (VNC) server:
Log file is /home/debian/.vnc/beagleboard:1.log
-To connect to the Bone, you will need to run a VNC client. There are many to choose from. Remmina Remote Desktop Client is already installed on Ubuntu. Start and select the new remote desktop file button (:ref:`<tips_vnc1_fig>`).
+To connect to the Bone, you will need to run a VNC client. There are many to choose from. Remmina Remote
+Desktop Client is already installed on Ubuntu. Start and select the new remote desktop file button (:ref:`tips_vnc1_fig`).
.. _tips_vnc1_fig:
-
.. figure:: figures/vnc1.png
:align: center
:alt: Create a new remote desktop
Creating a new remote desktop file in Remmina Remote Desktop Client
-Give your connection a name, being sure to select "Remmina VNC Plugin" Also, be sure to add +:1+ after the server address, as shown in :ref:`<tips_vnc2_fig>`. This should match the +:1+ that was displayed when you started +vncserver+.
+Give your connection a name, being sure to select "Remmina VNC Plugin" Also, be sure to add *:1* after the
+server address, as shown in :ref:`tips_vnc2_fig`. This should match the *:1* that was displayed when you started *vncserver*.
.. _tips_vnc2_fig:
-
.. figure:: figures/vnc2.png
:align: center
:alt: Configuring
Configuring the Remmina Remote Desktop Client
-Click Connect to start graphical access to your Bone, as shown in :ref:`<tips_vnc3_fig>`.
-
-// TODO update this
+Click Connect to start graphical access to your Bone, as shown in :ref:`tips_vnc3_fig`.
.. _tips_vnc3_fig:
@@ -406,10 +404,12 @@ Click Connect to start graphical access to your Bone, as shown in :ref:`<tips_vn
The Remmina Remote Desktop Client showing the BeagleBone desktop
.. tip::
+
You might need to resize the VNC screen on your
host to see the bottom menu bar on your Bone.
.. note::
+
You need to have X Windows installed and running for the VNC to work.
Here's how to install it. This needs some 250M of disk space and 19 minutes to install.
@@ -422,27 +422,22 @@ Click Connect to start graphical access to your Bone, as shown in :ref:`<tips_vn
/usr/bin/startxfce4: 122: exec: xinit: not found
-Discussion
-*************
-
Learning Typical GNU/Linux Commands
-------------------------
+====================================
Problem
-*************
+--------
There are many powerful commands to use in Linux. How do you learn about them?
Solution
-*************
+---------
-:ref:`<tips_linux_commands>` lists many common Linux commands.
+:ref:`tips_linux_commands` lists many common Linux commands.
.. _tips_linux_commands:
-Common Linux commands
-
-.. table::
+.. table:: Common Linux commands
+--------+--------------------------------+
|Command |Action |
@@ -494,7 +489,7 @@ Common Linux commands
|apropos |show list of man pages |
+--------+--------------------------------+
|find |search for files |
- +--------+--------------------------------+
+ +--------+--------------------------------+
|tar |create/extract file archives |
+--------+--------------------------------+
|gzip |compress a file |
@@ -514,39 +509,33 @@ Common Linux commands
|whereis |locates binary and source files |
+--------+--------------------------------+
-Discussion
-*************
-
-
.. _tips_editing_files:
Editing a Text File from the GNU/Linux Command Shell
------------------------------------------------------
+=====================================================
Problem
-*************
+--------
You want to run an editor to change a file.
Solution
-*************
+---------
-The Bone comes with a number of editors. The simplest to learn is +nano+.
+The Bone comes with a number of editors. The simplest to learn is *nano*.
Just enter the following command:
.. code-block:: bash
bone$ nano file
-
-You are now in nano (:ref:`<tips_nano_fig>`). You can't move around the screen
+You are now in nano (:ref:`tips_nano_fig`). You can't move around the screen
using the mouse, so use the arrow keys. The bottom two lines of the screen
list some useful commands. Pressing ˄G (Ctrl-G) will display more useful
commands. ˄X (Ctrl-X) exits nano and gives you the option of saving the file.
.. _tips_nano_fig:
-
.. figure:: figures/nano.png
:align: center
:alt: nano
@@ -555,35 +544,30 @@ commands. ˄X (Ctrl-X) exits nano and gives you the option of saving the fil
.. tip::
By default, the file you create will be saved
- in the directory from which you opened +nano+.
+ in the directory from which you opened *nano*.
-Discussion
-*************
-
-
-Many other text editors will run on the Bone. +vi+, +vim+, +emacs+, and even +eclipse+ are all supported.
-See :ref:`<tips_apt>` to learn if your favorite is one of them.
+Many other text editors will run on the Bone. *vi*, *vim*, *emacs*, and even *eclipse* are all supported.
+See :ref:`tips_apt` to learn if your favorite is one of them.
.. _networking_wired:
Establishing an Ethernet-Based Internet Connection
-------------------------
+===================================================
Problem
-*************
+--------
You want to connect your Bone to the Internet using the wired network connection.
Solution
-*************
+---------
-Plug one end of an Ethernet patch cable into the RJ45 connector on the Bone (see :ref:`<networking_rj45>`)
+Plug one end of an Ethernet patch cable into the RJ45 connector on the Bone (see :ref:`networking_rj45`)
and the other end into your home hub/router. The yellow and green link lights on both ends should begin to flash.
.. _networking_rj45:
-
.. figure:: figures/internLED.png
:align: center
:alt: RJ45
@@ -593,9 +577,10 @@ and the other end into your home hub/router. The yellow and green link lights on
If your router is already configured to run DHCP (Dynamical Host Configuration Protocol),
it will automatically assign an IP address to the Bone.
-.. warning:: It might take a minute or two for your router to detect the Bone and assign the IP address.
+.. warning::
+ It might take a minute or two for your router to detect the Bone and assign the IP address.
-To find the IP address, open a terminal window and run the +ip+ command:
+To find the IP address, open a terminal window and run the *ip* command:
.. code-block:: bash
@@ -630,46 +615,43 @@ To find the IP address, open a terminal window and run the +ip+ command:
link/can
-My Bone is connected to the Internet in two ways: via the RJ45 connection (+eth0+) and via the USB cable (+usb0+).
-The +inet+ field shows that my Internet address is +10.0.5.144+ for the RJ45 connector.
+My Bone is connected to the Internet in two ways: via the RJ45 connection (*eth0*) and via the USB cable (*usb0*).
+The *inet* field shows that my Internet address is *10.0.5.144* for the RJ45 connector.
On my university campus, you must register your MAC address before any device will work on the network.
-The +HWaddr+ field gives the MAC address. For +eth0+, it's +c8:a0:30:a6:26:e8+.
+The *HWaddr* field gives the MAC address. For *eth0*, it's *c8:a0:30:a6:26:e8*.
The IP address of your Bone can change. If it's been assigned by DHCP, it can change at any time.
The MAC address, however, never changes; it is assigned to your ethernet device when it's manufactured.
.. warning::
- When a Bone is connected to some networks it becomes visible to the _world_. If you don't secure your Bone,
- the world will soon find it. See :ref:`<tips_passwords>` and :ref:`<tips_firewall
-On many home networks, you will be behind a firewall and won't be as visible.
+ When a Bone is connected to some networks it becomes visible to the ``world``. If you don't secure your Bone,
+ the world will soon find it. See :ref:`tips_passwords` and :ref:`tips_firewall`
-Discussion
-*************
+On many home networks, you will be behind a firewall and won't be as visible.
.. _networking_wireless:
Establishing a WiFi-Based Internet Connection
-------------------------
+==============================================
Problem
-*************
+--------
You want BeagleBone Black to talk to the Internet using a USB wireless adapter.
Solution
-*************
+---------
-
-.. tip:: For the correct instructions for the image you are using, go to
-httporum.beagleboard.org/tag/latest-images[latest-images] and click on the image you are using.
+.. tip::
+ For the correct instructions for the image you are using, go to
+ `latest-images <http://forum.beagleboard.org/tag/latest-images>`_ and click on the image you are using.
I'm running Debian 11.x (Bullseye), the middle one.
.. _tips_latest-images_fig:
-
.. figure:: figures/latest-images.png
:align: center
:alt: Latest Image Page
@@ -680,28 +662,30 @@ Scroll to the top of the page and you'll see instructions on setting up Wifi. Th
.. _tips_networkfig:
-
.. figure:: figures/network.png
:align: center
:alt: Network Setup Instructions
Instructions for setting up your network.
-// TODO is this up to date?
-Several WiFi adapters work with the Bone. Check http://bit.ly/1EbEwUo[WiFi Adapters] for the latest list.
+.. TODO
+ is this up to date?
+
+Several WiFi adapters work with the Bone. Check `WiFi Adapters <http://bit.ly/1EbEwUo>`_ for the latest list.
To make this recipe, you will need:
-* USB Wifi adapter (see :ref:`<app_misc>`)
-* 5 V external power supply (see :ref:`<app_misc>`)
+* USB Wifi adapter
+* 5 V external power supply
.. warning::
+
Most adapters need at least 1 A of current to run, and USB supplies only 0.5 A, so be sure to use an
external power supply. Otherwise, you will experience erratic behavior and random crashes.
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:
+Then run *lsusb* to ensure that your Bone found the adapter:
.. code-block:: bash
@@ -712,12 +696,16 @@ Then run +lsusb+ to ensure that your Bone found the adapter:
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
-.. note:: There is a well-known bug in the Bone's 3.8 kernel series that prevents USB devices from being discovered when hot-plugged, which is why you should reboot. Newer kernels should address this issue.
+.. note::
+ There is a well-known bug in the Bone's 3.8 kernel series that prevents USB devices from
+ being discovered when hot-plugged, which is why you should reboot. Newer kernels should address this issue.
-// TODO update
+.. TODO
+ update
-Next, run +networkctl+ to find your adapter's name. Mine is called +wlan0+, but you might see other names, such as +ra0+.
+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
@@ -735,7 +723,7 @@ Next, run +networkctl+ to find your adapter's name. Mine is called +wlan0+, but
8 links listed.
-If no name appears, try +ip a+:
+If no name appears, try *ip a*:
.. code-block:: bash
@@ -758,7 +746,7 @@ If no name appears, try +ip a+:
valid_lft forever preferred_lft forever
- Next edit the configuration file +/etc/wpa_supplicant/wpa_supplicant-wlan0.conf+.
+ Next edit the configuration file */etc/wpa_supplicant/wpa_supplicant-wlan0.conf*.
.. code-block:: bash
@@ -779,7 +767,7 @@ In the file you'll see:
}
-Change the +ssid+ and +psk+ enteries for your network. Save your file, then run:
+Change the *ssid* and *psk* enteries for your network. Save your file, then run:
.. code-block:: bash
@@ -795,50 +783,45 @@ Change the +ssid+ and +psk+ enteries for your network. Save your file, then run:
rtt min/avg/max/mdev = 19.387/19.450/19.513/0.063 ms
-+wlan0+ should now have an ip address and you should be on the network. If not, try rebooting.
-
-Discussion
-*************
-
-
+*wlan0* should now have an ip address and you should be on the network. If not, try rebooting.
.. _networking_usb:
Sharing the Host's Internet Connection over USB
-------------------------
+=================================================
-// TODO Test this
+.. TODO
+ Test this
Problem
-*************
+-------
Your host computer is connected to the Bone via the USB cable, and you want to run the network between the two.
Solution
-*************
+---------
-:ref:`<networking_wired>` shows how to connect BeagleBone Black to the Internet via the RJ45 Ethernet connector.
-This recipe shows a way to connect without using the RJ45 pass:[<span class="keep-together">connector</span>].
+:ref:`networking_wired` shows how to connect BeagleBone Black to the Internet via the RJ45 Ethernet connector.
+This recipe shows a way to connect without using the RJ45 connector.
A network is automatically running between the Bone and the host computer at boot time using the USB. The host's
-IP address is +192.168.7.1+ and the Bone's is +192.168.7.2+. Although your Bone is talking to your host, it can't
+IP address is *192.168.7.1* and the Bone's is *192.168.7.2*. Although your Bone is talking to your host, it can't
reach the Internet in general, nor can the Internet reach it. On one hand, this is good, because those who are up to
no good can't access your Bone. On the other hand, your Bone can't reach the rest of the world.
Letting your bone see the world: setting up IP masquerading
You need to set up IP masquerading on your host and configure your Bone to use it. Here is a solution that works
-with a host computer running Linux. Add the code in :ref:`<tips_ipmasq_code>` to a
-file called _ipMasquerade.sh_ on your host computer.
+with a host computer running Linux. Add the code in :ref:`tips_ipmasq_code` to a
+file called ``ipMasquerade.sh`` on your host computer.
.. _tips_ipmasq_code:
-Code for IP Masquerading (ipMasquerade.sh)
-
-.. code-block:: JavaScript
-
- include::code/ipMasquerade.sh[IP masquerade]
+.. literalinclude:: code/ipMasquerade.sh
+ :caption: Code for IP Masquerading (ipMasquerade.sh)
+ :linenos:
+:download:`ipMasquerade.sh <code/ipMasquerade.sh>`
Then, on your host, run the following commands:
@@ -848,20 +831,19 @@ Then, on your host, run the following commands:
host$ ./ipMasquerade.sh eth0
-This will direct your host to take requests from the Bone and send them to +eth0+.
-If your host is using a wireless connection, change +eth0+ to +wlan0+.
+This will direct your host to take requests from the Bone and send them to *eth0*.
+If your host is using a wireless connection, change *eth0* to *wlan0*.
Now let's set up your host to instruct the Bone what to do. Add the code
-in :ref:`<tips_setDNS>` to _setDNS.sh_ on your host computer.
+in :ref:`tips_setDNS` to ``setDNS.sh`` on your host computer.
.. _tips_setDNS:
-Code for setting the DNS on the Bone (setDNS.sh)
-
-.. code-block:: JavaScript
-
- include::code/setDNS.sh[Set DNS]
+.. literalinclude:: code/setDNS.sh
+ :caption: Code for setting the DNS on the Bone (setDNS.sh)
+ :linenos:
+:download:`setDNS.sh <code/setDNS.sh>`
Then, on your host, run the following commands:
@@ -881,15 +863,17 @@ Then, on your host, run the following commands:
This will look up what Domain Name System (DNS) servers your host is using and copy
-them to the right place on the Bone. The +ping+ command is a quick way to verify your connection.
+them to the right place on the Bone. The *ping* command is a quick way to verify your connection.
Letting the world see your bone: setting up port forwarding
Now your Bone can access the world via the USB port and your host computer, but
what if you have a web server on your Bone that you want to access from the world?
-The solution is to use _port forwarding_ from your host.
-Web servers typically listen to port +80+. First, look up the IP address of your host:
-// TODO switch to ip address
+The solution is to use port forwarding from your host.
+Web servers typically listen to port *80*. First, look up the IP address of your host:
+
+.. TODO
+ switch to ip address
.. code-block:: bash
@@ -907,14 +891,16 @@ Web servers typically listen to port +80+. First, look up the IP address of your
...
-It's the number following +inet addr:+, which in my case is +137.112.41.35+.
+It's the number following *inet addr:*, which in my case is *137.112.41.35*.
-.. tip::
- If you are on a wireless network, find the IP address associated with +wlan0+.
+.. tip::
+
+ If you are on a wireless network, find the IP address associated with *wlan0*.
Then run the following, using your host's IP address:
-// TODO check this iptables, convert to ufw
+.. TODO
+ check this iptables, convert to ufw
.. code-block:: bash
@@ -922,30 +908,26 @@ Then run the following, using your host's IP address:
-d 137.112.41.35 --dport 1080 -j DNAT --to 192.168.7.2:80
-Now browse to your host computer at port +1080+. That is, if your host's IP address
-is +123.456.789.0+, enter +123.456.789.0:1080+. The +:1080+ specifies what port number to
-use. The request will be forwarded to the server on your Bone listening to port +80+.
-(I used +1080+ here, in case your host is running a web server of its own on port +80+.)
-
-Discussion
-*************
-
+Now browse to your host computer at port *1080*. That is, if your host's IP address
+is *123.456.789.0*, enter *123.456.789.0:1080*. The *:1080* specifies what port number to
+use. The request will be forwarded to the server on your Bone listening to port *80*.
+(I used *1080* here, in case your host is running a web server of its own on port *80*.)
.. _tips_firewall:
Setting Up a Firewall
-------------------------
+======================
Problem
-*************
+--------
You have put your Bone on the network and want to limit which IP addresses can access it.
Solution
-*************
+---------
-https://www.howtogeek.com/[How-To Geek] has a great posting on how do use +ufw+, the "uncomplicated firewall".
-Check out https://www.howtogeek.com/devops/how-to-secure-your-linux-server-with-a-ufw-firewall/[How to Secure Your Linux Server with a UFW Firewall].
+`How-To Geek <https://www.howtogeek.com/>`_ has a great posting on how do use *ufw*, the "uncomplicated firewall".
+Check out `How to Secure Your Linux Server with a UFW Firewall <https://www.howtogeek.com/devops/how-to-secure-your-linux-server-with-a-ufw-firewall/>`_.
I'll summarize the initial setup here.
First install and check the status:
@@ -957,7 +939,8 @@ First install and check the status:
Status: inactive
-Now turn off everything coming in and leave on all outgoing. Note, this won't take effect until +ufw+ is enabled.
+Now turn off everything coming in and leave on all outgoing.
+Note, this won't take effect until *ufw* is enabled.
.. code-block:: bash
@@ -965,14 +948,14 @@ Now turn off everything coming in and leave on all outgoing. Note, this won't t
bone$ sudo ufw default allow outgoing
-Don't enable yet, make sure +ssh+ still has access
+Don't enable yet, make sure *ssh* still has access
.. code-block:: bash
bone$ sudo ufw allow 22
-Just to be sure, you can install +nmap+ on your host computer to see what ports are currently open.
+Just to be sure, you can install *nmap* on your host computer to see what ports are currently open.
.. code-block:: bash
@@ -990,7 +973,7 @@ Just to be sure, you can install +nmap+ on your host computer to see what ports
Nmap done: 1 IP address (1 host up) scanned in 0.19 seconds
-Currently there are three ports visible: 22, 80 and 3000(visual studio code) Now turn on the firewal and see what happends.
+Currently there are three ports visible: 22, 80 and 3000 (visual studio code) Now turn on the firewal and see what happends.
.. code-block:: bash
@@ -1022,25 +1005,22 @@ The firewall will remain on, even after a reboot. Disable it now if you don't wa
See the How-To Geek article for more examples.
-Discussion
-*************
-
.. _tips_apt:
Installing Additional Packages from the Debian Package Feed
--------------------------------------------------------------
+============================================================
Problem
-*************
+--------
You want to do more cool things with your BeagleBone by installing more programs.
Solution
-*************
+----------
.. warning::
- Your Bone needs to be on the network for this to work. See :ref:`<networking_wired>`,
- :ref:`<networking_wireless>`, or :ref:`<networking_usb>`.
+ Your Bone needs to be on the network for this to work. See :ref:`networking_wired`,
+ :ref:`networking_wireless`, or :ref:`networking_usb`.
The easiest way to install more software is to use +apt+:
@@ -1050,7 +1030,7 @@ The easiest way to install more software is to use +apt+:
bone$ sudo apt install "name of software"
-A +sudo+ is necessary since you aren't running as +root+. The first command downloads
+A *sudo* is necessary since you aren't running as *root*. The first command downloads
package lists from various repositories and updates them to get information on the
newest versions of packages and their dependencies. (You need to run it only once a week or so.)
The second command fetches the software and installs it and all packages it depends on.
@@ -1065,38 +1045,36 @@ How do you find out what software you can install? Try running this:
bone$ less /tmp/list
-The first command lists all the packages that +apt+ knows about and sorts them and stores
-them in _/tmp/list_. The second command shows why you want to put the list in a file.
-The +wc+ command counts the number of lines, words, and characters in a file. In our case,
-there are over 67,000 packages from which we can choose! The +less+ command displays the sorted
+The first command lists all the packages that *apt* knows about and sorts them and stores
+them in ``/tmp/list``. The second command shows why you want to put the list in a file.
+The *wc* command counts the number of lines, words, and characters in a file. In our case,
+there are over 67,000 packages from which we can choose! The *less* command displays the sorted
list, one page at a time. Press the space bar to go to the next page. Press Q to quit.
-Suppose that you would like to install an online dictionary (+dict+). Just run the following command:
+Suppose that you would like to install an online dictionary (*dict*). Just run the following command:
.. code-block:: bash
bone$ sudo apt install dict
-Now you can run +dict+.
-
-Discussion
-*************
+Now you can run *dict*.
.. _tips_apt_remove:
Removing Packages Installed with apt
--------------------------------------
+======================================
Problem
-*************
+--------
-You've been playing around and installing all sorts of things with +apt+ and now you want to clean things up a bit.
+You've been playing around and installing all sorts of
+things with *apt* and now you want to clean things up a bit.
Solution
-*************
+--------
-+apt+ has a +remove+ option, so you can run the following command:
+*apt* has a *remove* option, so you can run the following command:
.. code-block:: bash
@@ -1113,21 +1091,16 @@ Solution
After this operation, 164 kB disk space will be freed.
Do you want to continue [Y/n]? y
-
-Discussion
-*************
-
-
Copying Files Between the Onboard Flash and the MicroSD Card
----------------------------------------------------------------
+=============================================================
Problem
-*************
+--------
You want to move files between the onboard flash and the microSD card.
Solution
-*************
+---------
If you booted from the microSD card, run the following command:
@@ -1148,16 +1121,17 @@ If you booted from the microSD card, run the following command:
/dev/mmcblk0p1 /dev/mmcblk1 /dev/mmcblk1boot1
-The +df+ command shows what partitions are already mounted.
-The line +/dev/mmcblk0p2 7.2G 2.0G 4.9G 29% /+ shows that +mmcblk0+ partition +p2+
-is mounted as +/+, the root file system. The general rule is that the media you're booted from
-(either the onboard flash or the microSD card) will appear as +mmcblk0+.
-The second partition (+p2+) is the root of the file system.
+The *df* command shows what partitions are already mounted.
+The line */dev/mmcblk0p2 7.2G 2.0G 4.9G 29% /* shows that *mmcblk0* partition *p2*
+is mounted as */*, the root file system. The general rule is that the media you're booted from
+(either the onboard flash or the microSD card) will appear as *mmcblk0*.
+The second partition (*p2*) is the root of the file system.
-The +ls+ command shows what devices are available to mount. Because +mmcblk0+ is already mounted,
-+/dev/mmcblk1p1+ must be the other media that we need to mount. Run the following commands to mount it:
+The *ls* command shows what devices are available to mount. Because *mmcblk0* is already mounted,
+*/dev/mmcblk1p1* must be the other media that we need to mount. Run the following commands to mount it:
-// TODO update
+.. TODO
+ update
.. code-block:: bash
@@ -1171,16 +1145,14 @@ The +ls+ command shows what devices are available to mount. Because +mmcblk0+ is
dev ID.txt media opt run srv usr
-The +cd+ command takes us to a place in the file system where files are commonly mounted.
-The +mkdir+ command creates a new directory (_onboard_) to be a mount point. The +ls+
-command shows there is nothing in _onboard_. The +mount+ command makes the contents of
-the onboard flash accessible. The next +ls+ shows there now are files in _onboard_.
+The *cd* command takes us to a place in the file system where files are commonly mounted.
+The *mkdir* command creates a new directory (``onboard``) to be a mount point. The *ls*
+command shows there is nothing in ``onboard``. The *mount* command makes the contents of
+the onboard flash accessible. The next *ls* shows there now are files in ``onboard``.
These are the contents of the onboard flash, which can be copied to and from like any other file.
-Discussion
-*************
-
-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:
+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
@@ -1188,27 +1160,28 @@ This same process should also work if you have booted from the onboard flash. Wh
Freeing Space on the Onboard Flash or MicroSD Card
-----------------------------------------------------
+===================================================
Problem
-*************
+--------
You are starting to run out of room on your microSD card (or onboard flash) and
-have removed several packages you had previously installed (:ref:`<tips_apt_remove>`),
+have removed several packages you had previously installed (:ref:`tips_apt_remove`),
ut you still need to free up more space.
Solution
-*************
-
+--------
To free up space, you can remove preinstalled packages or discover big files to remove.
Removing preinstalled packages
-You might not need a few things that come preinstalled in the Debian image, including such things as OpenCV, the Chromium web browser, and some documentation.
+You might not need a few things that come preinstalled in the Debian image, including such
+things as OpenCV, the Chromium web browser, and some documentation.
.. note::
+
The Chromium web browser is the open source version of Google's Chrome web browser.
Unless you are using the Bone as a desktop computer, you can probably remove it.
@@ -1226,7 +1199,7 @@ Here's how you can remove these:
Discovering big files
-The +du+ (disk usage) command offers a quick way to discover big files:
+The *du* (disk usage) command offers a quick way to discover big files:
.. code-block:: bash
@@ -1257,18 +1230,19 @@ The +du+ (disk usage) command offers a quick way to discover big files:
1.9G /var
-If you booted from the microSD card, +du+ lists the usage of the microSD.
+If you booted from the microSD card, *du* lists the usage of the microSD.
If you booted from the onboard flash, it lists the onboard flash usage.
-The +-s+ option summarizes the results rather than displaying every file. +-h+ prints
-it in _human_ form--that is, using +M+ and +K+ postfixes rather than showing lots of digits.
-The +/*+ specifies to run it on everything in the top-level directory. It looks like a couple
+The *-s* option summarizes the results rather than displaying every file. *-h* prints
+it in _human_ form--that is, using *M* and *K* postfixes rather than showing lots of digits.
+The */** specifies to run it on everything in the top-level directory. It looks like a couple
of things disappeared while the command was running and thus produced some error messages.
-.. tip:: For more help, try +du --help+.
+.. tip::
+ For more help, try *du --help*.
-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_:
+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
@@ -1288,7 +1262,7 @@ following command to see what's taking up the space in _/var_:
16K /var/www
-A more interactive way to explore your disk usage is by installing +ncdu+ (ncurses disk usage):
+A more interactive way to explore your disk usage is by installing *ncdu* (ncurses disk usage):
.. code-block:: bash
@@ -1325,40 +1299,38 @@ After a moment, you'll see the following:
Total disk usage: 5.6 GiB Apparent size: 5.5 GiB Items: 206148
-+ncdu+ is a character-based graphics interface to +du+. You can now use your arrow
+*ncdu* is a character-based graphics interface to *du*. You can now use your arrow
keys to navigate the file structure to discover where the big unused files are. Press ? for help.
-.. warning:: Be careful not to press the D key, because it's used to delete a file or directory.
-
-Discussion
-*************
+.. warning::
+ Be careful not to press the D key, because it's used to delete a file or directory.
.. _misc_libsoc:
Using C to Interact with the Physical World
---------------------------------------------
+=============================================
Problem
-*************
+--------
You want to use C on the Bone to talk to the world.
Solution
-*************
+---------
The C solution isn't as simple as the JavaScript or Python solution, but it does work
-and is much faster. The approach is the same, write to the +/sys/class/gpio+ files.
+and is much faster. The approach is the same, write to the */sys/class/gpio* files.
.. _misc_c_blink:
-Use C to blink an LED (blinkLED.c)
-
-.. code-block:: bash
+.. literalinclude:: code/blinkLED.c
+ :caption: Use C to blink an LED (blinkLED.c)
+ :linenos:
- include::code/blinkLED.c[]
+:download:`blinkLED.c <code/blinkLED.c>`
Here, as with JavaScript and Python, the gpio pins are refered to by the Linux gpio number.
-:ref:`<tips_cape_headers_digital>` shows how the P8 and P9 Headers numbers map to the gpio number.
+:ref:`tips_cape_headers_digital` shows how the P8 and P9 Headers numbers map to the gpio number.
For this example P9_14 is used, which the table shows in gpio 50.
.. _tips_cape_headers_digital:
@@ -1379,7 +1351,3 @@ Compile and run the code:
Hit ^C to stop the blinking.
-
-Discussion
-*************
-
diff --git a/books/beaglebone-cookbook/06iot/iot.rst b/books/beaglebone-cookbook/06iot/iot.rst
index 22df18ea..8c1f61e4 100644
--- a/books/beaglebone-cookbook/06iot/iot.rst
+++ b/books/beaglebone-cookbook/06iot/iot.rst
@@ -4,36 +4,37 @@ Internet of Things
####################
Introduction
--------------
+*************
-You can easily connect BeagleBone Black to the Internet via a wire (:ref:`<networking_wired>`),
-wirelessly (:ref:`<networking_wireless>`), or through the USB to a host and then to the Internet
-(:ref:`<networking_usb>`). Either way, it opens up a world of possibilities for the "Internet of Things" (IoT).
+You can easily connect BeagleBone Black to the Internet via a wire (:ref:`networking_wired`), wirelessly
+(:ref:`networking_wireless`), or through the USB to a host and then to the Internet (:ref:`networking_usb`).
+Either way, it opens up a world of possibilities for the "Internet of Things" (IoT).
Now that you're online, this chapter offers various things to do with your connection.
Accessing Your Host Computer's Files on the Bone
--------------------------------------------------
+=================================================
Problem
-*********
+--------
You want to access a file on a Linux host computer that's attached to the Bone.
Solution
-*********
+--------
If you are running Linux on a host computer attached to BeagleBone Black,
it's not hard to mount the Bone's files on the host or the host's files on the
-Bone by using +sshfs+. Suppose that you want to access files on the host from
-the Bone. First, install +sshfs+:
+Bone by using *sshfs*. Suppose that you want to access files on the host from
+the Bone. First, install *sshfs*:
.. code-block:: bash
bone$ sudo apt install sshfs
-Now, mount the files to an empty directory (substitute your username on the host computer for +username+ and the IP address of the host for +192.168.7.1+):
+Now, mount the files to an empty directory (substitute your username on the host
+computer for *username* and the IP address of the host for *192.168.7.1*):
.. code-block:: bash
@@ -43,9 +44,12 @@ Now, mount the files to an empty directory (substitute your username on the host
bone$ ls
-The +ls+ command will now list the files in your home directory on your host computer. You can edit them as if they were local to the Bone. You can access all the files by substituting +:/+ for the +:.+ following the IP address.
+The *ls* command will now list the files in your home directory on your host computer.
+You can edit them as if they were local to the Bone. You can access all the
+files by substituting *:/* for the *:.* following the IP address.
-You can go the other way, too. Suppose that you are on your Linux host computer and want to access files on your Bone. Install +sshfs+:
+You can go the other way, too. Suppose that you are on your
+Linux host computer and want to access files on your Bone. Install *sshfs*:
.. code-block:: bash
@@ -62,79 +66,72 @@ and then access:
host$ ls
-Here, we are accessing the files on the Bone as +debian+. We’ve mounted the entire file system, starting with +/+, so you can access any file. Of course, with great power comes great responsibility, so be careful.
+Here, we are accessing the files on the Bone as *debian*. We’ve mounted the entire file system,
+starting with */*, so you can access any file. Of course, with great power comes great responsibility, so be careful.
-Discussion
-************
-
-The +sshfs+ command gives you easy access from one computer to another. When you are done, you can unmount the files by using the following commands:
+The *sshfs* command gives you easy access from one computer to another.
+When you are done, you can unmount the files by using the following commands:
.. code-block:: bash
host$ umount /mnt/bone
bone$ umount home
-
.. _networking_builtin_server:
Serving Web Pages from the Bone
-----------------------------------
+================================
Problem
-*********
+--------
You want to use BeagleBone Black as a web server.
Solution
-*********
+---------
-BeagleBone Black already has the +nginx+ web server running.
+BeagleBone Black already has the *nginx* web server running.
-When you point your browser to _192.168.7.2_, you are using the +nginx+ web server.
-The web pages are served from _/var/www/html/. Add the HTML in :ref:`<networking_index_html>`
-to a file called _/var/www/html/test.html_, and then point your browser to _192.168.7.2://test.html_.
+When you point your browser to *192.168.7.2*, you are using the *nginx* web server.
+The web pages are served from */var/www/html/*. Add the HTML in :ref:`networking_index_html`
+to a file called */var/www/html/test.html*, and then point your browser to *192.168.7.2://test.html*.
.. _networking_index_html:
-A sample web page (test.html)
-
-.. code-block:: html
-
- include::code/test.html[Sample html]
+.. literalinclude:: code/test.html
+ :caption: A sample web page (test.html)
+ :linenos:
+:download:`test.html <code/test.html>`
-
-You will see the web page shown in :ref:`<networking_node_page>`.
+You will see the web page shown in :ref:`networking_node_page`.
.. _networking_node_page:
-test.html as served by nginx
-
.. figure:: figures/nginxTest.png
:align: center
:alt: test.html served by nginx
-Discussion
-*********
+ test.html as served by nginx
.. _networking_nodejs:
Interacting with the Bone via a Web Browser
----------------------------------------------
+============================================
Problem
-*********
+--------
BeagleBone Black is interacting with the physical world nicely and you want to display that information on a web browser.
Solution
-*********
+---------
-https://www.fullstackpython.com/flask.html[Flask] is a Python web framework built
-with a small core and easy-to-extend philosophy. :ref:`<networking_builtin_server>`
+`Flask <https://www.fullstackpython.com/flask.html>`_ is a Python web framework built
+with a small core and easy-to-extend philosophy. :ref:`networking_builtin_server`
shows how to use nginx, the web server that's already running. This recipe shows how
easy it is to build your own server. This is an adaptation of
-`Python WebServer With Flask and Raspberry Pi <https://towardsdatascience.com/python-webserver-with-flask-and-raspberry-pi-398423cc6f5d>`_.
+`Python WebServer With Flask and Raspberry Pi <https://towardsdatascience.com/python-webserver-with-flask-and-raspberry-pi-398423cc6f5>`_.
First, install flask:
@@ -151,41 +148,39 @@ All the code in is the Cookbook repo:
bone$ git clone https://github.com/MarkAYoder/BoneCookbook
bone$ cd BoneCookbook/doc/06iod/code/flash
-
First Flask - hello, world
-****************************
+============================
Our first example is *helloWorld.py*
.. _flask_hello_world:
-Python code for flask hello world (helloWorld.py)
-
-.. code-block:: python
+.. literalinclude:: code/flask/helloWorld.py
+ :caption: Python code for flask hello world (helloWorld.py)
+ :linenos:
- include::code/flask/helloWorld.py[simple flask-based web server]
+:download:`helloWorld.py <code/flask/helloWorld.py>`
+1. The first line loads the Flask module into your Python script.
-<1> The first line loads the Flask module into your Python script.
+2. The second line creates a Flask object called ``app``.
-<2> The second line creates a Flask object called _app_.
+3. The third line is where the action is, it says to run the index() function when someone accesses the root URL (‘/’) of the server. In this case, send the text “hello, world†to the client’s web browser via return.
-<3> The third line is where the action is, it says to run the index() function when someone accesses the root URL (‘/’) of the server. In this case, send the text “hello, world†to the client’s web browser via return.
+4. The last line says to “listen†on port 8080, reporting any errors.
-<4> The last line says to “listen†on port 8080, reporting any errors.
-
-Now on your host computer, browse to 192.168.7.2:8080flask an you should see.
+Now on your host computer, browse to 192.168.7.2:8080 flask an you should see.
.. _flask_flaskServer:
-Test page served by our custom flask server
-
.. figure:: figures/flaskServer.png
:align: center
:alt: Test page
+ Test page served by our custom flask server
+
Adding a template
-*******************
+==================
Let’s improve our “hello, world†application, by using an HTML template and a
CSS file for styling our page. Note: these have been created for you in the
@@ -196,11 +191,11 @@ Here's what's in *templates/index1.html*:
.. _flask_index1:
-Python code for flask hello world (helloWorld.py)
+.. literalinclude:: code/flask/templates/index1.html
+ :caption: index1.html
+ :linenos:
-.. code-block:: html
-
- include::code/flask/templates/index1.html
+:download:`index1.html <code/flask/templates/index1.html>`
Note: a style sheet (style.css) is also included. This will be populated later.
@@ -211,13 +206,11 @@ function. Now, let’s create a new Python script. We will name it app1.py:
.. _flask_app1:
-Python code for flask index1.html (app1.py)
-
-.. code-block:: html
-
- include::code/flask/app1.py[app1]
-
+.. literalinclude:: code/flask/app1.py
+ :caption: app1.py
+ :linenos:
+:download:`app1.py <code/flask/app1.py>`
Note that we create a formatted string("timeString") using the date and time from the "now" object, that has the current time stored on it.
@@ -234,35 +227,35 @@ Open any web browser and browse to 192.168.7.2:8080. You should see:
.. _flask_app1_fig:
-Test page served by app1.py
-
.. figure:: figures/flaskapp1.png
:align: center
:alt: app1.py
+ Test page served by app1.py
+
Note that the page’s content changes dynamically any time that you refresh
it with the actual variable data passed by Python script. In our case,
“title†is a fixed value, but “time†change it every second.
Displaying GPIO Status in a Web Browser - reading a button
------------------------------------------------------------
+===========================================================
Problem
-*********
+--------
You want a web page to display the status of a GPIO pin.
Solution
-*********
+---------
-This solution builds on the Flask-based web server solution in :ref:`<networking_nodejs>`.
+This solution builds on the Flask-based web server solution in :ref:`networking_nodejs`.
To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`<app_proto>`)
-* Pushbutton switch (see :ref:`<app_misc>`)
+* Breadboard and jumper wires.
+* Pushbutton switch.
-Wire your pushbutton as shown in :ref:`<js_pushbutton_fig>`.
+Wire your pushbutton as shown in :ref:`js_pushbutton_fig`.
Wire a button to *P9_11* and have the web page display the value of the button.
@@ -270,12 +263,11 @@ Let’s use a new Python script named *app2.py*.
.. _flask_app2:
-A simple Flask-based web server to read a GPIO (app2.py)
-
-.. code-block:: python
-
- include::code/flask/app2.py
+.. literalinclude:: code/flask/app2.py
+ :caption: A simple Flask-based web server to read a GPIO (app2.py)
+ :linenos:
+:download:`app2.py <code/flask/app2.py>`
Look that what we are doing is defining the button on *P9_11* as input, reading its value and
storing it in *buttonSts*. Inside the function *index()*, we will pass that value to our web
@@ -285,11 +277,11 @@ Let’s also see the new *index2.html* to show the GPIO status:
.. _flask_index2:
-A simple Flask-based web server to read a GPIO (index2.html)
-
-.. code-block:: html
+.. literalinclude:: code/flask/templates/index2.html
+ :caption: A simple Flask-based web server to read a GPIO (index2.html)
+ :linenos:
- include::code/flask/templates/index2.html[]
+:download:`index2.html <code/flask/templates/index2.html>`
Now, run the following command:
@@ -298,35 +290,32 @@ Now, run the following command:
bone$ ./app2.py
-Point your browser to _http://192.168.7.2:8080_, and the
-page will look like :ref:`<networking_GPIOserver_fig>`.
+Point your browser to `http://192.168.7.2:8080`, and the
+page will look like :ref:`flask_app2_fig`.
.. _flask_app2_fig:
-Status of a GPIO pin on a web page
-
.. figure:: figures/flaskapp2.png
:align: center
:alt: GPIO status
-Currently, the +0+ shows that the button isn't pressed.
-Try refreshing the page while pushing the button, and you will see +1+ displayed.
+ Status of a GPIO pin on a web page
-Discussion
-***********
+Currently, the *0* shows that the button isn't pressed.
+Try refreshing the page while pushing the button, and you will see *1* displayed.
It's not hard to assemble your own HTML with the GPIO data. It's an easy extension to write a program to display the status of all the GPIO pins.
Controlling GPIOs
-------------------
+===================
Problem
-*********
+--------
You want to control an LED attached to a GPIO pin.
Solution
-*********
+---------
Now that we know how to “read†GPIO Status, let’s change them. What we will do will control the LED via
the web page. We have an LED connected to *P9_14*. Controlling remotely we will change
@@ -361,26 +350,23 @@ http://192.168.7.2:8081/ledRed/off
For the above example, *ledRed* is the “deviceName†and *on* or *off* are examples of
possible “actionâ€. Those routes will be identified and properly “workedâ€. The main steps are:
-* Convert the string “ledREDâ€, for example, on its equivalent GPIO pin.
-
-The integer variable ledRed is equivalent to P9_14. We store this value on variable “actuatorâ€
-
-* For each actuator, we will analyze the “actionâ€, or “command†and act properly.
-If “action = on†for example, we must use the command: GPIO.output(actuator, GPIO.HIGH)
-
+* Convert the string “ledREDâ€, for example, on its equivalent GPIO pin. The integer variable ledRed is equivalent to P9_14. We store this value on variable “actuatorâ€
+* For each actuator, we will analyze the “actionâ€, or “command†and act properly. If “action = on†for example, we must use the command: GPIO.output(actuator, GPIO.HIGH)
* Update the status of each actuator
* Update the variable library
* Return the data to index.html
-Let’s now create an index.html to show the GPIO status of each actuator and more important, create “buttons†to send the commands:
-.. _flask_index3:
+Let’s now create an index.html to show the GPIO status of each
+actuator and more important, create “buttons†to send the commands:
-A simple Flask-based web server to write a GPIO (index3.html)
+.. _flask_index3:
-.. code-block:: html
+.. literalinclude:: code/flask/templates/index3.html
+ :caption: A simple Flask-based web server to write a GPIO (index3.html)
+ :linenos:
- include::code/flask/templates/index3.html
+:download:`index3.html <code/flask/templates/index3.html>`
.. code-block:: bash
@@ -402,18 +388,17 @@ Try clicking the "TURN ON" and "TURN OFF" buttons and your LED will respond.
*app4.py* and *app5.py* combine the previous apps. Try them out.
Plotting Data
----------------
+==============
Problem
-*********
+--------
You have live, continuous, data coming into your Bone via one of the Analog Ins, and you want to plot it.
Solution
-*********
+---------
-Analog in - Continuous
-(This is based on information at: http://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/Foundational_Components/Kernel/Kernel_Drivers/ADC.html#Continuous%20Mode)
+Analog in - Continuous (This is based on information at: http://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/Foundational_Components/Kernel/Kernel_Drivers/ADC.html#Continuous%20Mode)
Reading a continuous analog signal requires some set up. First go to the iio devices directory.
@@ -425,7 +410,7 @@ Reading a continuous analog signal requires some set up. First go to the iio dev
dev in_voltage1_raw in_voltage3_raw in_voltage5_raw in_voltage7_raw of_node@ scan_elements/ uevent
-Here you see the files used to read the one shot values. Look in +scan_elements+ to see how to enable continuous input.
+Here you see the files used to read the one shot values. Look in *scan_elements* to see how to enable continuous input.
.. code-block:: bash
@@ -460,30 +445,29 @@ Let's use a 512 sample buffer. You might need to experiment with this.
bone$ echo 1 > buffer/enable
- Now, just read from +/dev/iio:device0+.
+ Now, just read from */dev/iio:device0*.
.. _analog_sine_fig:
-1KHz sine wave sampled at 8KHz
-
.. figure:: figures/Sine1k.png
:align: center
:alt: 1KHz sine wave sampled at 8KHz
+ 1KHz sine wave sampled at 8KHz
+
An example Python program that does the above and the reads and
plot the buffer is here: analogInContinuous.py
.. _analog_code:
-Code to read and plot a continuous analog input(analogInContinuous.py)
-
-.. code-block:: python
-
- include::code/analogInContinuous.py[]
+.. literalinclude:: code/analogInContinuous.py
+ :caption: Code to read and plot a continuous analog input(analogInContinuous.py)
+ :linenos:
+:download:`analogInContinuous.py <code/analogInContinuous.py>`
Be sure to read the instillation instructions in the comments. Also note this uses X
-windows and you need to +ssh -X 192.168.7.2+ for X to know where the display is.
+windows and you need to *ssh -X 192.168.7.2* for X to know where the display is.
Run it:
@@ -495,9 +479,10 @@ Run it:
bone$ ./analogInContinuous.py
Hit ^C to stop
-// TODO verify this works. fonts are taking too long to load
+.. TODO
+ verify this works. fonts are taking too long to load
-:ref:`<analog_sine_fig>` is the output of a 1KHz sine wave.
+:ref:`analog_sine_fig` is the output of a 1KHz sine wave.
It's a good idea to disable the buffer when done.
@@ -508,7 +493,7 @@ It's a good idea to disable the buffer when done.
Analog in - Continuous, Change the sample rate
-***********************************************
+===============================================
The built in ADCs sample at 8k samples/second by default.
They can run as fast as 200k samples/second by editing a device tree.
@@ -586,16 +571,17 @@ A number of files get installed, including the ADC file. Now try rerunning.
Here's the output of a 10KHz sine wave.
-// TODO Is this trun: (The plot is wrong, but eLinux won't let me fix it.)
+.. TODO
+ Is this trun: (The plot is wrong, but eLinux won't let me fix it.)
.. _analog_tri_fig:
-10KHz triangle wave sampled at 200KHz
-
.. figure:: figures/Tri10k.png
:align: center
:alt: 10KHz triangle wave sampled at 200KHz
+ 10KHz triangle wave sampled at 200KHz
+
It's still a good idea to disable the buffer when done.
@@ -605,67 +591,71 @@ It's still a good idea to disable the buffer when done.
Sending an Email
----------------------
+=================
Problem
-*********
+---------
You want to send an email via Gmail from the Bone.
Solution
-*********
+---------
This example came from https://realpython.com/python-send-email/.
-First, you need to `set up a Gmail account <https://mail.google.com>`_, if you don't already have one.
-Then add the code in :ref:`<networking_nodemailer_code>` to a file named _emailTest.py_. Substitute your own Gmail username. For the password:
+First, you need to `set up a Gmail account <https://mail.google.co>`_, if you don't already have one.
+Then add the code in :ref:`networking_nodemailer_code` to a file named ``emailTest.py``. Substitute your own Gmail username. For the password:
* Go to: https://myaccount.google.com/security
* Select App password.
-* Generate your own 16 char password and copy it into _emailTest.py_.
+* Generate your own 16 char password and copy it into ``emailTest.py``.
* Be sure to delete password when done https://myaccount.google.com/apppasswords .
.. _networking_nodemailer_code:
-Sending email using nodemailer (emailtTest.py)
-
-.. code-block:: python
-
- include::code/emailTest.py
+.. literalinclude:: code/emailTest.py
+ :caption: Sending email using nodemailer (emailtTest.py)
+ :linenos:
+:download:`emailTest.py <code/emailTest.py>`
Then run the script to send the email:
.. code-block:: bash
- bone$ chmod +x emailTest.py
+ bone$ chmod *x emailTest.py
bone$ .\emailTest.py
-.. warning:: This solution requires your Gmail password to be in plain text in a file, which is a security problem. Make sure you know who has access to your Bone. Also, if you remove the microSD card, make sure you know who has access to it. Anyone with your microSD card can read your Gmail password.
+.. warning::
+ This solution requires your Gmail password to be in plain text in a file, which is a security problem.
+ Make sure you know who has access to your Bone. Also, if you remove the microSD card, make sure you know
+ who has access to it. Anyone with your microSD card can read your Gmail password.
-Discussion
-*********
Be careful about putting this into a loop. Gmail presently limits you to
-`500 emails per day and 10 MB per message <http://group-mail.com/email-marketing/how-to-send-bulk-emails-using-gmail/>`_.
+`500 emails per day and 10 MB per message <http://group-mail.com/email-marketing/how-to-send-bulk-emails-using-gmail>`_.
See https://realpython.com/python-send-email/ for an example that sends an attached file.
Sending an SMS Message
--------------------------
+=======================
-// TODO My twilio account is suspended.
+.. TODO
+ My twilio account is suspended.
Problem
-*********
+--------
You want to send a text message from BeagleBone Black.
Solution
-*********
+---------
-There are a number of SMS services out there. This recipe uses Twilio because you can use it for free, but you will need to http://bit.ly/1MrHBBF[verify the number] to which you are texting. First, go to https://www.twilio.com/[Twilio's home page] and set up an account. Note your account SID and authorization token. If you are using the free version, be sure to http://bit.ly/19c7GZ7[verify your numbers].
+There are a number of SMS services out there. This recipe uses Twilio because you can use it for free,
+but you will need to `verify the number <http://bit.ly/1MrHBBF>`_ to which you are texting. First, go
+to `Twilio's home page <https://www.twilio.com/>`_ and set up an account. Note your account SID and
+authorization token. If you are using the free version, be sure to `verify your numbers <http://bit.ly/19c7GZ7>`_.
Next, install Trilio by using the following command:
@@ -674,65 +664,61 @@ Next, install Trilio by using the following command:
bone$ npm install -g twilio
-Finally, add the code in :ref:`<networking_twilio_code>` to a file named _twilio-test.js_ and run it. Your text will be sent.
+Finally, add the code in :ref:`networking_twilio_code` to a file named ``twilio-test.js`` and run it. Your text will be sent.
.. _networking_twilio_code:
-Sending SMS messages using Twilio (_twilio-test.js_)
+.. literalinclude:: code/twilio-test.js
+ :caption: Sending SMS messages using Twilio (``twilio-test.js``)
+ :linenos:
-.. code-block:: JavaScript
-
- include::code/twilio-test.js[nodemailer-test.js]
-
-
-
-Discussion
-*********
+:download:`twilio-test.js <code/twilio-test.js>`
+:download:`nodemailer-test.js <code/nodemailer-test.js>`
Twilio allows a small number of free text messages, enough to test your code and to play around some.
Displaying the Current Weather Conditions
--------------------------------------------
+==========================================
Problem
-*********
+--------
You want to display the current weather conditions.
Solution
-*********
+---------
Because your Bone is on the network, it's not hard to access the current weather conditions from a weather API.
* Go to https://openweathermap.org/ and create an account.
* Go to https://home.openweathermap.org/api_keys and get your API key.
-* Store your key in the +bash+ variable +APPID+.
+* Store your key in the *bash* variable *APPID*.
.. code-block:: bash
bash$ export APPID="Your key"
-* Then add the code in :ref:`<networking_weather_code>` to a file named _weather.js_.
+* Then add the code in :ref:`networking_weather_code` to a file named ``weather.js``.
* Run the pyhon script.
.. _networking_weather_code:
-Code for getting current weather conditions (_weather.py_)
+.. literalinclude:: code/weather.py
+ :caption: Code for getting current weather conditions (``weather.py``)
+ :linenos:
-.. code-block:: python
+:download:`weather.py <code/weather.py>`
- include::code/weather.py
-
-<1> Prints current conditions.
-<2> Prints the forecast for the next day.
-<3> Prints everything returned by the weather site.
+1. Prints current conditions.
+2. Prints the forecast for the next day.
+3. Prints everything returned by the weather site.
Run this by using the following commands:
.. code-block:: bash
- bone$ chmod +x weather.py
+ bone$ chmod *x weather.py
bone$ ./weather.js
Getting weather
Temp: 85.1
@@ -741,37 +727,33 @@ Run this by using the following commands:
High: 85.1
sunrise: 2022-07-14 14:32:46
-
-Discussion
-*********
-
The weather API returns lots of information. Use Python to extract the information you want.
Sending and Receiving Tweets
--------------------------------
+=============================
Problem
-*********
+--------
You want to send and receive tweets (Twitter posts) with your Bone.
Solution
-*********
+---------
-`Twitter <https://twitter.com/>`_ has a whole `git repo <https://github.com/twitterdev/Twitter-API-v2-sample-code>`_
+`Twitter <https://twitter.com>`_ has a whole `git repo <https://github.com/twitterdev/Twitter-API-v2-sample-code>`_
of sample code for interacting with Twitter. Here I'll show how to create a tweet and then how to delete it.
Creating a Project and App
-****************************
+===========================
-* Follow the https://developer.twitter.com/en/docs/apps/overview[directions here] to create a project and and app.
+* Follow the `directions here <https://developer.twitter.com/en/docs/apps/overview>`_ to create a project and and app.
* Be sure to giv eyour app Read and Write permission.
-* Then go to the https://developer.twitter.com/en/portal/projects-and-apps[developer portal] and select you app by clicking on the gear icon to the right of the app name.
+* Then go to the `developer portal <https://developer.twitter.com/en/portal/projects-and-apps>`_ and select you app by clicking on the gear icon to the right of the app name.
* Click on the *Keys and tokens* tab. Here you can get to all your keys and tokens.
.. tip:: Be sure to record them, you can't get them later.
-* Open the file +twitterKeys.sh+ and record your keys in it.
+* Open the file *twitterKeys.sh* and record your keys in it.
.. code-block:: bash
@@ -787,19 +769,21 @@ Creating a Project and App
bash$ source twitterKeys.sh
-You'll need to do this every time you open a new +bash+ window.
+You'll need to do this every time you open a new *bash* window.
Creating a tweet
-****************************
-Add the code in :ref:`<twitter_create_code>` to a file called _twitter_create_tweet_.py_ and run it to see your timeline.
+=================
-.. _twitter_create_code:
+Add the code in :ref:`twitter_create_code` to a file called
+``twitter_create_tweet_.py`` and run it to see your timeline.
-Create a Tweet (_twitter_create_tweet.py_)
+.. _twitter_create_code:
-.. code-block:: python
+.. literalinclude:: code/twitter_create_tweet.py
+ :caption: Create a Tweet (``twitter_create_tweet.py``)
+ :linenos:
- include::code/twitter_create_tweet.py[]
+:download:`twitter_create_tweet.py <code/twitter_create_tweet.py>`
Run the code and you'll have to authorize.
@@ -821,35 +805,33 @@ Check your twitter account and you'll see the new tweet.
Record the *id* number and we'll use it next to delete the tweet.
Deleting a tweet
-****************************
+=================
-Use the code in :ref:`<twitter_delete_code>` to delete a tweet. Around line 15 is the *id* number. Paste in the value returned above.
+Use the code in :ref:`twitter_delete_code` to delete a tweet.
+Around line 15 is the *id* number. Paste in the value returned above.
.. _twitter_delete_code:
-.Code to delete a tweet (twitter_delete_tweet.py_)
-
-.. code-block:: python
+.. literalinclude:: code/twitter_delete_tweet.py
+ :caption: Code to delete a tweet (``twitter_delete_tweet.py``)
+ :linenos:
- include::code/twitter_delete_tweet.py
+:download:`twitter_delete_tweet.py <code/twitter_delete_tweet.py>`
+.. TODO
+ Start Here
-// TODO Start Here
-The code in :ref:`<networking_pushbutton_code>` sends a tweet whenever a button is pushed.
+The code in :ref:`networking_pushbutton_code` snds a tweet whenever a button is pushed.
.. _networking_pushbutton_code:
-.Tweet when a button is pushed (twitterPushbutton.js)
-
-.. code-block:: JavaScript
-
- include::code/twitterPushbutton.js
+.. literalinclude:: code/twitterPushbutton.js
+ :caption: Tweet when a button is pushed (twitterPushbutton.js)
+ :linenos:
+:download:`twitterPushbutton.js <code/twitterPushbutton.js>`
-To see many other examples, go to `iStrategyLabs' node-twitter GitHub page <http://bit.ly/18AvSTW>`_.
-
-Discussion
-*********
+To see many other examples, go to `iStrategyLabs node-twitter GitHub page <http://bit.ly/18AvST>`_.
This opens up many new possibilities. You can read a temperature sensor and tweet its
value whenever it changes, or you can turn on an LED whenever a certain hashtag
@@ -858,23 +840,23 @@ is used. What are you going to tweet?
.. _networking_node_red:
Wiring the IoT with Node-RED
------------------------------
+=============================
Problem
-*********
+--------
You want BeagleBone to interact with the Internet,
but you want to program it graphically.
Solution
-*********
+---------
-http://nodered.org/[Node-RED] is a visual tool for wiring the IoT.
+`Node-RED <http://nodered.org/>`_ is a visual tool for wiring the IoT.
It makes it easy to turn on a light when a certain hashtag is tweeted,
or spin a motor if the forecast is for hot weather.
Installing Node-RED
-*********************
+====================
To install Node-RED, run the following commands:
@@ -900,8 +882,7 @@ To run Node-RED, use the following commands:
- 18 Aug 16:31:43 - [red] Version: 0.8.1.git
- 18 Aug 16:31:43 - [red] Loading palette nodes
-- 18 Aug 16:31:49 - [26-rawserial.js] Info : only really needed for
- Windows boxes without serialport npm module installed.
+- 18 Aug 16:31:49 - [26-rawserial.js] Info : only really needed for Windows boxes without serialport npm module installed.
- 18 Aug 16:31:56 - ------------------------------------------
- 18 Aug 16:31:56 - [red] Failed to register 44 node types
- 18 Aug 16:31:56 - [red] Run with -v for details
@@ -910,179 +891,165 @@ To run Node-RED, use the following commands:
- 18 Aug 16:31:56 - [red] Loading flows : flows_yoder-debian-bone.json
-The second-to-last line informs you that Node-RED is listening on part +1880+. Point your browser to http://192.168.7.2:1880, and you will see the screen shown in :ref:`<networking_node_red_fig>`.
+The second-to-last line informs you that Node-RED is listening on part *1880*. Point your browser to
+http://192.168.7.2:1880, and you will see the screen shown in :ref:`networking_node_red_fig`.
.. _networking_node_red_fig:
-The Node-RED web page
-
.. figure:: figures/node-red.png
:align: center
:alt: node-red
+ The Node-RED web page
+
Building a Node-RED Flow
-****************************
-The example in this recipe builds a Node-RED flow that will toggle an LED whenever a certain hashtag is tweeted. But first, you need to set up the Node-RED flow with the +twitter+ node:
+=========================
-- On the Node-RED web page, scroll down until you see the +social+ nodes on the left side of the page.
-- Drag the +twitter+ node to the canvas, as shown in :ref:`<networking_node_twitter_fig>`.
+The example in this recipe builds a Node-RED flow that will toggle an LED whenever a certain hashtag
+is tweeted. But first, you need to set up the Node-RED flow with the *twitter* node:
-.. _networking_node_twitter_fig:
+- On the Node-RED web page, scroll down until you see the *social* nodes on the left side of the page.
+- Drag the *twitter* node to the canvas, as shown in :ref:`networking_node_twitter_fig`.
-Node-RED twitter node
+.. _networking_node_twitter_fig:
.. figure:: figures/node-twitter.png
:align: center
:alt: node-red
-.. [start=3]
-. Authorize Twitter by double-clicking the +twitter+ node. You'll see the screen shown in :ref:`<networking_node_twitter_auth_fig>`.
+ Node-RED twitter node
-.. _networking_node_twitter_auth_fig:
+Authorize Twitter by double-clicking the *twitter* node. You'll see the screen shown in :ref:`networking_node_twitter_auth_fig`.
-Node-RED Twitter authorization, step 1
+.. _networking_node_twitter_auth_fig:
.. figure:: figures/node-twitter-auth.png
:align: center
:alt: node-red authentication
-.. [start=4]
-. Click the pencil button to bring up the dialog box shown in :ref:`<networking_node_twitter_auth2_fig>`.
+ Node-RED Twitter authorization, step 1
-.. _networking_node_twitter_auth2_fig:
+Click the pencil button to bring up the dialog box shown in :ref:`networking_node_twitter_auth2_fig`.
-Node-RED twitter authorization, step 2
+.. _networking_node_twitter_auth2_fig:
.. figure:: figures/node-twitter-auth2.png
:align: center
:alt: node-red authentication2
-.. [start=5]
+ Node-RED twitter authorization, step 2
-- Click the "here" link, as shown in :ref:`<networking_node_twitter_auth2_fig>`, and you'll
-be taken to Twitter to authorize Node-RED.
+- Click the "here" link, as shown in :ref:`networking_node_twitter_auth2_fig`, and you'll be taken to Twitter to authorize Node-RED.
+- Log in to Twitter and click the "Authorize app" button (:ref:`networking_node_twitter_auth3_fig`).
-- Log in to Twitter and click the "Authorize app" button (:ref:`<networking_node_twitter_auth3_fig>`).
.. _networking_node_twitter_auth3_fig:
-Node-RED Twitter site authorization
-
.. figure:: figures/node-twitter-auth3.png
:align: center
:alt: node-red authentication3
-.. [start=7]
+ Node-RED Twitter site authorization
-- When you're back to Node-RED, click the Add button, add your Twitter credentials,
-enter the hashtags to respond to (:ref:`<networking_node_twitter_beagle_fig>`), and then
-click the Ok pass:[<span class="keep-together">button</span>].
+- When you're back to Node-RED, click the Add button, add your Twitter credentials, enter the hashtags to respond to (:ref:`networking_node_twitter_beagle_fig`), and then click the Ok button.
-.. _networking_node_twitter_beagle_fig:
-Node-RED adding the #BeagleBone hashtag
+.. _networking_node_twitter_beagle_fig:
.. figure:: figures/node-twitter-beagle.png
:align: center
:alt: node-red beagle hash
-.. [start=8]
-- Go back to the left panel, scroll up to the top, and then drag the +debug+ node to the canva- (+debug+ is in the +output+ section.)
-- Connect the two nodes by clicking and dragging (:ref:`<networking_node_twitter_debug_fig>`).
+ Node-RED adding the #BeagleBone hashtag
-.. _networking_node_twitter_debug_fig:
+- Go back to the left panel, scroll up to the top, and then drag the *debug* node to the canva- (*debug* is in the *output* section.)
+- Connect the two nodes by clicking and dragging (:ref:`networking_node_twitter_debug_fig`).
-Node-RED Twitter adding +debug+ node and connecting
+.. _networking_node_twitter_debug_fig:
.. figure:: figures/node-twitter-debug.png
:align: center
:alt: node-red debug
-.. [start=10]
+ Node-RED Twitter adding *debug* node and connecting
- In the right panel, in the upper-right corner, click the "debug" tab.
- Finally, click the Deploy button above the "debug" tab.
-Your Node-RED flow is now running on the Bone. Test it by going to Twitter and tweeting something with the hashtag +#BeagleBone+. Your Bone is now responding to events happening out in the world.
+Your Node-RED flow is now running on the Bone. Test it by going to Twitter and tweeting something with
+the hashtag *#BeagleBone*. Your Bone is now responding to events happening out in the world.
Adding an LED Toggle
-***********************
+=====================
Now, we're ready to add the LED toggle:
-- Wire up an LED as shown in :ref:`<displays_externalLED>`. Mine is wired to +P9_14+.
-- Scroll to the bottom of the left panel and drag the +bbb-discrete-out+ node (second from the bottom of the +bbb+ nodes) to the canvas and wire it (:ref:`<networking_node_bbb_out_fig>`).
+- Wire up an LED as shown in :ref:`displays_externalLED`. Mine is wired to *P9_14*.
+- Scroll to the bottom of the left panel and drag the *bbb-discrete-out* node (second from the bottom of the *bbb* nodes) to the canvas and wire it (:ref:`networking_node_bbb_out_fig`).
.. _networking_node_bbb_out_fig:
-Node-RED adding bbb-discrete-out node
-
.. figure:: figures/node-disc-out.png
:align: center
:alt: node-red discrete out node
-.. [start=3]
+ Node-RED adding bbb-discrete-out node
Double-click the node, select your GPIO pin and "Toggle state,"
-and then set "Startup as" to +1+ (:ref:`<networking_node_bbb_out_setup_fig>`).
+and then set "Startup as" to *1* (:ref:`networking_node_bbb_out_setup_fig`).
.. _networking_node_bbb_out_setup_fig:
-Node-RED adding bbb-discrete-out configuration
-
.. figure:: figures/node-disc-out-setup.png
:align: center
:alt: node-red discrete out setup
-.. [start=4]
+ Node-RED adding bbb-discrete-out configuration
Click Ok and then Deploy.
-Test again. The LED will toggle every time the hashtag +#BeagleBone+ is tweeted. With a little more exploring, you should be able to have your Bone ringing a bell or spinning a motor in response to tweets.
-
-Discussion
-***********
+Test again. The LED will toggle every time the hashtag *#BeagleBone* is tweeted. With a little more exploring,
+you should be able to have your Bone ringing a bell or spinning a motor in response to tweets.
Communicating over a Serial Connection to an Arduino or LaunchPad
--------------------------------------------------------------------
+==================================================================
Problem
-*********
+--------
You would like your Bone to talk to an Arduino or LaunchPad.
Solution
-*********
+---------
The common serial port (also know as a UART) is the simplest way to
-talk between the two. Wire it up as shown in :ref:`<networking_launchPad_fig>`.
+talk between the two. Wire it up as shown in :ref:`networking_launchPad_fig`.
-.. warning::
- BeagleBone Black runs at 3.3 V. When wiring other devices to it,
- ensure that they are also 3.3 V. The LaunchPad I'm using is 3.3 V,
- but many Arduinos are 5.0 V and thus won't work. Or worse,
- they might damage your Bone.
+.. warning::
+ BeagleBone Black runs at 3.3 V. When wiring other devices to it, ensure that
+ they are also 3.3 V. The LaunchPad I'm using is 3.3 V, but many Arduinos are
+ 5.0 V and thus won't work. Or worse, they might damage your Bone.
-.. _networking_launchPad_fig:
-Wiring a LaunchPad to a Bone via the common serial port
+.. _networking_launchPad_fig:
.. figure:: figures/launchPad_bb.png
:align: center
:alt: MSP430 LaunchPad
-Add the code (or _sketch_, as it's called in Arduino-speak) in :ref:`<js_launchPad_code>`
-to a file called _launchPad.ino_ and run it on your LaunchPad.
+ Wiring a LaunchPad to a Bone via the common serial port
-.. _js_launchPad_code:
-
-LaunchPad code for communicating via the UART (launchPad.ino)
+Add the code (or ``sketch``, as it's called in Arduino-speak) in :ref:`js_launchPad_code`
+to a file called ``launchPad.ino`` and run it on your LaunchPad.
-.. code-block:: C
+.. _js_launchPad_code:
- include::code/launchPad/launchPad.ino
+.. literalinclude:: code/launchPad/launchPad.ino
+ :caption: LaunchPad code for communicating via the UART (launchPad.ino)
+ :linenos:
+:download:`launchPad.ino <code/launchPad/launchPad.ino>`
1. Set the mode for the built-in red and green LEDs.
@@ -1090,34 +1057,33 @@ LaunchPad code for communicating via the UART (launchPad.ino)
3. Prompt the user, which in this case is the Bone.
-4. Set the LEDs to the current values of the +red+ and +green+ variables.
+4. Set the LEDs to the current values of the *red* and *green* variables.
5. Wait for characters to arrive on the serial port.
6. After the characters are received, read it and respond to it.
-On the Bone, add the script in :ref:`<js_launchPadBeagle_code>` to a file called _launchPad.js_ and run it.
+On the Bone, add the script in :ref:`js_launchPadBeagle_code` to a file called `launchPad.js` and run it.
.. _js_launchPadBeagle_code:
-Code for communicating via the UART (launchPad.js)
-
-.. code-block:: C
-
- include::code/launchPad.js
+.. literalinclude:: code/launchPad.js
+ :caption: Code for communicating via the UART (launchPad.js)
+ :linenos:
+:download:`launchPad.js <code/launchPad.js>`
-1. Select which serial port to use. :ref:`<networking_cape-headers-serial_fig>` shows what's available. We've wired +P9_24+ and +P9_26+, so we are using serial port +/dev/ttyO1+. (Note that's the letter _O_ and not the number _zero_.)
+1. Select which serial port to use. :ref:`networking_cape-headers-serial_fig` sows what's available. We've wired *P9_24* and *P9_26*, so we are using serial port */dev/ttyO1*. (Note that's the letter ``O`` and not the number ``zero``.)
2. Set the baudrate to 9600, which matches the setting on the LaunchPad.
-3. Read one line at a time up to the newline character (+\n+).
+3. Read one line at a time up to the newline character (*\n*).
-4. Open the serial port and call +onSerial()+ whenever there is data available.
+4. Open the serial port and call *onSerial()* whenever there is data available.
5. Determine what event has happened on the serial port and respond to it.
-6. If the serial port has been ++open++ed, start calling +sendCommand()+ every 1000 ms.
+6. If the serial port has been *opened*, start calling *sendCommand()* every 1000 ms.
7. These are the two commands to send.
@@ -1136,6 +1102,6 @@ Code for communicating via the UART (launchPad.js)
Discussion
************
-When you run the script in :ref:`<js_launchPadBeagle_code>`, the Bone opens up the
-serial port and every second sends a new command, either +r+ or +g+.
+When you run the script in :ref:`js_launchPadBeagle_code`, the Bone opens up the
+serial port and every second sends a new command, either *r* or *g*.
The LaunchPad waits for the command and, when it arrives, responds by toggling the corresponding LED.
diff --git a/books/beaglebone-cookbook/07kernel/kernel.rst b/books/beaglebone-cookbook/07kernel/kernel.rst
index 7b0966b7..88cf1e10 100644
--- a/books/beaglebone-cookbook/07kernel/kernel.rst
+++ b/books/beaglebone-cookbook/07kernel/kernel.rst
@@ -4,33 +4,35 @@ The Kernel
###########
Introduction
----------------------------------
+*************
+
The kernel is the heart of the Linux operating system. It's the software that takes the
low-level requests, such as reading or writing files, or reading and writing general-purpose
input/output (GPIO) pins, and maps them to the hardware. When you install a new version of the
-OS (:ref:`<basics_latest_os>`), you get a certain version of the kernel.
+OS (:ref:`basics_latest_os`), you get a certain version of the kernel.
You usually won't need to mess with the kernel, but sometimes you might want to try something new
that requires a different kernel. This chapter shows how to switch kernels. The nice thing is you
can have multiple kernels on your system at the same time and select from among them which to boot up.
-// TODO is this still true?
+.. TODO
+ is this still true?
.. note::
- We assume here that you are logged on to your Bone as +root+ and superuser privileges.
+ We assume here that you are logged on to your Bone as *root* and superuser privileges.
You also need to be logged in to your Linux host computer as a nonsuperuser.
Updating the Kernel
----------------------
+====================
Problem
-***********
+--------
You have an out-of-date kernel and want to want to make it current.
Solution
-***********
+---------
Use the following command to determine which kernel you are running:
@@ -41,10 +43,10 @@ Use the following command to determine which kernel you are running:
GNU/Linux
-The +3.8.13-bone67+ string is the kernel version.
+The *3.8.13-bone67* string is the kernel version.
To update to the current kernel, ensure that your Bone is on the Internet
-(:ref:`<networking_usb>` or :ref:`<networking_wired>`) and then run the following commands:
+(:ref:`networking_usb` or :ref:`networking_wired`) and then run the following commands:
.. code-block:: bash
@@ -72,74 +74,67 @@ After you have rebooted, the new kernel will be running.
If the current kernel is doing its job adequately, you probably don't need to update, but sometimes a new
software package requires a more up-to-date kernel. Fortunately, precompiled kernels are available and ready to download.
-Discussion
-***********
-
-
.. _kernel_building_modules:
Building and Installing Kernel Modules
----------------------------------
+=======================================
Problem
-***********
+--------
You need to use a peripheral for which there currently is no driver, or you need to improve the
performance of an interface previously handled in user space.
Solution
-***********
+---------
The solution is to run in kernel space by building a kernel module. There are entire
`books on writing Linux Device Drivers <http://bit.ly/1Fb0usf>`_. This recipe assumes that
the driver has already been written and shows how to compile and install it. After you've
followed the steps for this simple module, you will be able to apply them to any other module.
-For our example module, add the code in :ref:`<kernel_simple_module>` to a file called _hello.c_.
+For our example module, add the code in :ref:`kernel_simple_module` to a file called ``hello.c``.
.. _kernel_simple_module:
-Simple Kernel Module (hello.c)
-
-.. code-block:: JavaScript
-
- include::code/hello.c
+.. literalinclude:: code/hello.c
+ :caption: Simple Kernel Module (hello.c)
+ :linenos:
+:download:`hello.c <code/hello.c>`
-
-When compiling on the Bone, all you need to do is load the Kernel Headers for the version of the kernel you're running:
+When compiling on the Bone, all you need to do is load the Kernel
+Headers for the version of the kernel you're running:
.. code-block:: bash
- bone$ sudo apt install linux-headers-`uname -r`
-
+ bone$ sudo apt install linux-headers-``uname -r``
.. note::
- The quotes around +`uname -r`+ are backtick characters. On a United States keyboard,
+
+ The quotes around ``uname -r`` are backtick characters. On a United States keyboard,
the backtick key is to the left of the 1 key.
-This took a little more than three minutes on my Bone. The +`uname -r`+ part of the command
+This took a little more than three minutes on my Bone. The ``uname -r`` part of the command
looks up what version of the kernel you are running and loads the headers for it.
-Next, add the code in :ref:`<kernel_Makefle>` to a file called _Makefile_.
+Next, add the code in :ref:`kernel_Makefle` to a file called ``Makefile``.
.. _kernel_Makefle:
-Simple Kernel Module (_Makefile_)
-
-.. code-block:: JavaScript
-
- include::code/Makefile.display
-
+.. literalinclude:: code/Makefile.display
+ :caption: Simple Kernel Module (``Makefile``)
+ :linenos:
+:download:`Makefile.display <code/Makefile.display>`
.. note::
- Replace the two instances of +<TAB>+ with a tab character (the key left of the Q key on a United States keyboard).
+ Replace the two instances of *<TAB>* with a tab character (the key left of the Q key on a United States keyboard).
The tab characters are very important to makefiles and must appear as shown.
-Now, compile the kernel module by using the +make+ command:
+Now, compile the kernel module by using the *make* command:
.. code-block:: bash
@@ -158,7 +153,8 @@ Now, compile the kernel module by using the +make+ command:
Module.symvers hello.ko hello.mod.o modules.order
-Notice that several files have been created. _hello.ko_ is the one you want. Try a couple of commands with it:
+Notice that several files have been created.
+``hello.ko`` is the one you want. Try a couple of commands with it:
.. code-block:: bash
@@ -175,26 +171,25 @@ Notice that several files have been created. _hello.ko_ is the one you want. Try
[491540.999476] Hello world
-The first command displays information about the module. The +insmod+ command inserts the module into the running kernel.
-If all goes well, nothing is displayed, but the module does print something in the kernel log. The +dmesg+ command displays
-the messages in the log, and the +tail -4+ command shows the last four messages. The last two messages are from the module. It worked!
-
-Discussion
-***********
+The first command displays information about the module. The *insmod* command inserts the module into the running kernel.
+If all goes well, nothing is displayed, but the module does print something in the kernel log. The *dmesg* command displays
+the messages in the log, and the *tail -4* command shows the last four messages. The last two messages are from the module. It worked!
.. _kernel_LEDs:
Controlling LEDs by Using SYSFS Entries
----------------------------------
+========================================
Problem
-***********
+---------
+
You want to control the onboard LEDs from the command line.
Solution
-***********
-On Linux, http://bit.ly/1AjhWUW[everything is a file]; that is, you can access all the inputs and outputs, the LEDs,
-and so on by opening the right _file_ and reading or writing to it. For example, try the following:
+---------
+
+On Linux, `everything is a file <http://bit.ly/1AjhWUW>`_ that is, you can access all the inputs and outputs, the LEDs,
+and so on by opening the right ``file`` and reading or writing to it. For example, try the following:
.. code-block:: bash
@@ -216,8 +211,8 @@ What you are seeing are four directories, one for each onboard LED. Now try this
backlight gpio cpu0 default-on transient
-The first command changes into the directory for LED +usr0+, which is the LED closest to the edge of the board.
-The +[heartbeat]+ indicates that the default trigger (behavior) for the LED is to blink in the heartbeat pattern.
+The first command changes into the directory for LED *usr0*, which is the LED closest to the edge of the board.
+The *[heartbeat]* indicates that the default trigger (behavior) for the LED is to blink in the heartbeat pattern.
Look at your LED. Is it blinking in a heartbeat pattern?
Then try the following:
@@ -230,7 +225,7 @@ Then try the following:
backlight gpio cpu0 default-on transient
-This instructs the LED to use +none+ for a trigger. Look again. It should be no longer blinking.
+This instructs the LED to use *none* for a trigger. Look again. It should be no longer blinking.
Now, try turning it on and off:
@@ -242,39 +237,36 @@ Now, try turning it on and off:
The LED should be turning on and off with the commands.
-Discussion
-***********
-
.. _kernel_gpio_sysfs:
Controlling GPIOs by Using SYSFS Entries
------------------------------------------
+=========================================
Problem
-***********
+--------
You want to control a GPIO pin from the command line.
Solution
-***********
+---------
-:ref:`<kernel_LEDs>` introduces the +sysfs+. This recipe shows how to read and write a GPIO pin.
+:ref:`kernel_LEDs` introduces the *sysfs*. This recipe shows how to read and write a GPIO pin.
Reading a GPIO Pin via sysfs
-******************************
+=============================
-Suppose that you want to read the state of the +P9_42+ GPIO pin. (:ref:`<sensors_pushbutton>` shows how to wire a switch to +P9_42+.)
-First, you need to map the +P9+ header location to GPIO number using :ref:`<kernel_gpio_map_fig>`, which shows that +P9_42+ maps to GPIO 7.
+Suppose that you want to read the state of the *P9_42* GPIO pin. (:ref:`sensors_pushbutton` shows how to wire a switch to *P9_42*.)
+First, you need to map the *P9* header location to GPIO number using :ref:`kernel_gpio_map_fig`, which shows that *P9_42* maps to GPIO 7.
.. _kernel_gpio_map_fig:
-.Mapping P9_42 header position to GPIO 7
-
.. figure:: figures/cape-headers-digitalGPIO7.png
:align: center
:alt: Mapping Header Position to GPIO Numbers
-Next, change to the GPIO +sysfs+ directory:
+ Mapping P9_42 header position to GPIO 7
+
+Next, change to the GPIO *sysfs* directory:
.. code-block:: bash
@@ -283,8 +275,8 @@ Next, change to the GPIO +sysfs+ directory:
export gpiochip0 gpiochip32 gpiochip64 gpiochip96 unexport
-The +ls+ command shows all the GPIO pins that have be exported. In this case, none have,
-so you see only the four GPIO controllers. Export using the +export+ command:
+The *ls* command shows all the GPIO pins that have be exported. In this case, none have,
+so you see only the four GPIO controllers. Export using the *export* command:
.. code-block:: bash
@@ -293,7 +285,7 @@ so you see only the four GPIO controllers. Export using the +export+ command:
export gpio7 gpiochip0 gpiochip32 gpiochip64 gpiochip96 unexport
-Now you can see the _gpio7_ directory. Change into the _gpio7_ directory and look around:
+Now you can see the ``gpio7`` directory. Change into the ``gpio7`` directory and look around:
.. code-block:: bash
@@ -307,7 +299,7 @@ Now you can see the _gpio7_ directory. Change into the _gpio7_ directory and loo
Notice that the pin is already configured to be an input pin. (If it wasn't already configured that way,
-use +echo in > direction+ to configure it.) You can also see that its current value is +0+—that is, it
+use *echo in > direction* to configure it.) You can also see that its current value is *0*—that is, it
isn't pressed. Try pressing and holding it and running again:
.. code-block:: bash
@@ -316,7 +308,7 @@ isn't pressed. Try pressing and holding it and running again:
1
-The +1+ informs you that the switch is pressed. When you are done with GPIO 7, you can always +unexport+ it:
+The *1* informs you that the switch is pressed. When you are done with GPIO 7, you can always *unexport* it:
.. code-block:: bash
@@ -327,11 +319,11 @@ The +1+ informs you that the switch is pressed. When you are done with GPIO 7, y
Writing a GPIO Pin via sysfs
-******************************
+=============================
-Now, suppose that you want to control an external LED. :ref:`<displays_externalLED>` shows
-how to wire an LED to +P9_14+. :ref:`<kernel_gpio_map_fig>` shows +P9_14+ is GPIO 50. Following
-the approach in :ref:`<kernel_gpio_sysfs>`, enable GPIO 50 and make it an output:
+Now, suppose that you want to control an external LED. :ref:`displays_externalLED` shows
+how to wire an LED to *P9_14*. :ref:`kernel_gpio_map_fig` shows *P9_14* is GPIO 50. Following
+the approach in :ref:`kernel_gpio_sysfs`, enable GPIO 50 and make it an output:
.. code-block:: bash
@@ -346,7 +338,7 @@ the approach in :ref:`<kernel_gpio_sysfs>`, enable GPIO 50 and make it an output
in
-By default, +P9_14+ is set as an input. Switch it to an output and turn it on:
+By default, *P9_14* is set as an input. Switch it to an output and turn it on:
.. code-block:: bash
@@ -355,23 +347,20 @@ By default, +P9_14+ is set as an input. Switch it to an output and turn it on:
bone$ echo 0 > value
-The LED turns on when a +1+ is written to +value+ and turns off when a +0+ is written.
-
-Discussion
-***********
+The LED turns on when a *1* is written to *value* and turns off when a *0* is written.
.. _kernel_compiling:
Compiling the Kernel
-----------------------
+=====================
Problem
-***********
+--------
You need to download, patch, and compile the kernel from its source code.
Solution
-***********
+---------
This is easier than it sounds, thanks to some very powerful scripts.
@@ -381,7 +370,7 @@ This is easier than it sounds, thanks to some very powerful scripts.
Downloading and Compiling the Kernel
-**************************************
+=====================================
To download and compile the kernel, follow these steps:
@@ -394,52 +383,49 @@ To download and compile the kernel, follow these steps:
host$ ./build_kernel.sh # <4>
1. The first command clones a repository with the tools to build the kernel for the Bone.
+2. This command lists all the different versions of the kernel that you can build. You'll need to pick one of these. How do you know which one to pick? A good first step is to choose the one you are currently running. *uname -a* will reveal which one that is. When you are able to reproduce the current kernel, go to `Linux Kernel Newbies <http://kernelnewbies.org/>`_ to see what features are available in other kernels. `LinuxChanges <http://bit.ly/1AjiL00>`_ shows the features in the newest kernel and `LinuxVersions <http://bit.ly/1MrIHx3>`_ links to features of pervious kernels.
+3. When you know which kernel to try, use *git checkout* to check it out. This command checks out at tag *3.8.13-bone60* and creates a new branch, *v3.8.13-bone60*.
+4. *build_kernel* is the master builder. If needed, it will download the cross compilers needed to compile the kernel (`linaro <http://www.linaro.org/>`_ is the current cross compiler). If there is a kernel at ``~/linux-dev``, it will use it; otherwise, it will download a copy to ``bb-kernel/ignore/linux-src``. It will then patch the kernel so that it will run on the Bone.
-2. This command lists all the different versions of the kernel that you can build. You'll need to pick one of these. How do you know which one to pick? A good first step is to choose the one you are currently running. +uname -a+ will reveal which one that is. When you are able to reproduce the current kernel, go to http://kernelnewbies.org/[Linux Kernel Newbies] to see what features are available in other kernels. http://bit.ly/1AjiL00[LinuxChanges] shows the features in the newest kernel and http://bit.ly/1MrIHx3[LinuxVersions] links to features of pervious kernels.
-
-3. When you know which kernel to try, use +git checkout+ to check it out. This command checks out at tag +3.8.13-bone60+ and creates a new branch, +v3.8.13-bone60+.
-
-4. +build_kernel+ is the master builder. If needed, it will download the cross compilers needed to compile the kernel (linaro [http://www.linaro.org/] is the current cross compiler). If there is a kernel at _~/linux-dev_, it will use it; otherwise, it will download a copy to _bb-kernel/ignore/linux-src_. It will then patch the kernel so that it will run on the Bone.
-
-After the kernel is patched, you'll see a screen similar to :ref:`<kernel_config_fig>`, on which you can configure the kernel.
+After the kernel is patched, you'll see a screen similar to :ref:`kernel_config_fig`, on which you can configure the kernel.
.. _kernel_config_fig:
-Kernel configuration menu
-
.. figure:: figures/KernelConfig3.16.png
:align: center
:alt: Kernel configuration menu
+ Kernel configuration menu
+
You can use the arrow keys to navigate. No changes need to be made, so you can just press the right
arrow and Enter to start the kernel compiling. The entire process took about 25 minutes on my 8-core host.
-The _bb-kernel/KERNEL_ directory contains the source code for the kernel. The _bb-kernel/deploy_
+The ``bb-kernel/KERNEL`` directory contains the source code for the kernel. The ``bb-kernel/deploy``
directory contains the compiled kernel and the files needed to run it.
.. _kernel_install:
Installing the Kernel on the Bone
-***********************************
+===================================
To copy the new kernel and all its files to the microSD card, you need to halt the Bone,
and then pull the microSD card out and put it in an microSD card reader on your host computer.
-Run +Disk+ (see :ref:`<basics_latest_os>`) to learn where the microSD card appears on your host
-(mine appears in _/dev/sdb_). Then open the _bb-kernel/system.sh_ file and find this line near the end:
+Run *Disk* (see :ref:`basics_latest_os`) to learn where the microSD card appears on your host
+(mine appears in ``/dev/sdb``). Then open the ``bb-kernel/system.sh`` file and find this line near the end:
.. code-block:: bash
MMC=/dev/sde
-Change that line to look like this (where +/dev/sdb+ is the path to your device):
+Change that line to look like this (where */dev/sdb* is the path to your device):
.. code-block:: bash
MMC=/dev/sdb
-Now, while in the _bb-kernel_ directory, run the following command:
+Now, while in the ``bb-kernel`` directory, run the following command:
.. code-block:: bash
@@ -469,42 +455,38 @@ Now, while in the _bb-kernel_ directory, run the following command:
The script lists the partitions it sees and asks if you have the correct one.
If you are sure, press Y, and the script will uncompress and copy the files to
the correct locations on your card. When this is finished, eject your card, plug
-it into the Bone, and boot it up. Run +uname -a+, and you
+it into the Bone, and boot it up. Run *uname -a*, and you
will see that you are running your compiled kernel.
-Discussion
-***********
-
.. _kernel_using_cross_compiler:
Using the Installed Cross Compiler
-------------------------------------
+===================================
Problem
-***********
+--------
-You have followed the instructions in :ref:`<kernel_compiling>`
+You have followed the instructions in :ref:`kernel_compiling`
and want to use the cross compiler it has downloaded.
-[TIP]
-
+.. tip::
+ You can cross-compile without installing the
+ entire kernel source by running the following:
-You can cross-compile without installing the entire kernel source by running the following:
+ .. code-block:: bash
-.. code-block:: bash
-
- host$ sudo apt install gcc-arm-linux-gnueabihf
+ host$ sudo apt install gcc-arm-linux-gnueabihf
-Then skip down to :ref:`<kernel_skip_to_here>`.
+Then skip down to :ref:`kernel_skip_to_here`.
Solution
-***********
+---------
-:ref:`<kernel_compiling>` installs a cross compiler, but you need to set up a
-couple of things so that it can be found. :ref:`<kernel_compiling>` installed the
-kernel and other tools in a directory called _bb-kernel_. Run the
+:ref:`kernel_compiling` installs a cross compiler, but you need to set up a
+couple of things so that it can be found. :ref:`kernel_compiling` installed the
+kernel and other tools in a directory called ``bb-kernel``. Run the
following commands to find the path to the cross compiler:
.. code-block:: bash
@@ -516,7 +498,7 @@ following commands to find the path to the cross compiler:
Here, the path to the cross compiler contains the version number
-of the compiler. Yours might be different from mine. +cd+ into it:
+of the compiler. Yours might be different from mine. *cd* into it:
.. code-block:: bash
@@ -526,7 +508,7 @@ of the compiler. Yours might be different from mine. +cd+ into it:
arm-linux-gnueabihf lib share
-At this point, we are interested in what's in _bin_:
+At this point, we are interested in what's in ``bin``:
.. code-block:: bash
@@ -535,12 +517,12 @@ At this point, we are interested in what's in _bin_:
arm-linux-gnueabihf-addr2line arm-linux-gnueabihf-gfortran
arm-linux-gnueabihf-ar arm-linux-gnueabihf-gprof
arm-linux-gnueabihf-as arm-linux-gnueabihf-ld
- arm-linux-gnueabihf-c++ arm-linux-gnueabihf-ld.bfd
+ arm-linux-gnueabihf-c+* arm-linux-gnueabihf-ld.bfd
arm-linux-gnueabihf-c++filt arm-linux-gnueabihf-ldd
arm-linux-gnueabihf-cpp arm-linux-gnueabihf-ld.gold
arm-linux-gnueabihf-ct-ng.config arm-linux-gnueabihf-nm
arm-linux-gnueabihf-elfedit arm-linux-gnueabihf-objcopy
- arm-linux-gnueabihf-g++ arm-linux-gnueabihf-objdump
+ arm-linux-gnueabihf-g+* arm-linux-gnueabihf-objdump
arm-linux-gnueabihf-gcc arm-linux-gnueabihf-pkg-config
arm-linux-gnueabihf-gcc-4.7.3 arm-linux-gnueabihf-pkg-config-real
arm-linux-gnueabihf-gcc-ar arm-linux-gnueabihf-ranlib
@@ -551,7 +533,7 @@ At this point, we are interested in what's in _bin_:
What you see are all the cross-development tools. You need to add this directory
-to the +$PATH+ the shell uses to find the commands it runs:
+to the *$PATH* the shell uses to find the commands it runs:
.. code-block:: bash
@@ -566,7 +548,7 @@ to the +$PATH+ the shell uses to find the commands it runs:
The first command displays the path to the directory where the cross-development
tools are located. The second shows which directories are searched to find commands
-to be run. Currently, the cross-development tools are not in the +$PATH+. Let's add it:
+to be run. Currently, the cross-development tools are not in the *$PATH*. Let's add it:
.. code-block:: bash
@@ -579,15 +561,15 @@ to be run. Currently, the cross-development tools are not in the +$PATH+. Let's
.. note::
- Those are backtick characters (left of the "1" key on your keyboard) around +pwd+.
+ Those are backtick characters (left of the "1" key on your keyboard) around *pwd*.
-The second line shows the +$PATH+ now contains the directory with the cross-development tools.
+The second line shows the *$PATH* now contains the directory with the cross-development tools.
.. _kernel_skip_to_here:
Setting Up Variables
-*********************
+=====================
Now, set up a couple of variables to know which compiler you are using:
@@ -598,17 +580,15 @@ Now, set up a couple of variables to know which compiler you are using:
These lines set up the standard environmental variables so that you can determine which cross-development
-tools to use. Test the cross compiler by adding :ref:`<kernel_helloWorld>` to a file named _helloWorld.c_.
+tools to use. Test the cross compiler by adding :ref:`kernel_helloWorld` to a file named _helloWorld.c_.
.. _kernel_helloWorld:
-Simple helloWorld.c to test cross compiling (helloWorld.c)
-
-.. code-block:: C
-
- include::code/helloWorld.c
-
+.. literalinclude:: code/helloWorld.c
+ :caption: Simple helloWorld.c to test cross compiling (helloWorld.c)
+ :linenos:
+:download:`helloWorld.c <code/helloWorld.c>`
You can then cross-compile by using the following commands:
@@ -621,42 +601,36 @@ You can then cross-compile by using the following commands:
BuildID[sha1]=0x10182364352b9f3cb15d1aa61395aeede11a52ad, not stripped
-The +file+ command shows that +a.out+ was compiled for an ARM processor.
-
-Discussion
-***********
-
+The *file* command shows that *a.out* was compiled for an ARM processor.
.. _kernel_patches:
Applying Patches
---------------------
+=================
Problem
-***********
+--------
You have a patch file that you need to apply to the kernel.
Solution
-***********
+---------
-:ref:`<kernel_hello_patch>` shows a patch file that you can use on the kernel.
+:ref:`kernel_hello_patch` shows a patch file that you can use on the kernel.
.. _kernel_hello_patch:
-Simple kernel patch file (hello.patch)
-
-.. code-block:: C
-
- include::code/hello.patch[]
-
+.. literalinclude:: code/hello.patch
+ :caption: Simple kernel patch file (hello.patch)
+ :linenos:
+:download:`hello.patch <code/hello.patch>`
Here's how to use it:
-- Install the kernel sources (:ref:`<kernel_compiling>`).
+- Install the kernel sources (:ref:`kernel_compiling`).
- Change to the kernel directory (+cd bb-kernel/KERNEL+).
-- Add :ref:`<kernel_hello_patch>` to a file named _hello.patch_ in the _bb-kernel/KERNEL_ directory.
+- Add :ref:`kernel_hello_patch` to a file named ``hello.patch`` in the ``bb-kernel/KERNEL`` directory.
- Run the following commands:
.. code-block:: bash
@@ -667,8 +641,8 @@ Here's how to use it:
patching file hello/hello.c
-The output of the +patch+ command apprises you of what it's doing.
-Look in the _hello_ directory to see what was created:
+The output of the *patch* command apprises you of what it's doing.
+Look in the ``hello`` directory to see what was created:
.. code-block:: bash
@@ -676,26 +650,24 @@ Look in the _hello_ directory to see what was created:
host$ ls
hello.c Makefile
-
-Discussion
-***********
-
-:ref:`<kernel_building_modules>` shows how to build and install a module, and :ref:`<kernel_create_patch>`
+:ref:`kernel_building_modules` shows how to build and install a module, and :ref:`kernel_create_patch`
shows how to create your own patch file.
.. _kernel_create_patch:
Creating Your Own Patch File
----------------------------------
+=============================
Problem
-***********
+--------
+
You made a few changes to the kernel, and you want to share them with your friends.
Solution
-***********
+---------
-Create a patch file that contains just the changes you have made. Before making your changes, check out a new branch:
+Create a patch file that contains just the changes you have made.
+Before making your changes, check out a new branch:
.. code-block:: bash
@@ -715,7 +687,7 @@ Good, so far no changes have been made. Now, create a new branch:
nothing to commit (working directory clean)
-You've created a new branch called _hello1_ and checked it out. Now, make whatever changes
+You've created a new branch called ``hello1`` and checked it out. Now, make whatever changes
to the kernel you want. I did some work with a simple character driver that we can use as an example:
.. code-block:: bash
@@ -764,8 +736,4 @@ Finally, create the patch file:
.. code-block:: bash
host$ git format-patch master --stdout > hello1.patch
-
-
-Discussion
-***********
diff --git a/books/beaglebone-cookbook/08realtime/realtime.rst b/books/beaglebone-cookbook/08realtime/realtime.rst
index a69b133b..4f894ee4 100644
--- a/books/beaglebone-cookbook/08realtime/realtime.rst
+++ b/books/beaglebone-cookbook/08realtime/realtime.rst
@@ -4,91 +4,88 @@ Real-Time I/O
###############
Introduction
-----------------
+*************
Sometimes, when BeagleBone Black interacts with the physical world, it needs to respond in a timely manner.
For example, your robot has just detected that one of the driving motors needs to turn a bit faster.
-Systems that can respond quickly to a real event are known as _real-time_ systems. There are two broad
+Systems that can respond quickly to a real event are known as ``real-time`` systems. There are two broad
categories of real-time systems: soft and hard.
-In a _soft real-time_ system, the real-time requirements should be met _most_ of the time, where _most_
+In a ``soft real-time`` system, the real-time requirements should be met ``most`` of the time, where ``most``
depends on the system. A video playback system is a good example. The goal might be to display 60 frames
-per second, but it doesn't matter much if you miss a frame now and then. In a 100 percent _hard real-time_
-system, you can never fail to respond in time. Think of an airbag deployment system on a car. You can't even
-be pass:[<span class="keep-together">50 ms late</span>].
+per second, but it doesn't matter much if you miss a frame now and then. In a 100 percent ``hard real-time``
+system, you can never fail to respond in time. Think of an airbag deployment system on a car. You can't even be 50 ms late.
Systems running Linux generally can't do 100 percent hard real-time processing, because Linux gets in the way.
However, the Bone has an ARM processor running Linux and two additional 32-bit programmable real-time units
-(PRUs http://bit.ly/1EzTPZv[Ti AM33XX PRUSSv2]) available to do real-time processing. Although the PRUs can
+(PRUs `Ti AM33XX PRUSSv2 <http://bit.ly/1EzTPZv>`_) available to do real-time processing. Although the PRUs can
achieve 100 percent hard real-time, they take some effort to use.
This chapter shows several ways to do real-time input/output (I/O), starting with the effortless, yet slower
JavaScript and moving up with increasing speed (and effort) to using the PRUs.
.. note::
- In this chapter, as in the others, we assume that you are logged in as +debian+ (as indicated by the +bone$+ prompt).
- This gives you quick access to the general-purpose input/output (GPIO) ports but you may have to use +sudo+ some times.
+ In this chapter, as in the others, we assume that you are logged in as *debian* (as indicated by the *bone$* prompt).
+ This gives you quick access to the general-purpose input/output (GPIO) ports but you may have to use *sudo* some times.
.. _realtime_JavaScript:
I/O with JavaScript
----------------------
+====================
Problem
-**********
+--------
You want to read an input pin and write it to the output as quickly as possible with JavaScript.
Solution
-**********
+---------
-:ref:`<sensors_pushbutton>` shows how to read a pushbutton switch and :ref:`<displays_externalLED>` controls an external LED.
+:ref:`sensors_pushbutton` shows how to read a pushbutton switch and :ref:`displays_externalLED` controls an external LED.
This recipe combines the two to read the switch and turn on the LED in response to it. To make this recipe, you will need:
-* Breadboard and jumper wires (see :ref:`app proto <app_proto>`)
-* Pushbutton switch (see :ref:`app misc <app_misc>`)
-* 220 Ω resistor (see :ref:`app resistor <app_resistor>`)
-* LED (see :ref:`app opto <app_opto>`)
+* Breadboard and jumper wires
+* Pushbutton switch
+* 220R resistor
+* LED
-Wire up the pushbutton and LED as shown in :ref:`<realtime_pushLED_fig>`.
+Wire up the pushbutton and LED as shown in :ref:`realtime_pushLED_fig`.
.. _realtime_pushLED_fig:
-Diagram for wiring a pushbutton and LED with the LED attached to P9_14
-
.. figure:: figures/pushLED_bb.png
:align: center
:alt: Bone with pushbutton and LED
-The code in :ref:`<realtime_pushLED_code>` reads GPIO port +P9_42+, which is attached to the
-pass:[<span class="keep-together">pushbutton</span>], and turns on the LED attached to
-+P9_12+ when the button is pushed.
-
-.. _py_pushLED_code:
+ Diagram for wiring a pushbutton and LED with the LED attached to P9_14
-Monitoring a pushbutton (pushLED.py)
+The code in :ref:`realtime_pushLED_code` reads GPIO port *P9_42*, which is attached to the
+pushbutton, and turns on the LED attached to *P9_12* when the button is pushed.
-.. code-block:: python
+.. _py_pushLED_code:
- include::code/pushLED.py
+.. literalinclude:: code/pushLED.py
+ :caption: Monitoring a pushbutton (pushLED.py)
+ :linenos:
+:download:`pushLED.py <code/pushLED.py>`
.. _realtime_pushLED_code:
-Monitoring a pushbutton (pushLED.js)
-
-.. code-block:: JavaScript
+.. literalinclude:: code/pushLED.js
+ :caption: Monitoring a pushbutton (pushLED.js)
+ :linenos:
- include::code/pushLED.js
+:download:`pushLED.js <code/pushLED.js>`
-Add the code to a file named _pushLED.js_ and run it by using the following commands:
+Add the code to a file named ``pushLED.js`` and run it by using the following commands:
.. code-block:: bash
- bone$ <strong>chmod +x pushLED.js</strong>
- bone$ <strong>./pushLED.js</strong>
+ bone$ chmod *x pushLED.js
+ bone$ ./pushLED.js
data = 0
data = 0
data = 1
@@ -97,44 +94,39 @@ Add the code to a file named _pushLED.js_ and run it by using the following comm
Press ^C (Ctrl-C) to stop the code.
-Discussion
-**********
-
-
.. _realtime_c:
I/O with C
----------------------
+===========
Problem
-**********
+--------
You want to use the C language to process inputs in real time, or Python/JavaScript isn't fast enough.
Solution
-**********
+---------
-:ref:`<realtime_JavaScript>` shows how to control an LED with a pushbutton using JavaScript. This recipe accomplishes
+:ref:`realtime_JavaScript` shows how to control an LED with a pushbutton using JavaScript. This recipe accomplishes
the same thing using C. It does it in the same way, opening the correct /sys/class/gpio files and reading an writing them.
-Wire up the pushbutton and LED as shown in :ref:`<realtime_pushLED_fig>`.
-Then add the code in :ref:`<realtime_pushLED_c_code>` to a file named _pushLED.c_.
+Wire up the pushbutton and LED as shown in :ref:`realtime_pushLED_fig`.
+Then add the code in :ref:`realtime_pushLED_c_code` to a file named ``pushLED.c``.
.. _realtime_pushLED_c_code:
-Code for reading a switch and blinking an LED (pushLED.c)
-
-.. code-block:: bash
-
- include::code/pushLED.c[]
+.. literalinclude:: code/pushLED.c
+ :caption: Code for reading a switch and blinking an LED (pushLED.c)
+ :linenos:
+:download:`pushLED.c <code/pushLED.c>`
Compile and run the code:
.. code-block:: bash
- bone$ <strong>gcc -o pushLED pushLED.c</strong>
- bone$ <strong>./pushLED</strong>
+ bone$ gcc -o pushLED pushLED.c
+ bone$ ./pushLED
state: 1
state: 1
state: 0
@@ -144,91 +136,89 @@ Compile and run the code:
^C
The code responds quickly to the pushbutton. If you need more speed,
-comment-out the +printf()+ and the +sleep()+.
+comment-out the *printf()* and the *sleep()*.
-Discussion
-**********
.. _realtime_devmem2:
I/O with devmem2
----------------------
+=================
Problem
-**********
+--------
Your C code isn't responding fast enough to the input signal. You want to read the GPIO registers directly.
Solution
-**********
+---------
-The solution is to use a simple utility called +devmem2+, with which
+The solution is to use a simple utility called *devmem2*, with which
you can read and write registers from the command line.
.. warning::
This solution is much more involved than the previous ones. You need to understand binary and
- hex numbers and be able to read the http://bit.ly/1B4Cm45[AM335x Technical Reference Manual].
+ hex numbers and be able to read the `AM335x Technical Reference Manual <http://bit.ly/1B4Cm45>`_.
-First, download and install +devmem2+:
+First, download and install *devmem2*:
.. code-block:: bash
- bone$ <strong>wget http://free-electrons.com/pub/mirror/devmem2.c</strong>
- bone$ <strong>gcc -o devmem2 devmem2.c</strong>
- bone$ <strong>sudo mv devmem2 /usr/bin</strong>
+ bone$ wget http://free-electrons.com/pub/mirror/devmem2.c
+ bone$ gcc -o devmem2 devmem2.c
+ bone$ sudo mv devmem2 /usr/bin
-This solution will read a pushbutton attached to +P9_42+ and flash an LED attached to +P9_13+. Note that this is a
+This solution will read a pushbutton attached to *P9_42* and flash an LED attached to *P9_13*. Note that this is a
change from the previous solutions that makes the code used here much simpler. Wire up your Bone as
-shown in :ref:`<realtime_pushLEDmmap_fig>`.
+shown in :ref:`realtime_pushLEDmmap_fig`.
.. _realtime_pushLEDmmap_fig:
-Diagram for wiring a pushbutton and LED with the LED attached to P9_13
-
.. figure:: figures/pushLEDmmap_bb.png
:align: center
:alt: Bone with pushbutton and LED wired to P9_13
-Now, flash the LED attached to +P9_13+ using the Linux +sysfs+ interface (:ref:`<kernel_gpio_sysfs>`). To do this,
-first look up which GPIO number +P9_13+ is attached to by referring to :ref:`<tips_cape_headers_digital>`.
-Finding +P9_13+ at GPIO 31, export GPIO 31 and make it an output:
+ Diagram for wiring a pushbutton and LED with the LED attached to P9_13
+
+Now, flash the LED attached to *P9_13* using the Linux *sysfs* interface (:ref:`kernel_gpio_sysfs`). To do this,
+first look up which GPIO number *P9_13* is attached to by referring to :ref:`tips_cape_headers_digital`.
+Finding *P9_13* at GPIO 31, export GPIO 31 and make it an output:
.. code-block:: bash
- bone$ <strong>cd cd /sys/class/gpio/</strong>
- bone$ <strong>echo 31 > export</strong>
- bone$ <strong>cd gpio31</strong>
- bone$ <strong>echo out > direction</strong>
- bone$ <strong>echo 1 > value</strong>
- bone$ <strong>echo 0 > value</strong>
+ bone$ cd cd /sys/class/gpio/
+ bone$ echo 31 > export
+ bone$ cd gpio31
+ bone$ echo out > direction
+ bone$ echo 1 > value
+ bone$ echo 0 > value
-The LED will turn on when +1+ is echoed into +value+ and off when +0+ is echoed.
+The LED will turn on when *1* is echoed into *value* and off when *0* is echoed.
Now that you know the LED is working, look up its memory address. This is where things get very detailed.
-First, download the http://bit.ly/1B4Cm45[AM335x Technical Reference Manual]. Look up +GPIO0+ in the
-Memory Map chapter (sensors). Table 2-2 indicates that +GPIO0+ starts at address +0x44E0_7000+. Then
-go to Section 25.4.1, "GPIO Registers." This shows that +GPIO_DATAIN+ has an offset of +0x138+, +GPIO_CLEARDATAOUT+
-has an offset of +0x190+, and +GPIO_SETDATAOUT+ has an offset of +0x194+.
+First, download the `AM335x Technical Reference Manual <http://bit.ly/1B4Cm45>`_. Look up *GPIO0* in the
+Memory Map chapter (sensors). Table 2-2 indicates that *GPIO0* starts at address *0x44E0_7000*. Then
+go to Section 25.4.1, "GPIO Registers." This shows that *GPIO_DATAIN* has an offset of *0x138*, *GPIO_CLEARDATAOUT*
+has an offset of *0x190*, and *GPIO_SETDATAOUT* has an offset of *0x194*.
-This means you read from address +0x44E0_7000+ + +0x138+ = +0x44E0_7138+ to see the status of the LED:
+This means you read from address *0x44E0_7000* * *0x138* = *0x44E0_7138* to see the status of the LED:
.. code-block:: bash
- bone$ <strong>sudo devmem2 0x44E07138</strong>
+ bone$ sudo devmem2 0x44E07138
/dev/mem opened.
Memory mapped at address 0xb6f8e000.
Value at address 0x44E07138 (0xb6f8e138): 0xC000C404
-The returned value +0xC000C404+ (+1100 0000 0000 0000 1100 0100 0000 0100+ in binary) has bit 31 set to +1+,
-which means the LED is on. Turn the LED off by writing +0x80000000+ (+1000 0000 0000 0000 0000 0000 0000 0000+ binary)
-to the +GPIO_CLEARDATA+ register at +0x44E0_7000+ + +0x190+ = +0x44E0_7190+:
+The returned value *0xC000C404* (*1100 0000 0000 0000 1100 0100 0000 0100* in binary) has bit 31 set to *1*,
+which means the LED is on. Turn the LED off by writing *0x80000000* (*1000 0000 0000 0000 0000 0000 0000 0000* binary)
+to the *GPIO_CLEARDATA* register at *0x44E0_7000* * *0x190* = *0x44E0_7190*:
.. code-block:: bash
- bone$ <strong>sudo devmem2 0x44E07190 w 0x80000000</strong>
+ bone$ sudo devmem2 0x44E07190 w 0x80000000
/dev/mem opened.
Memory mapped at address 0xb6fd7000.
Value at address 0x44E07190 (0xb6fd7190): 0x80000000
@@ -236,41 +226,43 @@ to the +GPIO_CLEARDATA+ register at +0x44E0_7000+ + +0x190+ = +0x44E0_7190+:
The LED is now off.
-You read the pushbutton switch in a similar way. :ref:`<tips_cape_headers_digital>` says +P9_42+ is GPIO 7, which means bit 7 is the state of +P9_42+. The +devmem2+ in this example reads +0x0+, which means all bits are +0+, including GPIO 7. Section 25.4.1 of the Technical Reference Manual instructs you to use offset +0x13C+ to read +GPIO_DATAOUT+. Push the pushbutton and run +devmem2+:
+You read the pushbutton switch in a similar way. :ref:`tips_cape_headers_digital` says
+*P9_42* is GPIO 7, which means bit 7 is the state of *P9_42*. The *devmem2* in this
+example reads *0x0*, which means all bits are *0*, including GPIO 7. Section 25.4.1
+of the Technical Reference Manual instructs you to use offset *0x13C* to read
+*GPIO_DATAOUT*. Push the pushbutton and run *devmem2*:
.. code-block:: bash
- bone$ <strong>sudo devmem2 0x44e07138</strong>
+ bone$ sudo devmem2 0x44e07138
/dev/mem opened.
Memory mapped at address 0xb6fe2000.
Value at address 0x44E07138 (0xb6fe2138): 0x4000C484
-Here, bit 7 is set in +0x4000C484+, showing the button is pushed.
+Here, bit 7 is set in *0x4000C484*, showing the button is pushed.
-Discussion
-**********
This is much more tedious than the previous methods, but it's what's necessary if you need to
-minimize the time to read an input. :ref:`<realtime_mmap>` shows how to read and write these addresses from C.
+minimize the time to read an input. :ref:`realtime_mmap` shows how to read and write these addresses from C.
.. _realtime_mmap:
I/O with C and mmap()
----------------------
+======================
Problem
-**********
+--------
Your C code isn't responding fast enough to the input signal.
Solution
-**********
+---------
In smaller processors that aren't running an operating system, you can read and write a given memory address directly
from C. With Linux running on Bone, many of the memory locations are hardware protected, so you can't accidentally access them directly.
-This recipe shows how to use +mmap()+ (memory map) to map the GPIO registers to an array in C. Then all you need t
+This recipe shows how to use *mmap()* (memory map) to map the GPIO registers to an array in C. Then all you need t
o do is access the array to read and write the registers.
.. warning::
@@ -279,41 +271,41 @@ o do is access the array to read and write the registers.
and be able to read the AM335x Technical Reference Manual.
-This solution will read a pushbutton attached to +P9_42+ and flash an LED attached to +P9_13+. Note that this is a
+This solution will read a pushbutton attached to *P9_42* and flash an LED attached to *P9_13*. Note that this is a
change from the previous solutions that makes the code used here much simpler.
-.. tip:: See :ref:`<realtime_devmem2>` for details on mapping the GPIO numbers to memory addresses.
+.. tip::
+ See :ref:`realtime_devmem2` for details on mapping
+ the GPIO numbers to memory addresses.
-Add the code in :ref:`<realtime_pushLEDmmap_h>` to a file named _pushLEDmmap.h_.
+Add the code in :ref:`realtime_pushLEDmmap_h` to a file named ``pushLEDmmap.h``.
.. _realtime_pushLEDmmap_h:
-Memory address definitions (pushLEDmmap.h)
-
+.. literalinclude:: code/pushLEDmmap.h
+ :caption: Memory address definitions (pushLEDmmap.h)
+ :linenos:
-.. code-block:: bash
-
- include::code/pushLEDmmap.h[pushLEDmmap.h]
+:download:`pushLEDmmap.h <code/pushLEDmmap.h>`
+Add the code in :ref:`realtime_pushLEDmmap_c` to a file named ``pushLEDmmap.c``.
-Add the code in :ref:`<realtime_pushLEDmmap_c>` to a file named _pushLEDmmap.c_.
.. _realtime_pushLEDmmap_c:
-Code for directly reading memory addresses (pushLEDmmap.c)
+.. literalinclude:: code/pushLEDmmap.c
+ :caption: Code for directly reading memory addresses (pushLEDmmap.c)
+ :linenos:
-
-.. code-block:: bash
-
- include::code/pushLEDmmap.c[pushLEDmmap.c]
+:download:`pushLEDmmap.c <code/pushLEDmmap.c>`
Now, compile and run the code:
.. code-block:: bash
- bone$ <strong>gcc -O3 pushLEDmmap.c -o pushLEDmmap</strong>
- bone$ <strong>sudo ./pushLEDmmap</strong>
+ bone$ gcc -O3 pushLEDmmap.c -o pushLEDmmap
+ bone$ sudo ./pushLEDmmap
Mapping 44E07000 - 44E08000 (size: 1000)
GPIO mapped to 0xb6fac000
GPIO SETDATAOUTADDR mapped to 0xb6fac194
@@ -322,23 +314,21 @@ Now, compile and run the code:
^C
Ctrl-C pressed, cleaning up and exiting...
-The code is in a tight +while+ loop that checks the status of GPIO 7 and copies it to GPIO 31.
+The code is in a tight *while* loop that checks the status of GPIO 7 and copies it to GPIO 31.
-Discussion
-**********
Tighter Delay Bounds with the PREEMPT_RT Kernel
-----------------
+================================================
Problem
-**********
+--------
You want to run real-time processes on the Beagle, but the OS is slowing things down.
Solution
-**********
+---------
The Kernel can be compiled with PREEMPT_RT enabled which reduces the delay from when a thread is scheduled to when it runs.
@@ -349,33 +339,35 @@ Discussion to see how much the latencies are reduced.
.. code-block:: bash
- bone$ <strong>uname -a</strong>
+ bone$ uname -a
Linux breadboard-home 5.10.120-ti-r47 #1bullseye SMP PREEMPT Tue Jul 12 18:59:38 UTC 2022 armv7l GNU/Linux
- I'm running a 5.10 kernel. Remember the whole string, +5.10.120-ti-r47+, for later.
+
+I'm running a 5.10 kernel. Remember the whole string, *5.10.120-ti-r47*, for later.
-* Go to https://forum.beagleboard.org/t/debian-10-x-11-x-kernel-updates/30928[kernel update] and look for +5.10+.
+* Go to `kernel update <https://forum.beagleboard.org/t/debian-10-x-11-x-kernel-updates/30928>`_ and look for *5.10*.
.. _realtime_kernel_update_fig:
-The regular and RT kernels
-
-.. figure:: figures/kernel_update.pn
- :align: centerg
+.. figure:: figures/kernel_update.png
+ :align: center
:alt: The regular and RT kernels
-In :ref:`<realtime_kernel_update_fig>` you see the reular kernel on top and the RT below.
+ The regular and RT kernels
+
+In :ref:`realtime_kernel_update_fig` you see the reular kernel on top and the RT below.
* We want the RT one.
.. code-block:: bash
- bone$ <strong>sudo apt update</strong>
- bone$ <strong>sudo apt install bbb.io-kernel-5.10-ti-rt-am335x</strong>
+ bone$ sudo apt update
+ bone$ sudo apt install bbb.io-kernel-5.10-ti-rt-am335x
-.. note:: Use the *am57xx* if you are using the BeagleBoard AI or AI64.
+.. note::
+ Use the *am57xx* if you are using the BeagleBoard AI or AI64.
-* Before rebooting, edit +/boot/uEnv.txt+ to start with:
+* Before rebooting, edit */boot/uEnv.txt* to start with:
.. code-block:: bash
@@ -386,12 +378,10 @@ In :ref:`<realtime_kernel_update_fig>` you see the reular kernel on top and the
#uuid=
#dtb=
-+uname_r+ tells the boot loader which kernel to boot. Here we've commented out the
+*uname_r* tells the boot loader which kernel to boot. Here we've commented out the
regular kernel and left in the RT kernel. Next time you boot you'll be running the RT kernel.
Don't reboot just yet. Let's gather some latency data first.
-Discussion
-**********
`Bootlin's preempt_rt workshop <https://bootlin.com/doc/training/preempt-rt/>`_ looks
like a good workshop on PREEMPT RT. Their slides say:
@@ -410,40 +400,42 @@ the first lab since we present a simpler way to get the RT kernel running.
Cyclictest
-**********
+===========
-+cyclictest+ is one tool for measuring the latency from when a thread is schduled and when it runs.
-The +code/rt+ directory in the git repo has some scripts for gathering latency data and plotting it.
+*cyclictest* is one tool for measuring the latency from when a thread is schduled and when it runs.
+The *code/rt* directory in the git repo has some scripts for gathering latency data and plotting it.
Here's how to run the scripts.
-* First look in :ref:`<realtime_install_fig>` to see what to install.
+* First look in :ref:`realtime_install_fig` to see what to install.
.. _realtime_install_fig:
-.. code-block:: bash
-
- include::code/rt/install.sh
+.. literalinclude:: code/rt/install.sh
+ :caption: rt/install.sh
+ :linenos:
+
+:download:`rt/install.sh <code/rt/install.sh>`
* Open up another window and start something that will create a load on the Bone, then run the following:
.. code-block:: bash
- bone$ <strong>time sudo ./hist.gen > nort.hist</strong>
+ bone$ time sudo ./hist.gen > nort.hist
-:ref:`<realtime_hist_gen_fig>` shows what's being run. It defaults to 100,000 loops, so it takes a while.
-The data is saved in +nort.hist+, which stands for no RT histogram.
+:ref:`realtime_hist_gen_fig` shows what's being run. It defaults to 100,000 loops, so it takes a while.
+The data is saved in *nort.hist*, which stands for no RT histogram.
.. _realtime_hist_gen_fig:
-hist.gen
-
-.. code-block:: bash
-
- include::code/rt/hist.gen
+.. literalinclude:: code/rt/hist.gen
+ :caption: hist.gen
+ :linenos:
+:download:`rt/hist.gen <code/rt/hist.gen>`
-.. note:: If you get an error:
+.. note::
+ If you get an error:
Unable to change scheduling policy!
Probably missing capabilities, either run as root or increase RLIMIT_RTPRIO limits
@@ -462,63 +454,64 @@ try running ./setup.sh. If that doesn't work try:
.. code-block:: bash
- bone$ <strong>reboot</strong>
+ bone$ reboot
* After rebooting:
.. code-block:: bash
- bone$ <strong>uname -a</strong>
+ bone$ uname -a
Linux breadboard-home 5.10.120-ti-rt-r47 #1bullseye SMP PREEMPT RT Tue Jul 12 18:59:38 UTC 2022 armv7l GNU/Linux
Congratulations you are running the RT kernel.
.. note::
If the Beagle appears to be running (the LEDs are flashing) but you are having trouble connecting
- via +ssh 192.168.7.2+, you can try connecting using the approach shown in :ref:`<tips_FTDI>`.
+ via *ssh 192.168.7.2*, you can try connecting using the approach shown in :ref:`tips_FTDI`.
-Now run the scipt again (note it's being saved in +rt.hist+ this time.)
+Now run the scipt again (note it's being saved in *rt.hist* this time.)
.. code-block:: bash
- bone$ <strong>time sudo ./hist.gen > rt.hist</strong>
+ bone$ time sudo ./hist.gen > rt.hist
-.. note:: At this point yoou can edit +/boot/uEnt.txt+ to boot the non RT kernel and reboot.
+.. note::
+ At this point yoou can edit */boot/uEnt.txt* to boot the non RT kernel and reboot.
Now it's time to plot the results.
.. code-block:: bash
- bone$ <strong>gnuplot hist.plt</strong>
+ bone$ gnuplot hist.plt
This will generate the file *cyclictest.png* which contains your plot. It should look like:
.. _realtime_cyclictest_fig:
-Histogram of Non-RT and RT kernels running cyclictest
-
.. figure:: code/rt/cyclictest.png
:align: center
:alt: Histogram of Non-RT and RT kernels running cyclictest
+ Histogram of Non-RT and RT kernels running cyclictest
+
Notice the NON-RT data have much longer latenices. They may not happen often (fewer than 10 times in each bin),
but they are occuring and may be enough to miss a real-time deadline.
-The PREEMPT-RT times are all under a 150 pass:[μ]s.
+The PREEMPT-RT times are all under a 150s.
.. _realtime_simpPRU:
I/O with simpPRU
----------------------
+=================
Problem
-**********
+--------
You require better timing than running C on the ARM can give you.
Solution
-**********
+---------
The AM335x processor on the Bone has an ARM processor that is running Linux, but it also has
two 32-bit PRUs that are available for processing I/O. It takes a fair amount of understanding
@@ -526,6 +519,6 @@ to program the PRU. Fortunately, `simpPRU <https://simppru.readthedocs.io/en/lat
language for PRU which compiles down to PRU C. This solution shows how to use it.
Background
------------
+===========
simpPRU
diff --git a/books/beaglebone-cookbook/09capes/capes.rst b/books/beaglebone-cookbook/09capes/capes.rst
index 796d056e..0285e96f 100644
--- a/books/beaglebone-cookbook/09capes/capes.rst
+++ b/books/beaglebone-cookbook/09capes/capes.rst
@@ -4,7 +4,7 @@ Capes
#####
Introduction
------------------------------
+**************
Previous chapters of this book show a variety of ways to interface BeagleBone Black
to the physical world by using a breadboard and wiring to the +P8+ and +P9+ headers.
@@ -16,7 +16,7 @@ you want to share your hardware with the masses.
You can easily expand the functionality of the Bone by adding a `cape <http://bit.ly/1wucweC>`_.
A cape is simply a board--often a printed circuit board (PCB) that connects to the +P8+
and +P9+ headers and follows a few standard pin usages. You can stack up to four capes onto the
-Bone. Capes can range in size from Bone-sized (:ref:`<capes_miniDisplay>`) to much larger than the Bone (:ref:`<capes_7inLCD>`).
+Bone. Capes can range in size from Bone-sized (:ref:`capes_miniDisplay`) to much larger than the Bone (:ref:`capes_7inLCD`).
This chapter shows how to attach a couple of capes, move your design to a protoboard, then to a PCB,
and finally on to mass production.
@@ -24,24 +24,27 @@ and finally on to mass production.
.. _capes_7inLCD:
Using a Seven-Inch LCD Cape
------------------------------
+============================
Problem
-***********
+--------
You want to display the Bone's desktop on a portable LCD.
Solution
-***********
+--------
A number of `LCD capes <http://bit.ly/1AjlXJ9>`_ are built for the Bone, ranging in size from three
to seven inches. This recipe attaches a seven-inch `BeagleBone LCD7 <http://bit.ly/1NK8Hra>`_
-from `CircuitCo http://circuitco.com/`_ (shown in :ref:`<capes_7inLCD_fig>`) to the Bone.
+from `CircuitCo <http://circuitco.com/>`_ (shown in :ref:`capes_7inLCD_fig`) to the Bone.
.. _capes_7inLCD_fig:
+7" LCD
+========
+
.. note::
- Seven-inch LCD from CircuitCo, :ref:`<capes_7inLCD_fig>` was originally posted by CircuitCo
+ Seven-inch LCD from CircuitCo, :ref:`capes_7inLCD_fig` was originally posted by CircuitCo
at http://elinux.org/File:BeagleBone-LCD7-Front.jpg under a
`Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
@@ -51,55 +54,52 @@ from `CircuitCo http://circuitco.com/`_ (shown in :ref:`<capes_7inLCD_fig>`) to
To make this recipe, you will need:
-* Seven-inch LCD cape (see :ref:`app misc<app_misc>`)
-* A 5 V power supply (see :ref:`app misc<app_misc>`)
+* Seven-inch LCD cape
+* A 5 V power supply
Just attach the Bone to the back of the LCD, making sure pin 1 of *P9* lines up with
pin 1 of +P9+ on the LCD. Apply a 5 V power supply, and the desktop will appear on
-your LCD, as shown in :ref:`<capes_LCD7Desktop>`.
+your LCD, as shown in :ref:`capes_LCD7Desktop`.
.. _capes_LCD7Desktop:
-Seven-inch LCD desktop
-
.. figure:: figures/LCD7Desktop.png
:align: center
:alt: 7 inch LCD desktop
+ Seven-inch LCD desktop
+
Attach a USB keyboard and mouse, and you have a portable Bone.
`Wireless keyboard and mouse combinations <https://www.adafruit.com/products/922>`_
make a nice solution to avoid the need to add a USB hub.
-Discussion
-***********
-
.. _capes_miniDisplay:
Using a 128 x 128-Pixel LCD Cape
----------------------------------
+=================================
Problem
-***********
+--------
You want to use a small LCD to display things other than the desktop.
Solution
-***********
+---------
-The http://bit.ly/1xd0r8p[MiniDisplay] is a 128 x 128 full-color LCD cape that just fits on the
-Bone, as shown in :ref:`<capes_miniDisplay_fig>`.
+The `MiniDisplay <http://bit.ly/1xd0r8>`p_ is a 128 x 128 full-color LCD cape that just fits on the
+Bone, as shown in :ref:`capes_miniDisplay_fig`.
.. _capes_miniDisplay_fig:
-MiniDisplay 128 x 128-pixel LCD from CircuitCo
-
.. figure:: figures/MiniDisplay-A1.jpg
:align: center
:alt: miniDisplay LCD
+ MiniDisplay 128 x 128-pixel LCD from CircuitCo
+
To make this recipe, you will need:
-* MiniDisplay LCD cape (see :ref:`app misc<app_misc>`)
+* MiniDisplay LCD cape
Attach to the Bone and apply power. Then run the following commands:
@@ -108,31 +108,32 @@ Attach to the Bone and apply power. Then run the following commands:
# From http://elinux.org/CircuitCo:MiniDisplay_Cape
# Datasheet:
# https://www.crystalfontz.com/products/document/3277/ST7735_V2.1_20100505.pdf
- bone$ <strong>wget http://elinux.org/images/e/e4/Minidisplay-example.tar.gz</strong>
- bone$ <strong>tar zmxvf Minidisplay-example.tar.gz</strong>
- bone$ <strong>cd minidisplay-example</strong>
- bone$ <strong>make</strong>
- bone$ <strong>./minidisplay-test</strong>
+ bone$ wget http://elinux.org/images/e/e4/Minidisplay-example.tar.gz
+ bone$ tar zmxvf Minidisplay-example.tar.gz
+ bone$ cd minidisplay-example
+ bone$ make
+ bone$ ./minidisplay-test
Unable to initialize SPI: No such file or directory
Aborted
-.. warning:: You might get a compiler warning, but the code should run fine.
+.. warning::
+ You might get a compiler warning, but the code should run fine.
The MiniDisplay uses the Serial Peripheral Interface (SPI) interface, and it's not initialized.
The `manufacturer's website <http://bit.ly/1xd0r8p>`_ suggests enabling SPI0 by using the following commands:
.. code-block:: bash
- bone$ <strong>export SLOTS=/sys/devices/bone_capemgr.*/slots</strong>
- bone$ <strong>echo BB-SPIDEV0 > $SLOTS</strong>
+ bone$ export SLOTS=/sys/devices/bone_capemgr.*/slots
+ bone$ echo BB-SPIDEV0 > $SLOTS
Hmmm, something isn't working here. Here's how to see what happened:
.. code-block:: bash
- bone$ <strong>dmesg | tail</strong>
+ bone$ dmesg | tail
[ 625.334497] bone_capemgr.9: part_number 'BB-SPIDEV0', version 'N/A'
[ 625.334673] bone_capemgr.9: slot #11: generic override
[ 625.334720] bone_capemgr.9: bone: Using override eeprom data at slot 11
@@ -160,7 +161,7 @@ Here's how to see what's already configured:
.. code-block:: bash
- bone$ <strong>cat $SLOTS</strong>
+ bone$ cat $SLOTS
0: 54:PF---
1: 55:PF---
2: 56:PF---
@@ -182,8 +183,8 @@ You can unconfigure it by using the following commands:
.. code-block:: bash
- bone$ <strong>echo -10 > $SLOTS</strong>
- bone$ <strong>cat $SLOTS</strong>
+ bone$ echo -10 > $SLOTS
+ bone$ cat $SLOTS
0: 54:PF---
1: 55:PF---
2: 56:PF---
@@ -194,71 +195,86 @@ You can unconfigure it by using the following commands:
8: ff:P-O-L Override Board Name,00A0,Override Manuf,bspm_P9_41_27
9: ff:P-O-L Override Board Name,00A0,Override Manuf,am33xx_pwm
-Now +P9_21+ is free for the MiniDisplay to use.
+Now *P9_21* is free for the MiniDisplay to use.
-.. note:: In future Bone images, all of the pins will already be allocated as part of the main device tree using runtime pinmux helpers and configured at runtime using the http://bit.ly/1EXLeP2[+config-pin+ utility]. This would eliminate the need for device tree overlays in most cases.
-====
+.. note::
+ In future Bone images, all of the pins will already be allocated as part of the main device
+ tree using runtime pinmux helpers and configured at runtime using the `config-pin utility <http://bit.ly/1EXLeP2>`_.
+ This would eliminate the need for device tree overlays in most cases.
Now, configure it for the MiniDisplay and run a test:
.. code-block:: bash
- bone$ <strong>echo BB-SPIDEV0 > $SLOTS</strong>
- bone$ <strong>./minidisplay-test</strong>
+ bone$ echo BB-SPIDEV0 > $SLOTS
+ bone$ ./minidisplay-test
-You then see Boris, as shown in :ref:`<capes_miniDisplayBoris>`.
+You then see Boris, as shown in :ref:`capes_miniDisplayBoris`.
.. _capes_miniDisplayBoris:
-.. note:: MiniDisplay showing Boris, :ref:`<capes_miniDisplayBoris>` was originally posted by David Anders at http://elinux.org/File:Minidisplay-boris.jpg under a `Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
+Mini display Boris
+==================
+
+.. note::
+ MiniDisplay showing Boris, :ref:`capes_miniDisplayBoris` was originally posted by David Anders at http://elinux.org/File:Minidisplay-boris.jpg
+ under a `Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
.. figure:: figures/miniDisplay_Boris.png
:align: center
:alt: miniDisplay LCD showing Boris
-Discussion
-***********
-
Connecting Multiple Capes
------------------------------
+==========================
Problem
-***********
+--------
You want to use more than one cape at a time.
Solution
-***********
+---------
First, look at each cape that you want to stack mechanically. Are they all using stacking
-headers like the ones shown in :ref:`<capes_stacking_headers>`? No more than one should be using non-stacking headers.
+headers like the ones shown in :ref:`capes_stacking_headers`? No more than one should be using non-stacking headers.
.. _capes_stacking_headers:
-Stacking headers
-
.. figure:: figures/stacking_headers.JPG
:align: center
:alt:
+ Stacking headers
+
Note that larger LCD panels might provide expansion headers, such as the ones
-shown in :ref:`<capes_lcd_backside>`, rather than the stacking headers, and that those can also be used for adding
+shown in :ref:`capes_lcd_backside`, rather than the stacking headers, and that those can also be used for adding
additional capes.
.. _capes_lcd_backside:
-.. note:: Back side of LCD7 cape, :ref:`<capes_lcd_backside>` was originally posted by CircuitCo at http://elinux.org/File:BeagleBone-LCD-Backside.jpg under a `Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
+LCD Backside
+=============
+
+.. note::
+ Back side of LCD7 cape, :ref:`capes_lcd_backside` was originally posted by CircuitCo at http://elinux.org/File:BeagleBone-LCD-Backside.jpg under
+ a `Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
.. figure:: figures/LCD7back.png
:align: center
:alt:
-Next, take a note of each pin utilized by each cape. The http://beaglebonecapes.com[BeagleBone Capes catalog] provides a graphical representation for the pin usage of most capes, as shown in :ref:`<Audio_cape_pins_fig>` for the Circuitco Audio Cape.
+Next, take a note of each pin utilized by each cape. The `BeagleBone Capes catalog <http://beaglebonecapes.com>`_
+provides a graphical representation for the pin usage of most capes, as shown in :ref:`Audio_cape_pins_fig` for the Circuitco Audio Cape.
.. _Audio_cape_pins_fig:
-.. note:: Pins utilized by CircuitCo Audio Cape, :ref:`<Audio_cape_pins_fig>` was originally posted by Djackson at http://elinux.org/File:Audio_pins_revb.png under a `Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
+Audio cape pins
+===============
+
+.. note::
+ Pins utilized by CircuitCo Audio Cape, :ref:`Audio_cape_pins_fig` was originally posted by Djackson at http://elinux.org/File:Audio_pins_revb.png
+ under a `Creative Commons Attribution-ShareAlike 3.0 Unported License <http://creativecommons.org/licenses/by-sa/3.0/>`_.
.. figure:: figures/audioCape.png
:align: center
@@ -267,48 +283,50 @@ Next, take a note of each pin utilized by each cape. The http://beaglebonecapes.
In most cases, the same pin should never be used on two different capes, though in some cases, pins can be shared. Here are some exceptions:
- GND
- - The ground (+GND+) pins should be shared between the capes, and there's no need to worry about consumed resources on those pins.
+ - The ground (*GND*) pins should be shared between the capes, and there's no need to worry about consumed resources on those pins.
- VDD_3V3
- - The 3.3 V power supply (+VDD_3V3+) pins can be shared by all capes to supply power, but the total combined consumption of all the capes should be less than 500 mA (250 mA per +VDD_3V3+ pin).
+ - The 3.3 V power supply (*VDD_3V3*) pins can be shared by all capes to supply power, but the total combined consumption of all the capes should be less than 500 mA (250 mA per *VDD_3V3* pin).
- VDD_5V
- - The 5.0 V power supply (+VDD_5V+) pins can be shared by all capes to supply power, but the total combined consumption of all the capes should be less than 2 A (1 A per +VDD_5V+ pin). It is possible for one, and only one, of the capes to _provide_ power to this pin rather than consume it, and it should provide at least 3 A to ensure proper system function. Note that when no voltage is applied to the DC connector, nor from a cape, these pins will not be powered, even if power is provided via USB.
+ - The 5.0 V power supply (*VDD_5V*) pins can be shared by all capes to supply power, but the total combined consumption of all the capes should be less than 2 A (1 A per +VD*_5V+ p*n). It is possible for one, and only one, of the capes to _provide_ power to this pin rather than consume it, and it should provide at least 3 A to ensure proper system function. Note that when no voltage is applied to the DC connector, nor from a cape, these pins will not be powered, even if power is provided via USB.
- SYS_5V
- - The regulated 5.0 V power supply (+SYS_5V+) pins can be shared by all capes to supply power, but the total combined consumption of all the capes should be less than 500 mA (250 mA per +SYS_5V+ pin).
+ - The regulated 5.0 V power supply (*SYS_5V*) pins can be shared by all capes to supply power, but the total combined consumption of all the capes should be less than 500 mA (250 mA per *SYS_5V* pin).
- VADC and AGND
- The ADC reference voltage pins can be shared by all capes.
- I2C2_SCL and I2C2_SDA
- - I^2^C is a shared bus, and the +I2C2_SCL+ and +I2C2_SDA+ pins default to having this bus enabled for use by cape expansion ID EEPROMs.
+ - |I2C| is a shared bus, and the *I2C2_SCL* and *I2C2_SDA* pins default to having this bus enabled for use by cape expansion ID EEPROMs.
-Discussion
-***********
+.. |I2C| replace:: I\ :sub:`2`\ C
.. _capes_soldering:
Moving from a Breadboard to a Protoboard
------------------------------------------
+=========================================
Problem
-***********
+--------
You have your circuit working fine on the breadboard, but you want a more reliable solution.
Solution
-***********
+---------
Solder your components to a protoboard.
To make this recipe, you will need:
-* Protoboard (see :ref:`<app_proto>`)
-* Soldering iron (see :ref:`app misc<app_misc>`)
+* Protoboard
+* Soldering iron
* Your other components
Many places make premade circuit boards that are laid out like the breadboard we have been using.
-:ref:`<capes_beaglebread_fig>` shows the http://bit.ly/1HCwtB4[BeagleBone Breadboard],
+:ref:`capes_beaglebread_fig` shows the `BeagleBone Breadboard <http://bit.ly/1HCwtB4>`_,
which is just one protoboard option.
.. _capes_beaglebread_fig:
+Beaglebread
+============
+
.. note::
This was originally posted by William
Traynor at http://elinux.org/File:BeagleBone-Breadboard.jpg under a
@@ -320,72 +338,66 @@ which is just one protoboard option.
You just solder your parts on the protoboard as you had them on the breadboard.
-Discussion
-***********
-
.. _capes_creating_prototype_schematic:
Creating a Prototype Schematic
------------------------------
+==============================
Problem
-***********
+--------
You've wired up a circuit on a breadboard. How do you turn that prototype into a schematic others can read and
that you can import into other design tools?
Solution
-***********
+---------
-In :ref:`<tips_fritzing>`, we introduced Fritzing as a useful tool for drawing block diagrams. Fritzing can also
-do circuit schematics and printed-circuit layout. For example, :ref:`<capes_quickRobo_fig>` shows a block diagram
+In :ref:`tips_fritzing`, we introduced Fritzing as a useful tool for drawing block diagrams. Fritzing can also
+do circuit schematics and printed-circuit layout. For example, :ref:`capes_quickRobo_fig` shows a block diagram
for a simple robot controller (quickBot.fzz is the name of the Fritzing file used to create the diagram).
.. _capes_quickRobo_fig:
-A simple robot controller diagram (quickBot.fzz)
-
.. figure:: figures/quickBot_bb.png
:align: center
:alt: Simple robot diagram
-The controller has an H-bridge to drive two DC motors (:ref:`<motors_dcDirection>`), an IR range sensor,
+ A simple robot controller diagram (quickBot.fzz)
+
+The controller has an H-bridge to drive two DC motors (:ref:`motors_dcDirection`), an IR range sensor,
and two headers for attaching analog encoders for the motors. Both the IR sensor and the encoders
have analog outputs that exceed 1.8 V, so each is run through a voltage divider (two resistors) to
-scale the voltage to the correct range (see :ref:`<sensors_hc-sr04>` for a voltage divider example).
+scale the voltage to the correct range (see :ref:`sensors_hc-sr04` for a voltage divider example).
-:ref:`<capes_quickRobo_schemRaw>` shows the schematic automatically generated by Fritzing.
+:ref:`capes_quickRobo_schemRaw` shows the schematic automatically generated by Fritzing.
It's a mess. It's up to you to fix it.
.. _capes_quickRobo_schemRaw:
-Automatically generated schematic
-
.. figure:: figures/quickBot_schemRaw.png
:align: center
:alt: Autogenerated schematic
-:ref:`<capes_quickRobo_schem>` shows my cleaned-up schematic. I did it by moving the parts around until it looked better.
+ Automatically generated schematic
-.. _capes_quickRobo_schem:
+:ref:`capes_quickRobo_schem` shows my cleaned-up schematic. I did it by moving the parts around until it looked better.
-Cleaned-up schematic
+.. _capes_quickRobo_schem:
.. figure:: figures/quickBot_schem.png
:align: center
:alt: Cleaned up schematic
-Discussion
-***********
+ Cleaned-up schematic
.. _capes_quickRobo_schemZoom:
-Zoomed-in schematic
-
.. figure:: figures/quickBot_schemZoom.png
:align: center
:alt: Zoomed in schematic
+ Zoomed-in schematic
+
You might find that you want to create your design in a more advanced design tool,
perhaps because it has the library components you desire, it integrates better with other tools
you are using, or it has some other feature (such as simulation) of which you'd like to take advantage.
@@ -393,27 +405,28 @@ you are using, or it has some other feature (such as simulation) of which you'd
.. _capes_verify:
Verifying Your Cape Design
------------------------------
+===========================
Problem
-***********
+--------
You've got a design. How do you quickly verify that it works?
Solution
-***********
+---------
To make this recipe, you will need:
-* An oscilloscope (see :ref:`app misc<app_misc>`)
+* An oscilloscope
Break down your design into functional subcomponents and write tests for each.
Use components you already know are working, such as the onboard LEDs, to display
-the test status with the code in :ref:`<capes_quickBot_motor_test_code>`.
+the test status with the code in :ref:`capes_quickBot_motor_test_code`.
.. _capes_quickBot_motor_test_code:
Testing the quickBot motors interface (quickBot_motor_test.js)
+==============================================================
.. code-block:: bash
@@ -557,94 +570,86 @@ Testing the quickBot motors interface (quickBot_motor_test.js)
.. <dd><p>The <code>analogWrite()</code> call uses the absolute value of <code>speed</code>, making any negative numbers a positive magnitude.</p></dd>
.. </dl>
-++++
-====
-
.. _quickBot_motor_kickback:
-quickBot motor test showing kickback
-
.. figure:: figures/quickBot_motor_kickback.JPG
:align: center
:alt: quickBot kicking back
-Using the solution in :ref:`<basics_autorun>`, you can untether from your coding station to test your
-design at your lab workbench, as shown in :ref:`<quickBot_scope_fig>`.
+ quickBot motor test showing kickback
-.. _quickBot_scope_fig:
+Using the solution in :ref:`beaglebone-cookbook-basics`, you can untether from your coding station to test your
+design at your lab workbench, as shown in :ref:`quickBot_scope_fig`.
-quickBot motor test code under scope
+.. _quickBot_scope_fig:
.. figure:: figures/quickBot_motor_test_scope.JPG
:align: center
:alt: quickBot under scope
+ quickBot motor test code under scope
+
SparkFun provides a `useful guide to using an oscilloscope <http://bit.ly/18AzuoR>`_.
You might want to check it out if you've never used an oscilloscope before.
Looking at the stimulus you'll generate *before* you connect up your hardware will help you avoid surprises.
-Discussion
-***********
-
.. _capes_layout:
Laying Out Your Cape PCB
------------------------------
+=========================
Problem
-***********
+--------
You've generated a diagram and schematic for your circuit and verified that they are correct. How do you create a PCB?
Solution
-***********
+---------
If you've been using Fritzing, all you need to do is click the PCB tab, and there's your board. Well, almost.
-Much like the schematic view shown in :ref:`<capes_creating_prototype_schematic>`, you need to do some layout work
+Much like the schematic view shown in :ref:`capes_creating_prototype_schematic`, you need to do some layout work
before it's actually usable. I just moved the components around until they seemed to be grouped logically and
then clicked the Autoroute button. After a minute or two of trying various layouts, Fritzing picked the one it
-determined to be the best. :ref:`<capes_quickRobo_pcb>` shows the results.
+determined to be the best. :ref:`capes_quickRobo_pcb` shows the results.
.. _capes_quickRobo_pcb:
-Simple robot PCB
-
.. figure:: figures/quickBot_pcb.png
:align: center
:alt: Simple robot PCB
+ Simple robot PCB
+
The `Fritzing pre-fab web page <http://bit.ly/1HCxokQ>`_ has a few helpful hints, including checking the widths
of all your traces and cleaning up any questionable routing created by the autorouter.
-Discussion
-***********
-
-The PCB in :ref:`<capes_quickRobo_pcb>` is a two-sided board. One color (or shade of gray in the printed book)
+The PCB in :ref:`capes_quickRobo_pcb` is a two-sided board. One color (or shade of gray in the printed book)
represents traces on one side of the board, and the other color (or shade of gray) is the other side. Sometimes,
you'll see a trace come to a small circle and then change colors. This is where it is switching sides of the board
through what's called a _via_. One of the goals of PCB design is to minimize the number of vias.
-:ref:`<capes_quickRobo_pcb>` wasn't my first try or my last. My approach was to see what was needed to hook where and
+:ref:`capes_quickRobo_pcb` wasn't my first try or my last. My approach was to see what was needed to hook where and
move the components around to make it easier for the autorouter to carry out its job.
.. note::
There are entire books and websites dedicated to creating PCB layouts. Look around and see
- what you can find. http://bit.ly/1wXTLki[SparkFun's guide to making PCBs] is particularly useful.
+ what you can find. `SparkFun's guide to making PCBs <http://bit.ly/1wXTLki>`_ is particularly useful.
Customizing the Board Outline
-*******************************
+=============================
One challenge that slipped my first pass review was the board outline. The part we installed in
-:ref:`<tips_fritzing>` is meant to represent BeagleBone Black, not a cape, so the outline doesn't have
-the notch cut out of it for the Ethernet pass:[<span class="keep-together">connector</span>].
+:ref:`tips_fritzing` is meant to represent BeagleBone Black, not a cape, so the outline doesn't have
+the notch cut out of it for the Ethernet connector.
-The http://bit.ly/1xd1aGV[Fritzing custom PCB outline page] describes how to create and use a custom
-board outline. Although it is possible to use a drawing tool like https://inkscape.org/en/[Inkscape],
-I chose to use http://bit.ly/1b2aZmn[the SVG _path_ command] directly to create :ref:`<capes_boardoutline_code>`.
+The `Fritzing custom PCB outline page <http://bit.ly/1xd1aGV>`_ describes how to create and use a custom
+board outline. Although it is possible to use a drawing tool like `Inkscape <https://inkscape.org/en/>`_,
+I chose to use `the SVG path command <http://bit.ly/1b2aZmn>`_ directly to create :ref:`capes_boardoutline_code`.
.. _capes_boardoutline_code:
Outline SVG for BeagleBone cape (beaglebone_cape_boardoutline.svg)
+===================================================================
.. <?xml version='1.0' encoding='UTF-8' standalone='no'?>
.. <svg xmlns="http://www.w3.org/2000/svg" version="1.1"
@@ -665,112 +670,120 @@ Outline SVG for BeagleBone cape (beaglebone_cape_boardoutline.svg)
.. </dl>
.. ++++
-The measurements are taken from the http://bit.ly/1C5rSa8[BeagleBone Black System Reference Manual],
-as shown in :ref:`<capes_dimensions_fig>`.
+The measurements are taken from the `BeagleBone Black System Reference Manual <http://bit.ly/1C5rSa8>`_, as shown in :ref:`capes_dimensions_fig`.
.. _capes_dimensions_fig:
-Cape dimensions
-
.. figure:: figures/srm_cape_dimensions.png
:align: center
:alt: Cape dimensions in SRM
-You can observe the rendered output of :ref:`<capes_boardoutline_code>` quickly by opening the file in a web browser, as shown in :ref:`<capes_boardoutline_fig>`.
+ Cape dimensions
-.. _capes_boardoutline_fig:
+You can observe the rendered output of :ref:`capes_boardoutline_code` quickly by opening the
+file in a web browser, as shown in :ref:`capes_boardoutline_fig`.
-Rendered cape outline in Chrome
+.. _capes_boardoutline_fig:
.. figure:: figures/beaglebone_cape_boardoutline.png
:align: center
:alt: Board outline in Chrome
-After you have the SVG outline, you'll need to select the PCB in Fritzing and select a custom shape in the Inspector box. Begin with the original background, as shown in :ref:`<capes_fritzing1>`.
+ Rendered cape outline in Chrome
-.. _capes_fritzing1:
+.. _tips_fritzing:
+
+Fritzing tips
+==============
-PCB with original board, without notch for Ethernet connector
+After you have the SVG outline, you'll need to select the PCB in Fritzing and select a custom shape in the
+Inspector box. Begin with the original background, as shown in :ref:`capes_fritzing1`.
+
+.. _capes_fritzing1:
.. figure:: figures/fritzing1.png
:align: center
:alt: PCB orginal baord
-Hide all but the Board Layer (:ref:`<capes_fritzing2>`).
+ PCB with original board, without notch for Ethernet connector
-.. _capes_fritzing2:
+Hide all but the Board Layer (:ref:`capes_fritzing2`).
-PCB with all but the Board Layer hidden
+.. _capes_fritzing2:
.. figure:: figures/fritzing2.png
:align: center
:alt: PCB orginal baord hidden
-Select the PCB1 object and then, in the Inspector pane, scroll down to the "load image file" button (:ref:`<capes_fritzing3>`).
+ PCB with all but the Board Layer hidden
-.. _capes_fritzing3:
+Select the PCB1 object and then, in the Inspector pane,
+scroll down to the "load image file" button (:ref:`capes_fritzing3`).
-Clicking :load image file: with PCB1 selected
+.. _capes_fritzing3:
.. figure:: figures/fritzing3.png
:align: center
:alt: PCB load image file
-Navigate to the _beaglebone_cape_boardoutline.svg_ file created in :ref:`<capes_boardoutline_code>`, as shown in :ref:`<capes_fritzing4>`.
+ Clicking :load image file: with PCB1 selected
-.. _capes_fritzing4:
+Navigate to the *beaglebone_cape_boardoutline.svg* file created in
+:ref:`capes_boardoutline_code`, as shown in :ref:`capes_fritzing4`.
-Selecting the .svg file
+.. _capes_fritzing4:
.. figure:: figures/fritzing4.png
:align: center
:alt: PCB selecting svg file
-Turn on the other layers and line up the Board Layer with the rest of the PCB, as shown in :ref:`<capes_fritzing_inspector_fig>`.
+ Selecting the .svg file
-.. _capes_fritzing_inspector_fig:
+Turn on the other layers and line up the Board Layer with the rest of the
+PCB, as shown in :ref:`capes_fritzing_inspector_fig`.
-PCB Inspector
+.. _capes_fritzing_inspector_fig:
.. figure:: figures/Fritzing_Inspector.png
:align: center
:alt: PCB Inspector
-Now, you can save your file and send it off to be made,
-as described in :ref:`<capes_prototype>`.
+ PCB Inspector
+
+Now, you can save your file and send it off to be made, as described in :ref:`capes_prototype`.
PCB Design Alternatives
-*************************
+=======================
There are other free PCB design programs. Here are a few.
TO PROD: The headings I've marked as bold lines really should be subheadings of "PCB Design Alternatives,"
-but AsciiDoc won't let me go that deep (to the ==level). Is what I've done the best solution,
+but AsciiDoc won't let me go that deep (to the level). Is what I've done the best solution,
or is there a way to create another heading level?
*EAGLE*
-http://www.cadsoftusa.com/[Eagle PCB] and http://bit.ly/19cbwS0[DesignSpark PCB] are two popular
+`Eagle PCB <http://www.cadsoftusa.com/>`_ and `DesignSpark PCB <http://bit.ly/19cbwS0>`_ are two popular
design programs. Many capes (and other PCBs) are designed with Eagle PCB, and the files are available.
-For example, the MiniDisplay cape (:ref:`<capes_miniDisplay>`) has the schematic shown in :ref:`<capes_miniDisplay_schem>`
-and PCB shown in :ref:`<capes_miniDisplay_pcb>`.
+For example, the MiniDisplay cape (:ref:`capes_miniDisplay`) has the schematic shown in :ref:`capes_miniDisplay_schem`
+and PCB shown in :ref:`capes_miniDisplay_pcb`.
.. _capes_miniDisplay_schem:
-Schematic for the MiniDisplay cape
-
.. figure:: figures/miniDisplay_Cape_schem.png
:align: center
:alt: Schematic for miniDisplay
-.. _capes_miniDisplay_pcb:
+ Schematic for the MiniDisplay cape
-PCB for MiniDisplay cape
+.. _capes_miniDisplay_pcb:
.. figure:: figures/miniDisplay_Cape_pcb.png
:align: center
:alt: PCB for miniDisplay
+ PCB for MiniDisplay cape
+
A good starting point is to take the PCB layout for the MiniDisplay and edit it for your project.
The connectors for +P8+ and +P9+ are already in place and ready to go.
@@ -785,37 +798,36 @@ You can install Eagle PCB on your Linux host by using the following command:
.. code-block:: bash
- host$ <strong>sudo apt install eagle</strong>
+ host$ sudo apt install eagle
Reading package lists... Done
Building dependency tree
Reading state information... Done
...
Setting up eagle (6.5.0-1) ...
Processing triggers for libc-bin (2.19-0ubuntu6.4) ...
- host$ <strong>eagle</strong>
+ host$ eagle
-You'll see the startup screen shown in :ref:`<capes_Eagle_License>`.
+You'll see the startup screen shown in :ref:`capes_Eagle_License`.
.. _capes_Eagle_License:
-Eagle PCB startup screen
-
.. figure:: figures/EagleLicense.png
:align: center
:alt: Eagle License
+ Eagle PCB startup screen
+
Click "Run as Freeware." When my Eagle started, it said it needed to be updated. To update on Linux,
-follow the link provided by Eagle and download _eagle-lin-7.2.0.run_ (or whatever version is current.).
+follow the link provided by Eagle and download *eagle-lin-7.2.0.run* (or whatever version is current.).
Then run the following commands:
.. code-block:: bash
- host$ <strong>chmod +x eagle-lin-7.2.0.run</strong>
- host$ <strong>./eagle-lin-7.2.0.run</strong>
+ host$ chmod +x eagle-lin-7.2.0.run
+ host$ ./eagle-lin-7.2.0.run
-
-A series of screens will appear. Click Next. When you see a screen that looks like :ref:`<capes_eagle3>`, note the Destination Directory.
+A series of screens will appear. Click Next. When you see a screen that looks like :ref:`capes_eagle3`, note the Destination Directory.
.. _capes_eagle3:
@@ -826,36 +838,36 @@ A series of screens will appear. Click Next. When you see a screen that looks li
The Eagle installation destination directory
Continue clicking Next until it's installed. Then run the following commands
-(where +~/eagle-7.2.0+ is the path you noted in :ref:`<capes_eagle3>`):
+(where *~/eagle-7.2.0* is the path you noted in :ref:`capes_eagle3`):
.. code-block:: bash
- host$ <strong>cd /usr/bin</strong>
- host$ <strong>sudo rm eagle</strong>
- host$ <strong>sudo ln -s ~/eagle-7.2.0/bin/eagle .</strong>
- host$ <strong>cd</strong>
- host$ <strong>eagle</strong>
+ host$ cd /usr/bin
+ host$ sudo rm eagle
+ host$ sudo ln -s ~/eagle-7.2.0/bin/eagle .
+ host$ cd
+ host$ eagle
-The +ls+ command links +eagle+ in */usr/bin*, so you can run +eagle+ from any directory.
-After +eagle+ starts, you'll see the start screen shown in :ref:`<capes_eagle7>`.
+The *ls* command links *eagle* in */usr/bin*, so you can run +eagle+ from any directory.
+After *eagle* starts, you'll see the start screen shown in :ref:`capes_eagle7`.
.. _capes_eagle7:
-The Eagle start screen
-
.. figure:: figures/eagle7.png
:align: center
:alt: Eagle start screen
+ The Eagle start screen
+
Ensure that the correct version number appears.
-If you are moving a design from Fritzing to Eagle, see :ref:`<capes_schematic_migration>`
+If you are moving a design from Fritzing to Eagle, see :ref:`capes_schematic_migration`
for tips on converting from one to the other.
*DesignSpark PCB*
-The free `DesignSpark PCB <http://bit.ly/19cbwS0>` doesn't have the same limitations as Eagle PCB,
+The free `DesignSpark PCB <http://bit.ly/19cbwS0>`_ doesn't have the same limitations as Eagle PCB,
but it runs only on Windows. Also, it doesn't seem to have the following of Eagle at this time.
.. _capes_upverter:
@@ -863,50 +875,50 @@ but it runs only on Windows. Also, it doesn't seem to have the following of Eagl
*Upverter*
In addition to free solutions you run on your desktop, you can also work with a browser-based
-tool called https://upverter.com/[Upverter]. With Upverter, you can collaborate easily, editing
+tool called `Upverter <https://upverter.com/>`_. With Upverter, you can collaborate easily, editing
your designs from anywhere on the Internet. It also provides many conversion options and a PCB fabrication service.
.. note::
- Don't confuse Upverter with Upconverter (:ref:`<capes_schematic_migration>`).
+ Don't confuse Upverter with Upconverter (:ref:`capes_schematic_migration`).
Though their names differ by only three letters, they differ greatly in what they do.
.. _capes_kicad:
-*Kicad*
+Kicad
+=======
-Unlike the previously mentioned free (no-cost) solutions, `Kicad <http://bit.ly/1b2bnBg >`_
-is open source and provides some features beyond those of Fritzing. Notably, `CircuitHub <http://circuithub.com/>`_
-(discussed in :ref:`<capes_production>`) provides support for uploading Kicad designs.
+Unlike the previously mentioned free (no-cost) solutions, `Kicad <http://bit.ly/1b2bnBg>`_
+is open source and provides some features beyond those of Fritzing. Notably, `CircuitHub site <http://circuithub.com/>`_
+(discussed in :ref:`capes_production`) provides support for uploading Kicad designs.
.. _capes_schematic_migration:
Migrating a Fritzing Schematic to Another Tool
------------------------------------------------
+===============================================
Problem
-***********
+--------
You created your schematic in Fritzing, but it doesn't integrate with everything you need.
How can you move the schematic to another tool?
Solution
-***********
-
+---------
Use the `Upverter schematic-file-converter <http://bit.ly/1wXUkdM>`_ Python script. For example, suppose that you want
-to convert the Fritzing file for the diagram shown in :ref:`<capes_quickRobo_fig>`. First, install Upverter.
+to convert the Fritzing file for the diagram shown in :ref:`capes_quickRobo_fig`. First, install Upverter.
I found it necessary to install +libfreetype6+ and +freetype-py+ onto my system, but you might not need this first step:
.. code-block:: bash
- host$ <strong>sudo apt install libfreetype6</strong>
+ host$ sudo apt install libfreetype6
Reading package lists... Done
Building dependency tree
Reading state information... Done
libfreetype6 is already the newest version.
0 upgraded, 0 newly installed, 0 to remove and 154 not upgraded.
- host$ <strong>sudo pip install freetype-py</strong>
+ host$ sudo pip install freetype-py
Downloading/unpacking freetype-py
Running setup.py egg_info for package freetype-py
@@ -921,11 +933,11 @@ I found it necessary to install +libfreetype6+ and +freetype-py+ onto my system,
All these commands are being run on the Linux-based host computer, as shown by the +host$+ prompt.
Log in as a normal user, not +root+.
-Now, install the +schematic-file-converter+ tool:
+Now, install the ``schematic-file-converter`` tool:
.. code-block:: bash
- host$ <strong>git clone git@github.com:upverter/schematic-file-converter.git</strong>
+ host$ git clone git@github.com:upverter/schematic-file-converter.git
Cloning into 'schematic-file-converter'...
remote: Counting objects: 22251, done.
remote: Total 22251 (delta 0), reused 0 (delta 0)
@@ -933,8 +945,8 @@ Now, install the +schematic-file-converter+ tool:
Resolving deltas: 100% (14761/14761), done.
Checking connectivity... done.
Checking out files: 100% (16880/16880), done.
- host$ <strong>cd schematic-file-converter</strong>
- host$ <strong>sudo python setup.py install</strong>
+ host$ cd schematic-file-converter
+ host$ sudo python setup.py install
.
.
.
@@ -945,8 +957,8 @@ Now, install the +schematic-file-converter+ tool:
Installed /usr/local/lib/python2.7/dist-packages/python_upconvert-0.8.9-py2.7.egg
Processing dependencies for python-upconvert==0.8.9
Finished processing dependencies for python-upconvert==0.8.9
- host$ <strong>cd ..</strong>
- host$ <strong>python -m upconvert.upconverter -h</strong>
+ host$ cd ..
+ host$ python -m upconvert.upconverter -h
usage: upconverter.py [-h] [-i INPUT] [-f TYPE] [-o OUTPUT] [-t TYPE]
[-s SYMDIRS [SYMDIRS ...]] [--unsupported]
[--raise-errors] [--profile] [-v] [--formats]
@@ -1000,35 +1012,32 @@ At the time of this writing, Upverter suppports the following file types:
| netlist (csv) | out only |
+----------------+-------------------------+
-After Upverter is installed, run the file (_quickBot.fzz_) that generated :ref:`<capes_quickRobo_fig>` through Upverter:
+After Upverter is installed, run the file (``quickBot.fzz``) that generated :ref:`capes_quickRobo_fig` through Upverter:
.. code-block:: bash
- host$ <strong>python -m upconvert.upconverter -i quickBot.fzz \
- -f fritzing -o quickBot-eaglexml.sch -t eaglexml --unsupported</strong>
+ host$ python -m upconvert.upconverter -i quickBot.fzz \
+ -f fritzing -o quickBot-eaglexml.sch -t eaglexml --unsupported
WARNING: RUNNING UNSUPPORTED VERSION OF PYTHON (2.7 > 2.6)
DEBUG:main:parsing quickBot.fzz in format fritzing
- host$ <strong>ls -l</strong>
+ host$ ls -l
total 188
-rw-rw-r-- 1 ubuntu ubuntu 63914 Nov 25 19:47 quickBot-eaglexml.sch
-rw-r--r-- 1 ubuntu ubuntu 122193 Nov 25 19:43 quickBot.fzz
drwxrwxr-x 9 ubuntu ubuntu 4096 Nov 25 19:42 schematic-file-converter
-:ref:`<caps_eagle>` shows the output of the conversion.
+:ref:`caps_eagle` shows the output of the conversion.
.. _caps_eagle:
-Output of Upverter conversion
-
.. figure:: figures/quickBot_eaglexml.png
:align: center
:alt: Converter Output
-No one said it would be pretty!
+ Output of Upverter conversion
-Discussion
-***********
+No one said it would be pretty!
I found that Eagle was more generous at reading in the +eaglexml+ format than the +eagle+ format.
This also made it easier to hand-edit any translation issues.
@@ -1036,37 +1045,39 @@ This also made it easier to hand-edit any translation issues.
.. _capes_prototype:
Producing a Prototype
------------------------------
+======================
Problem
-***********
+--------
You have your PCB all designed. How do you get it made?
Solution
-***********
+---------
To make this recipe, you will need:
-* A completed design (see :ref:`<capes_layout>`)
-* Soldering iron (see :ref:`app misc<app_misc>`)
-* Oscilloscope (see :ref:`app misc<app_misc>`)
-* Multimeter (see :ref:`app misc<app_misc>`)
+* A completed design
+* Soldering iron
+* Oscilloscope
+* Multimeter
* Your other components
-Upload your design to http://oshpark.com[OSH Park] and order a few boards. :ref:`<capes_oshpark_share>`
-shows a resulting http://bit.ly/1MtlzAp[shared project page for the quickBot cape] created in
-:ref:`<capes_layout>`. We'll proceed to break down how this design was uploaded and shared to enable ordering fabricated PCBs.
+Upload your design to `OSH Park <http://oshpark.com>` and order a few boards. :ref:`capes_oshpark_share` shows a resulting
+`shared project page for the quickBot cape <http://bit.ly/1MtlzAp>`_ created in :ref:`capes_layout`. We'll proceed to
+break down how this design was uploaded and shared to enable ordering fabricated PCBs.
.. _capes_oshpark_share:
-The OSH Park QuickBot Cape shared project page
-
.. figure:: figures/quickBot_oshpark_share.png
:align: center
:alt:
-Within Fritzing, click the menu next to "Export for PCB" and choose "Extended Gerber," as shown in :ref:`<capes_fritzing_export_fig>`. You'll need to choose a directory in which to save them and then compress them all into a http://bit.ly/1Br5lEh[Zip file]. The http://bit.ly/1B4GqRU[WikiHow article on creating Zip files] might be helpful if you aren't very experienced at making these.
+ The OSH Park QuickBot Cape shared project page
+
+Within Fritzing, click the menu next to "Export for PCB" and choose "Extended Gerber," as shown in :ref:`capes_fritzing_export_fig`.
+You'll need to choose a directory in which to save them and then compress them all into a `Zip file <http://bit.ly/1Br5lEh>`_.
+The `WikiHow article on creating Zip files <http://bit.ly/1B4GqRU>`_ might be helpful if you aren't very experienced at making these.
.. _capes_fritzing_export_fig:
@@ -1076,9 +1087,16 @@ Within Fritzing, click the menu next to "Export for PCB" and choose "Extended Ge
Choosing "Extended Gerber" in Fritzing
-Things on the `OSH Park website <http://oshpark.com>`_ are reasonably self-explanatory. You'll need to create an account and upload the Zip file containing the http://bit.ly/1B4GzEZ[Gerber files] you created. If you are a cautious person, you might choose to examine the Gerber files with a Gerber file viewer first. The http://bit.ly/18bUgeA[Fritzing fabrication FAQ] offers several suggestions, including http://gerbv.sourceforge.net/[gerbv] for Windows and Linux users.
+Things on the `OSH Park website <http://oshpark.com>`_ are reasonably self-explanatory. You'll need to create an account and
+upload the Zip file containing the `Gerber files <http://bit.ly/1B4GzEZ>`_ you created. If you are a cautious person,
+you might choose to examine the Gerber files with a Gerber file viewer first. The `Fritzing fabrication FAQ <http://bit.ly/18bUgeA>`_
+offers several suggestions, including `gerbv <http://gerbv.sourceforge.net/>`_ for Windows and Linux users.
-When your upload is complete, you'll be given a quote, shown images for review, and presented with options for accepting and ordering. After you have accepted the design, your https://oshpark.com/users/current[list of accepted designs] will also include the option of enabling sharing of your designs so that others can order a PCB, as well. If you are looking to make some money on your design, you'll want to go another route, like the one described in :ref:`<capes_production>`. :ref:`<capes_quickbot_pcb>` shows the resulting PCB that arrives in the mail.
+When your upload is complete, you'll be given a quote, shown images for review, and presented with options for accepting
+and ordering. After you have accepted the design, your `list of accepted designs <https://oshpark.com/users/current>`_
+will also include the option of enabling sharing of your designs so that others can order a PCB, as well. If you are
+looking to make some money on your design, you'll want to go another route, like the one described in :ref:`capes_production`.
+:ref:`capes_quickbot_pcb` shows the resulting PCB that arrives in the mail.
.. _capes_quickbot_pcb:
@@ -1088,13 +1106,13 @@ When your upload is complete, you'll be given a quote, shown images for review,
QuickBot PCB
-Now is a good time to ensure that you have all of your components and a soldering station set up as in :ref:`<capes_soldering>`, as well as an oscilloscope, as used in :ref:`<capes_verify>`.
+Now is a good time to ensure that you have all of your components and a soldering station set up as in :ref:`capes_soldering`, as well as an oscilloscope, as used in :ref:`capes_verify`.
-When you get your board, it is often informative to "buzz out" a few connections by using a multimeter. If you've never used a multimeter before, the http://bit.ly/18bUgeA[SparkFun] or http://bit.ly/1Br5Xtv[Adafruit] tutorials might be helpful. Set your meter to continuity testing mode and probe between points where the headers are and where they should be connecting to your components. This would be more difficult and less accurate after you solder down your components, so it is a good idea to keep a bare board around just for this purpose.
+When you get your board, it is often informative to "buzz out" a few connections by using a multimeter. If you've never used a multimeter before, the `SparkFun <http://bit.ly/18bUgeA>`_ or `Adafruit <http://bit.ly/1Br5Xtv>`_ tutorials might be helpful. Set your meter to continuity testing mode and probe between points where the headers are and where they should be connecting to your components. This would be more difficult and less accurate after you solder down your components, so it is a good idea to keep a bare board around just for this purpose.
You'll also want to examine your board mechanically before soldering parts down. You don't want to waste components on a PCB that might need to be altered or replaced.
-When you begin assembling your board, it is advisable to assemble it in functional subsections, if possible, to help narrow down any potential issues. :ref:`<capes_motors_soldered>` shows the motor portion wired up and running the test in :ref:`<capes_quickBot_motor_test_code>`.
+When you begin assembling your board, it is advisable to assemble it in functional subsections, if possible, to help narrow down any potential issues. :ref:`capes_motors_soldered` shows the motor portion wired up and running the test in :ref:`capes_quickBot_motor_test_code`.
.. _capes_motors_soldered:
@@ -1108,42 +1126,36 @@ Continue assembling and testing your board until you are happy. If you find issu
choose to cut traces and use point-to-point wiring to resolve your issues before placing an
order for a new PCB. Better right the second time than the third!
-Discussion
-***********
-
Creating Contents for Your Cape Configuration EEPROM
-------------------------------------------------------
+=====================================================
Problem
-***********
+--------
Your cape is ready to go, and you want it
to automatically initialize when the Bone boots up.
Solution
-***********
+---------
-Complete capes have an I^2^C EEPROM on board that contains configuration information that is read at boot time.
-`Adventures in BeagleBone Cape EEPROMs <http://bit.ly/1Fb64uF>` gives a helpful description of two methods for
+Complete capes have an |I2C| EEPROM on board that contains configuration information that is read at boot time.
+`Adventures in BeagleBone Cape EEPROMs <http://bit.ly/1Fb64uF>`_ gives a helpful description of two methods for
programming the EEPROM. `How to Roll your own BeagleBone Capes <http://bit.ly/1E5M7RJ>`_ is a good four-part
series on creating a cape, including how to wire and program the EEPROM.
-Discussion
-***********
-
.. _capes_production:
Putting Your Cape Design into Production
------------------------------------------
+=========================================
Problem
-***********
+--------
You want to share your cape with others.
How do you scale up?
Solution
-***********
+---------
`CircuitHub <https://circuithub.com/>`_ offers a great tool to get a quick quote on assembled PCBs.
To make things simple, I downloaded the `CircuitCo MiniDisplay Cape Eagle design materials <http://bit.ly/1C5uvJc>`_
@@ -1152,35 +1164,32 @@ and uploaded them to CircuitHub.
After the design is uploaded, you'll need to review the parts to verify that CircuitHub has or
can order the right ones. Find the parts in the catalog by changing the text in the search box
and clicking the magnifying glass. When you've found a suitable match, select it to confirm
-its use in your design, as shown in :ref:`<capes_circuithub_parts>`.
+its use in your design, as shown in :ref:`capes_circuithub_parts`.
.. _capes_circuithub_parts:
-CircuitHub part matching
-
.. figure:: figures/circuithub_part_matching.png
:align: center
:alt:
-When you've selected all of your parts, a quote tool appears at the bottom of the page,
-as shown in :ref:`<capes_circuithub_quote>`.
+ CircuitHub part matching
-.. _capes_circuithub_quote:
+When you've selected all of your parts, a quote tool appears at the bottom of the page, as shown in :ref:`capes_circuithub_quote`.
-CircuitHub quote generation
+.. _capes_circuithub_quote:
.. figure:: figures/circuithub_quote.png
:align: center
:alt:
-Checking out the pricing on the MiniDisplay Cape (without including the LCD itself) in :ref:`<capes_circuithub_pricing_table>`,
+ CircuitHub quote generation
+
+Checking out the pricing on the MiniDisplay Cape (without including the LCD itself) in :ref:`capes_circuithub_pricing_table`,
you can get a quick idea of how increased volume can dramatically impact the per-unit costs.
.. _capes_circuithub_pricing_table:
-CircuitHub price examples (all prices USD)
-
-.. table::
+.. table:: CircuitHub price examples (all prices USD)
+-----------+----------+---------+------------+------------+-------------+
| Quantity | 1 | 10 | 100 | 1000 | 10,000 |
@@ -1197,13 +1206,11 @@ CircuitHub price examples (all prices USD)
+-----------+----------+---------+------------+------------+-------------+
Checking the `Crystalfontz web page for the LCD <http://bit.ly/1GF6xqE>`_,
-you can find the prices for the LCDs as well, as shown in :ref:`<capes_lcd_pricing_table>`.
+you can find the prices for the LCDs as well, as shown in :ref:`capes_lcd_pricing_table`.
.. _capes_lcd_pricing_table:
-LCD pricing (USD)
-
-.. table::
+.. table:: LCD pricing (USD)
+-----------+---------+--------+----------+------------+-------------+
| Quantity | 1 | 10 | 100 | 1000 | 10,000 |
@@ -1219,15 +1226,14 @@ can choose how much markup you need to be paid for your work and launch the camp
Money is only collected if and when the desired target quantity is reached, so there's no risk that
the boards will cost too much to be affordable. This is a great way to cost-effectively launch your boards to market!
-Discussion
-***********
-
There's no real substitute for getting to know your contract manufacturer, its capabilities,
communication style, strengths, and weaknesses. Look around your town to see if anyone is
doing this type of work and see if they'll give you a tour.
.. note:: ?
-// To DO, fix this
+
+.. To DO
+ fix this
Don't confuse CircuitHub and CircuitCo. CircuitCo is the official contract manufacturer of
BeagleBoard.org and not the same company as CircuitHub, the online contract manufacturing
diff --git a/books/beaglebone-cookbook/10parts/parts.rst b/books/beaglebone-cookbook/10parts/parts.rst
index 2e6e6faf..18e1f84c 100644
--- a/books/beaglebone-cookbook/10parts/parts.rst
+++ b/books/beaglebone-cookbook/10parts/parts.rst
@@ -3,18 +3,13 @@
Parts and Suppliers
####################
-.. note::
- #TODO#: (Mark) Do we really need this? (Jason) Yeah, I think it is helpful.
-
Parts
-----------
+******
The following tables list where you can find the parts used in this book.
We have listed only one or two sources here, but you can often find a given part in many places.
-United States suppliers
-
-.. table::
+.. table:: United States suppliers
+-------------+------------------------------------+------------------------------------+
| Supplier | Website | Notes |
@@ -34,9 +29,7 @@ United States suppliers
| SparkFun | http://www.sparkfun.com | Good for modules and parts |
+-------------+------------------------------------+------------------------------------+
-Other suppliers
-
-.. table::
+.. table:: Other suppliers
+-----------+----------------------------------+-------------------------------------------------------------------------------------------+
| Supplier | Website | Notes |
@@ -44,10 +37,8 @@ Other suppliers
| Element14 | http://element14.com/BeagleBone | World-wide BeagleBoard.org-compliant clone of BeagleBone Black, carries many accessories |
+-----------+----------------------------------+-------------------------------------------------------------------------------------------+
-.. _app_proto:
-
Prototyping Equipment
------------------------
+======================
Many of the hardware projects in this book use jumper wires and a breadboard.
We prefer the preformed wires that lie flat on the board. <<parts_jumper>> lists places
@@ -55,9 +46,7 @@ with jumper wires, and <<parts_breadboard>> shows where you can get breadboards.
.. _parts_jumper:
-Jumper wires
-
-.. table::
+.. table:: Jumper wires
+-------------+--------------------------------------------------------------------------------------------+
| Supplier | Website |
@@ -74,9 +63,7 @@ Jumper wires
.. _parts_breadboard:
-Breadboards
-
-.. table::
+.. table:: Breadboards
+-------------+---------------------------------------------------------------------------------------------------------------------------------------------+
| Supplier | Website |
@@ -97,9 +84,9 @@ If you want something more permanent, try `Adafruit's Perma-Proto Breadboard <ht
.. _app_resistor:
Resistors
-----------
+==========
-We use 220 , 1 k, 4.7 k, 10 k, 20 k, and 22 k resistors in this book.
+We use 220 , 1k, 4.7k, 10k, 20k, and 22k resistors in this book.
All are 0.25 W. The easiest way to get all these, and many more, is to order `SparkFun's Resistor Kit <http://bit.ly/1EXREh8>`_.
It's a great way to be ready for future projects, because it has 500 resistors.
`RadioShack's 500-piece Resistor Assortment <http://shack.net/1B4Io4V>`_ is a bit more
@@ -115,10 +102,8 @@ You can find the 10 k trimpot (or variable resistor) at `SparkFun 10k POT <http:
Flex resistors (sometimes called *flex sensors* or *bend sensors*) are available at
`SparkFun flex resistors <http://bit.ly/1Br7HD2>`_ and `Adafruit flex resistors <http://bit.ly/1HCGoql>`_.
-.. _app_transistor:
-
Transistors and Diodes
------------------------
+=======================
The `2N3904 <http://bit.ly/1B4J8H4>`_ is a common NPN transistor that you can get almost anywhere.
Even `Amazon NPN transitor <http://amzn.to/1AjvcsD>`_ has it. `Adafruit NPN transitor <http://bit.ly/1b2dgxT>`_ has a nice 10-pack.
@@ -129,10 +114,8 @@ The `1N4001 <http://bit.ly/1EbRzF6>`_ is a popular 1A diode. Buy one at `SparkFu
10 at `Adafruit diode <http://bit.ly/1Gs05zP>`_, 25 at `RadioShack diode <http://shack.net/1E5OTXi>`_,
or 40,000 at `DigiKey diode <http://bit.ly/18ADlT2>`_.
-.. _app_ic:
-
Integrated Circuits
----------------------
+=====================
The PCA9306 is a small integrated circuit (IC) that converts voltage levels between 3.3 V and 5 V. You can get it
cheaply in large quantities from `DigiKey PCA9306 <http://bit.ly/1Fb8REd>`_, but it's in a very small, hard-to-use, surface-mount
@@ -153,10 +136,9 @@ sells it on a breakout board that works well with a breadboard.
The DS18B20 is a one-wire digital temperature sensor that looks like a three-terminal transistor.
Both `SparkFun DS18B20 <http://bit.ly/1Fba7Hv>`_ and `Adafruit DS18B20 <http://bit.ly/1EbSYvC>`_ carry it.
-.. _app_opto:
Opto-Electronics
------------------
+=================
`LEDs <http://bit.ly/1BwZvQj>`_ are *light-emitting diodes*. LEDs come in a wide range of colors,
brightnesses, and styles. You can get a basic red LED at `SparkFun red LED <http://bit.ly/1GFaHPi>`_,
@@ -165,104 +147,97 @@ brightnesses, and styles. You can get a basic red LED at `SparkFun red LED <http
Many places carry bicolor LED matrices, but be sure to get one with an I^2^C interface.
`Adafruit LED matrix <http://bit.ly/18AENVn>`_ is where I got mine.
-.. _app_capes:
-
Capes
-------
+======
There are a number of sources for capes for BeagleBone Black.
`eLinux.org BeagleBoard.org capes page <http://bit.ly/1AjlXJ9>`_ keeps a current list.
-
-.. _app_misc:
-
Miscellaneous
---------------
+==============
Here are some things that don't fit in the other categories.
-.Miscellaneous
-
-.. table::
-
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | 3.3 V FTDI cable | `SparkFun FTDI cable <http://bit.ly/1FMeXsG>`_, |
- | | `Adafruit FTDI cable <http://bit.ly/18AF1Mm>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | USB WiFi adapter | `Adafruit WiFi adapter <http://www.adafruit.com/products/814>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Female HDMI to male microHDMI adapter | `Amazon HDMI to microHDMI adapter <http://amzn.to/1C5BcLp>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | HDMI cable | `SparkFun HDMI cable <https://www.sparkfun.com/products/11572>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Micro HDMI to HDMI cable | `Adafruit HDMI to microHDMI cable <http://www.adafruit.com/products/1322>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | HDMI to DVI Cable | `SparkFun HDMI to DVI cable <https://www.sparkfun.com/products/12612>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | HDMI monitor | `Amazon HDMI monitor <http://amzn.to/1B4MABD>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Powered USB hub | `Amazon power USB hub <http://amzn.to/1NKm2zB>`_, |
- | | `Adafruit power USB hub <http://www.adafruit.com/products/961>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Keyboard with USB hub | `Amazon keyboard with USB hub <http://amzn.to/1FbblSX>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Soldering iron | `SparkFun soldering iron <http://bit.ly/1FMfUkP>`_, |
- | | `Adafruit soldering iron <http://bit.ly/1EXZ6J1>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Oscilloscope | `Adafruit oscilloscope <https://www.adafruit.com/products/468>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Multimeter | `SparkFun multimeter <http://bit.ly/1C5BUbu>`_, |
- | | `Adafruit multimeter <http://bit.ly/1wXX3np>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | PowerSwitch Tail II | `SparkFun PowerSwitch Tail II <http://bit.ly/1Ag5bLP>`_, |
- | | `Adafruit PowerSwitch Tail II <http://bit.ly/1wXX8aF>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
+.. table:: Miscellaneous
+
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | 3.3 V FTDI cable | `SparkFun FTDI cable <http://bit.ly/1FMeXsG>`_, |
+ | | `Adafruit FTDI cable <http://bit.ly/18AF1Mm>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | USB WiFi adapter | `Adafruit WiFi adapter <http://www.adafruit.com/products/814>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Female HDMI to male microHDMI adapter | `Amazon HDMI to microHDMI adapter <http://amzn.to/1C5BcLp>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | HDMI cable | `SparkFun HDMI cable <https://www.sparkfun.com/products/11572>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Micro HDMI to HDMI cable | `Adafruit HDMI to microHDMI cable <http://www.adafruit.com/products/1322>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | HDMI to DVI Cable | `SparkFun HDMI to DVI cable <https://www.sparkfun.com/products/12612>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | HDMI monitor | `Amazon HDMI monitor <http://amzn.to/1B4MABD>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Powered USB hub | `Amazon power USB hub <http://amzn.to/1NKm2zB>`_, |
+ | | `Adafruit power USB hub <http://www.adafruit.com/products/961>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Keyboard with USB hub | `Amazon keyboard with USB hub <http://amzn.to/1FbblSX>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Soldering iron | `SparkFun soldering iron <http://bit.ly/1FMfUkP>`_, |
+ | | `Adafruit soldering iron <http://bit.ly/1EXZ6J1>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Oscilloscope | `Adafruit oscilloscope <https://www.adafruit.com/products/468>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Multimeter | `SparkFun multimeter <http://bit.ly/1C5BUbu>`_, |
+ | | `Adafruit multimeter <http://bit.ly/1wXX3np>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | PowerSwitch Tail II | `SparkFun PowerSwitch Tail II <http://bit.ly/1Ag5bLP>`_, |
+ | | `Adafruit PowerSwitch Tail II <http://bit.ly/1wXX8aF>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
| Servo motor | `SparkFun servo motor <http://bit.ly/1C72cvw>`_, |
| | `Adafruit servo motor <http://bit.ly/1HCPQdl>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | 5 V power supply | `SparkFun 5V power supply <http://bit.ly/1C72q5C>`_, |
- | | `Adafruit 5V power supply <http://bit.ly/18c0n2D>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | 5 V power supply | `SparkFun 5V power supply <http://bit.ly/1C72q5C>`_, |
+ | | `Adafruit 5V power supply <http://bit.ly/18c0n2D>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
| 3 V to 5 V motor | `SparkFun 3V-5V motor <http://bit.ly/1b2g65Y>`_, |
| | `Adafruit 3V-5V motor <http://bit.ly/1C72DWF>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | 3 V to 5 V bipolar stepper motor | `SparkFun 3V-5V bipolar stepper motor <http://bit.ly/1Bx2hVU>`_, |
- | | `Adafruit 3V-5V bipolar stepper motor <http://bit.ly/18c0HhV>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | 3 V to 5 V unipolar stepper motor | `Adafruit 3V-5V unipolar stepper motor <http://www.adafruit.com/products/858>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Pushbutton switch | `SparkFun pushbutton switch <http://bit.ly/1AjDf90>`_, |
- | | `Adafruit pushbutton switch <http://bit.ly/1b2glhw>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Magnetic reed switch | `SparkFun magnetic reed switch <https://www.sparkfun.com/products/8642>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | LV-MaxSonar-EZ1 Sonar Range Finder | `SparkFun LV-MaxSonar-EZ1 <http://bit.ly/1C73dDH>`_, |
- | | `Amazon LV-MaxSonar-EZ1 <http://amzn.to/1wXXvlP>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | HC-SR04 Ultrsonic Range Sensor | `Amazon HC-SR04 <http://amzn.to/1FbcPNa>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Rotary encoder | `SparkFun rotary encoder <http://bit.ly/1D5ZypK>`_, |
- | | `Adafruit rotary encoder <http://bit.ly/1D5ZGp3>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | GPS receiver | `SparkFun GPS <http://bit.ly/1EA2sn0>`_, |
- | | `Adafruit GPS <http://bit.ly/1MrS2VV>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | BLE USB dongle | `Adafruit BLE USB dongle <http://www.adafruit.com/products/1327>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | SensorTag | `DigiKey SensorTag <http://bit.ly/18AGPVt>`_, |
- | | `Amazon SensorTag <http://amzn.to/1EA2B9U>`_, |
- | | `TI SensorTag <https://store.ti.com/CC2541-SensorTag-Development-Kit-P3192.aspx>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Syba SD-CM-UAUD USB Stereo Audio Adapter | `Amazon USB audio adapter <http://amzn.to/1EA2GdI>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Sabrent External Sound Box USB-SBCV | `Amazon USB audio adapter (alt) <http://amzn.to/1C74kTU>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Vantec USB External 7.1 Channel Audio Adapter | `Amazon USB audio adapter (alt2) <http://amzn.to/19cinev>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | Nokia 5110 LCD | `Adafruit 5110 LCD <http://bit.ly/1Ag6LgG>`_, |
- | | `SparkFun 5110 LCD <http://bit.ly/19cizdu>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
- | BeagleBone LCD7 | `eLinux LCD7 <http://elinux.org/CircuitCo:BeagleBone_LCD7#Distributors>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | 3 V to 5 V bipolar stepper motor | `SparkFun 3V-5V bipolar stepper motor <http://bit.ly/1Bx2hVU>`_, |
+ | | `Adafruit 3V-5V bipolar stepper motor <http://bit.ly/18c0HhV>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | 3 V to 5 V unipolar stepper motor | `Adafruit 3V-5V unipolar stepper motor <http://www.adafruit.com/products/858>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Pushbutton switch | `SparkFun pushbutton switch <http://bit.ly/1AjDf90>`_, |
+ | | `Adafruit pushbutton switch <http://bit.ly/1b2glhw>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Magnetic reed switch | `SparkFun magnetic reed switch <https://www.sparkfun.com/products/8642>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | LV-MaxSonar-EZ1 Sonar Range Finder | `SparkFun LV-MaxSonar-EZ1 <http://bit.ly/1C73dDH>`_, |
+ | | `Amazon LV-MaxSonar-EZ1 <http://amzn.to/1wXXvlP>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | HC-SR04 Ultrsonic Range Sensor | `Amazon HC-SR04 <http://amzn.to/1FbcPNa>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Rotary encoder | `SparkFun rotary encoder <http://bit.ly/1D5ZypK>`_, |
+ | | `Adafruit rotary encoder <http://bit.ly/1D5ZGp3>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | GPS receiver | `SparkFun GPS <http://bit.ly/1EA2sn0>`_, |
+ | | `Adafruit GPS <http://bit.ly/1MrS2VV>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | BLE USB dongle | `Adafruit BLE USB dongle <http://www.adafruit.com/products/1327>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | SensorTag | `DigiKey SensorTag <http://bit.ly/18AGPVt>`_, |
+ | | `Amazon SensorTag <http://amzn.to/1EA2B9U>`_, |
+ | | `TI SensorTag <https://store.ti.com/CC2541-SensorTag-Development-Kit-P3192.aspx>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Syba SD-CM-UAUD USB Stereo Audio Adapter | `Amazon USB audio adapter <http://amzn.to/1EA2GdI>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Sabrent External Sound Box USB-SBCV | `Amazon USB audio adapter (alt) <http://amzn.to/1C74kTU>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Vantec USB External 7.1 Channel Audio Adapter | `Amazon USB audio adapter (alt2) <http://amzn.to/19cinev>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | Nokia 5110 LCD | `Adafruit 5110 LCD <http://bit.ly/1Ag6LgG>`_, |
+ | | `SparkFun 5110 LCD <http://bit.ly/19cizdu>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
+ | BeagleBone LCD7 | `eLinux LCD7 <http://elinux.org/CircuitCo:BeagleBone_LCD7#Distributors>`_ |
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
| MiniDisplay Cape | `eLinux minidisplay <http://elinux.org/CircuitCo:MiniDisplay_Cape>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
--
GitLab