diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index abf6e568aa222716c210e535969493faa8d0426d..66142ecb97fae55857a2d888aeb8eec90fe53b09 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -3,10 +3,15 @@ image: beagle/sphinx-build-env:latest
stages:
- deploy
+cache:
+ key: bbdocs
+ paths:
+ - public
+
pages:
stage: deploy
script:
- - ./gitlab-build.sh
+ - ./gitlab-build.sh
artifacts:
paths:
- - public
+ - public
diff --git a/PAGES b/PAGES
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/VERSION b/VERSION
index 52daafdf597eab5aac8580ab3cc5fb35f28ca3e9..aa7870b204dd9ddff6fc071fc35debe46be42f11 100644
--- a/VERSION
+++ b/VERSION
@@ -1,5 +1,5 @@
VERSION_MAJOR = 0
VERSION_MINOR = 0
-PATCHLEVEL = 7
-VERSION_TWEAK = 2
-EXTRAVERSION = beta
+PATCHLEVEL = 9
+VERSION_TWEAK = 1
+EXTRAVERSION =
diff --git a/_static/css/custom.css b/_static/css/custom.css
index 19fa99fff967f7b6138d947a8ac93f03f335eed2..20417d54c45cf2b4a39e671926d756cede5fa5bc 100644
--- a/_static/css/custom.css
+++ b/_static/css/custom.css
@@ -18,9 +18,18 @@
}
.wy-nav-content {
- max-width: 100%;
+ max-width: 100%;
}
+.wy-side-scroll {
+ overflow-y: hidden;
+}
+
+.wy-menu.wy-menu-vertical {
+ overflow-y: auto;
+ overflow-x: hidden;
+ max-height: calc(100% - 247px);
+}
.wy-side-nav-search {
background-color: #25282b;
@@ -33,6 +42,7 @@
}
.wy-nav-side {
+ padding-bottom: 0px;
background-color: #25282b;
background-color: #25282b;
}
diff --git a/_templates/layout.html b/_templates/layout.html
new file mode 100644
index 0000000000000000000000000000000000000000..cd42441bc49212ded469a6ef1fdcf1bbb93118e5
--- /dev/null
+++ b/_templates/layout.html
@@ -0,0 +1,32 @@
+{% extends "!layout.html" %}
+{% block document %}
+ {% if pages_slug != "latest" %}
+ <div class="wy-alert wy-alert-danger">
+ The <a href="{{pages_url}}/latest">latest development version</a>
+ of this page may be more current than this released {{ version }} version.
+ </div>
+ {% else %}
+ <div class="wy-alert wy-alert-danger">
+ This is the latest (main) BeagleBoard documentation.
+ If you are looking for the previous releases, use the
+ drop-down menu on the left and select the desired version.
+ </div>
+ {% endif %}
+ {{ super() }}
+{% endblock %}
+{% block menu %}
+ {% include "versions.html" %}
+ {{ super() }}
+ {% if reference_links %}
+ <div class="toctree-wrapper compound">
+ <p class="caption"><span class="caption-text">Reference</span></p>
+ <ul>
+ {% for title, url in reference_links.items() %}
+ <li class="toctree-l1">
+ <a class="reference internal" href="{{ url }}">{{ title }}</a>
+ </li>
+ {% endfor %}
+ </ul>
+ </div>
+ {% endif %}
+{% endblock %}
diff --git a/_templates/versions.html b/_templates/versions.html
index d0228aeac47410c0dbdd063f33d946300e89235f..aeb38d9b0647fb7fd406436a5614cabe677b9030 100644
--- a/_templates/versions.html
+++ b/_templates/versions.html
@@ -2,19 +2,19 @@
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<span class="fa fa-book"> BeagleBoard Project</span>
- v: latest
+ v: {{ pages_slug }}
<span class="fa fa-caret-down"></span>
</span>
<div class="rst-other-versions">
<dl>
<dt>{{ _('Document Release Versions') }}</dt>
- <dd><a class="reference internal" href="">latest</a></dd>
- <dd><a class="reference internal" href="0.0.7">0.0.7</a></dd>
- <dd><a class="reference internal" href="0.1.0">0.1.0</a></dd>
+ {% for version_slug in versions %}
+ <dd><a href="{{pages_url}}/{{version_slug}}">{{ version_slug }}</a></dd>
+ {% endfor %}
</dl>
<dl>
<dt>{{ _('Downloads') }}</dt>
- <dd><a class="reference internal" href="beagleboard-docs.pdf">PDF</a></dd>
+ <dd><a href="{{docs_url}}/beagleboard-docs.pdf">PDF</a></dd>
</dl>
<dl>
<dt>{{ _('BeagleBoard.org Links') }}</dt>
diff --git a/boards/beaglebone/ai-64/ch06.rst b/boards/beaglebone/ai-64/ch06.rst
deleted file mode 100644
index 22a616fbe05d6040db5842de940c2a8896faab7a..0000000000000000000000000000000000000000
--- a/boards/beaglebone/ai-64/ch06.rst
+++ /dev/null
@@ -1,1758 +0,0 @@
-:orphan:
-
-.. _detailed-hardware-design:
-
-Detailed Hardware Design
-#########################
-
-This section provides a detailed description of the Hardware design.
-This can be useful for interfacing, writing drivers, or using it to help
-modify specifics of your own design.
-
-:ref:`bbai-64-block-diagram-ch06` below is the high level block diagram of the board. For those who may be concerned, It is the same figure as shown in :ref:`beaglebone-ai-64-high-level-specification`. It is placed here again for convenience so it is closer to the topics to follow.
-
-.. _bbai-64-block-diagram-ch06:
-
-.. figure:: images/ch05/board-block-diagram.svg
- :width: 400px
- :align: center
- :alt: Fig: BeagleBone AI-64 Key Components
-
- Fig: BeagleBone AI-64 Key Components
-
-.. _power-section:
-
-Power Section
------------------------------------
-
-:ref:`power-flow-diagram` shows the high level block diagram of the power section of the board.
-
-.. _power-flow-diagram,High level power block diagram:
-
-.. figure:: images/ch06/power.svg
- :width: 400px
- :align: center
- :alt: Fig: High level power block diagram
-
- Fig: High level power block diagram
-
-This section describes the power section of the design and all the
-functions performed by the *TPS65941213 and TPS65941111*.
-
-.. _TPS65941213-and-TPS65941111-pmic:
-
-TPS65941213 and TPS65941111 PMIC
-*********************************************
-
-The main Power Management IC (PMIC) in the system is the *TPS65941213 and TPS65941111*
-which is a single chip power management IC consisting of a linear
-dual-input power path, three step-down converters, and four LDOs. LDO
-stands for Low Drop Out. If you want to know more about an LDO, you can
-go to `http://en.wikipedia.org/wiki/Low-dropout_regulator <http://en.wikipedia.org/wiki/Low-dropout_regulator>`_ .
-
-If you want to learn more about step-down converters, you can go to `_http://en.wikipedia.org/wiki/DC-to-DC_converter <http://en.wikipedia.org/wiki/DC-to-DC_converter>`_ .
-
-The system is supplied by a USB port or DC adapter. Three
-high-efficiency 2.25MHz step-down converters are targeted at providing
-the core voltage, MPU, and memory voltage for the board.
-
-The step-down converters enter a low power mode at light load for
-maximum efficiency across the widest possible range of load currents.
-For low-noise applications the devices can be forced into fixed
-frequency PWM using the I2C interface. The step-down converters allow
-the use of small inductors and capacitors to achieve a small footprint
-solution size.
-
-LDO1 and LDO2 are intended to support system standby mode. In normal
-operation, they can support up to 100mA each. LDO3 and LDO4 can support
-up to 285mA each.
-
-By default only LDO1 is always ON but any rail can be configured to
-remain up in SLEEP state. In particular the DCDC converters can remain
-up in a low-power PFM mode to support processor suspend mode. The
-*TPS65941213 and TPS65941111* offers flexible power-up and power-down sequencing and
-several house-keeping functions such as power-good output, pushbutton
-monitor, hardware reset function and temperature sensor to protect the
-battery.
-
-See the :ref:`TPS6594-Q1-block-diagram` shown below for high level details
-for *TPS65941213 and TPS65941111*, for more information on the, refer to https://www.ti.com/product/TPS6594-Q1 Texas instruments product page.
-
-.. _TPS6594-Q1-block-diagram:
-
-.. figure:: images/ch06/TPS6594-Q1.svg
- :width: 400px
- :align: center
- :alt: Fig: TPS6594-Q1 block diagram
-
- Fig: TPS6594-Q1 block diagram
-
-.. _pmic-a-diagram,PMIC-A TPS65941213 circuit:
-
-.. figure:: images/ch06/pmic-a.svg
- :width: 400px
- :align: center
- :alt: Fig: PMIC-B TPS65941213 circuit
-
- Fig: PMIC-B TPS65941213 circuit
-
-.. _pmic-b-diagram,PMIC-B TPS65941111 circuit:
-
-.. figure:: images/ch06/pmic-b.svg
- :width: 400px
- :align: center
- :alt: Fig: PMIC-B TPS65941111 circuit
-
- Fig: PMIC-B TPS65941111 circuit
-
-.. _dc-input:
-
-DC Input
-***********
-
-:ref:`figure-23` below shows how the DC input is connected to the **TPS65941213 and TPS65941111**.
-
-.. _figure-23,Figure 23:
-
-.. figure:: media/image38.png
- :width: 400px
- :align: center
- :alt: Fig: TPS65217 DC Connection
-
- Fig: TPS65217 DC Connection
-
-A 5VDC supply can be used to provide power to the board. The power
-supply current depends on how many and what type of add-on boards are
-connected to the board. For typical use, a 5VDC supply rated at 1A
-should be sufficient. If heavier use of the expansion headers or USB
-host port is expected, then a higher current supply will be required.
-
-The connector used is a 2.1MM center positive x 5.5mm outer barrel. The
-5VDC rail is connected to the expansion header. It is possible to power
-the board via the expansion headers from an add-on card. The 5VDC is
-also available for use by the add-on cards when the power is supplied by
-the 5VDC jack on the board.
-
-.. _usb-power:
-
-USB Power
-*************
-
-The board can also be powered from the USB port. A typical USB port is
-limited to 500mA max. When powering from the USB port, the VDD_5V rail
-is not provided to the expansion headers, so capes that require the 5V
-rail to supply the cape direct, bypassing the *TPS65941213 and TPS65941111*, will not have
-that rail available for use. The 5VDC supply from the USB port is
-provided on the SYS_5V, the one that comes from the**TPS65941213 and TPS65941111**, rail
-of the expansion header for use by a cape. *Figure 24* is the connection
-of the USB power input on the PMIC.
-
-.. _figure-24.-usb-power-connections:
-
-.. figure:: media/image96.png
- :width: 400px
- :align: center
- :alt: Fig: USB Power Connections
-
- Fig: USB Power Connections
-
-
-
-.. _power-selection:
-
-Power Selection
-*********************************************
-
-The selection of either the 5VDC or the USB as the power source is
-handled internally to the *TPS65941213 and TPS65941111* and automatically switches to 5VDC
-power if both are connected. SW can change the power configuration via
-the I2C interface from the processor. In addition, the SW can read
-the**TPS65941213 and TPS65941111** and determine if the board is running on the 5VDC input
-or the USB input. This can be beneficial to know the capability of the
-board to supply current for things like operating frequency and
-expansion cards.
-
-It is possible to power the board from the USB input and then connect
-the DC power supply. The board will switch over automatically to the DC
-input.
-
-.. _power-button-1:
-
-Power Button
-*********************************************
-
-A power button is connected to the input of the *TPS65941213 and TPS65941111*. This is a
-momentary switch, the same type of switch used for reset and boot
-selection on the board.
-
-If you push the button the *TPS65941213 and TPS65941111* will send an interrupt to the
-processor. It is up to the processor to then pull the**PMIC_POWER_EN**
-pin low at the correct time to power down the board. At this point, the
-PMIC is still active, assuming that the power input was not removed.
-Pressing the power button will cause the board to power up again if the
-processor puts the board in the power off mode.
-
-In power off mode, the RTC rail is still active, keeping the RTC powered
-and running off the main power input. If you remove that power, then the
-RTC will not be powered. You also have the option of using the battery
-holes on the board to connect a battery if desired as discussed in the
-next section.
-
-If you push and hold the button for greater than 8 seconds, the PMIC
-will power down. But you must release the button when the power LED
-turns off. Holding the button past that point will cause the board to
-power cycle.
-
-.. _section-6-1-7,Section 6.1.7 Power Consumption:
-
-Power Consumption
-*********************************************
-
-The power consumption of the board varies based on power scenarios and
-the board boot processes. Measurements were taken with the board in the
-following configuration:
-
-* DC powered and USB powered
-* monitor connected
-* USB HUB
-* 4GB USB flash drive
-* Ethernet connected @ 100M
-* Serial debug cable connected
-
-:ref:`table-4` is an analysis of the power consumption of the board in these various scenarios.
-
-.. _table-4,Table 4:
-
-.. list-table:: Table 2: BeagleBone AI-64 Features and Specification
- :header-rows: 1
-
- * - MODE
- - USB
- - DC
- - C+USB
- * - Reset
- - TBD
- - TBD
- - TBD
- * - Idling @ UBoot
- - 210
- - 210
- - 210
- * - Kernel Booting (Peak)
- - 460
- - 460
- - 460
- * - Kernel Idling
- - 350
- - 350
- - 350
- * - Kernel Idling Display Blank
- - 280
- - 280
- - 280
- * - Loading a Webpage
- - 430
- - 430
- - 430
-
-The current will fluctuate as various activates occur, such as the LEDs
-on and microSD/eMMC accesses.
-
-.. _processor-interfaces:
-
-Processor Interfaces
-*********************************************
-
-The processor interacts with the *TPS65941213 and TPS65941111* via several different
-signals. Each of these signals is described below.
-
-.. _i2c0:
-
-I2C0
-************
-
-I2C0 is the control interface between the processor and the *TPS65941213 and TPS65941111*.
-It allows the processor to control the registers inside the**TPS65941213 and TPS65941111**
-for such things as voltage scaling and switching of the input rails.
-
-.. _pmc_powr_en:
-
-PMIC_POWR_EN
-******************
-
-On power up the *VDD_RTC* rail activates first. After the RTC circuitry
-in the processor has activated it instructs the**TPS65941213 and TPS65941111** to initiate
-a full power up cycle by activating the *PMIC_POWR_EN* signal by taking
-it HI. When powering down, the processor can take this pin low to start
-the power down process.
-
-.. _ldo_good:
-
-LDO_GOOD
-*********************
-
-This signal connects to the *RTC_PORZn* signal, RTC power on reset. The
-small “*n*†indicates that the signal is an active low signal. Word
-processors seem to be unable to put a bar over a word so the**n** is
-commonly used in electronics. As the RTC circuitry comes up first, this
-signal indicates that the LDOs, the 1.8V VRTC rail, is up and stable.
-This starts the power up process.
-
-.. _pmic_pgood:
-
-PMIC_PGOOD
-******************
-
-Once all the rails are up, the *PMIC_PGOOD* signal goes high. This
-releases the**PORZn** signal on the processor which was holding the
-processor reset.
-
-.. _wakeup:
-
-WAKEUP
-**************
-
-The WAKEUP signal from the *TPS65941213 and TPS65941111* is connected to the**EXT_WAKEUP**
-signal on the processor. This is used to wake up the processor when it
-is in a sleep mode. When an event is detected by the *TPS65941213 and TPS65941111*, such
-as the power button being pressed, it generates this signal.
-
-.. _pmic_int:
-
-PMIC_INT
-************
-
-The *PMIC_INT* signal is an interrupt signal to the processor. Pressing
-the power button will send an interrupt to the processor allowing it to
-implement a power down mode in an orderly fashion, go into sleep mode,
-or cause it to wake up from a sleep mode. All of these require SW
-support.
-
-.. _power-rails:
-
-6.1.9 Power Rails
-***********************
-
-:ref:`figure-25` shows the connections of each of the rails from the **TPS65941213 and TPS65941111**.
-
-.. _figure-25,Figure 25:
-
-.. figure:: media/image39.jpg
- :width: 400px
- :align: center
- :alt: fig-25: Power Rails
-
- Fig-25: Power Rails
-
-VRTC Rail
-************
-
-The *VRTC* rail is a 1.8V rail that is the first rail to come up in the
-power sequencing. It provides power to the RTC domain on the processor
-and the I/O rail of the **TPS65941213 and TPS65941111**. It can deliver up to 250mA
-maximum.
-
-VDD_3V3A Rail
-*************************
-
-The *VDD_3V3A* rail is supplied by the **TPS65941213 and TPS65941111** and provides the
-3.3V for the processor rails and can provide up to 400mA.
-
-VDD_3V3B Rail
-**********************
-
-The current supplied by the *VDD_3V3A* rail is not sufficient to power
-all of the 3.3V rails on the board. So a second LDO is supplied, U4,
-a **TL5209A**, which sources the *VDD_3V3B* rail. It is powered up just
-after the *VDD_3V3A* rail.
-
-VDD_1V8 Rail
-*********************************************
-
-The *VDD_1V8* rail can deliver up to 400mA and provides the power
-required for the 1.8V rails on the processor and the display framer. This
-rail is not accessible for use anywhere else on the board.
-
-VDD_CORE Rail
-*********************************************
-
-The *VDD_CORE* rail can deliver up to 1.2A at 1.1V. This rail is not
-accessible for use anywhere else on the board and connects only to the
-processor. This rail is fixed at 1.1V and should not be adjusted by SW
-using the PMIC. If you do, then the processor will no longer work.
-
-VDD_MPU Rail
-*********************************************
-
-The *VDD_MPU* rail can deliver up to 1.2A. This rail is not accessible
-for use anywhere else on the board and connects only to the processor.
-This rail defaults to 1.1V and can be scaled up to allow for higher
-frequency operation. Changing of the voltage is set via the I2C
-interface from the processor.
-
-VDDS_DDR Rail
-*********************************************
-
-The *VDDS_DDR* rail defaults to**1.5V** to support the LPDDR4 rails and
-can deliver up to 1.2A. It is possible to adjust this voltage rail down
-to *1.35V* for lower power operation of the LPDDR4 device. Only LPDDR4
-devices can support this voltage setting of 1.35V.
-
-Power Sequencing
-*********************************************
-
-The power up process is consists of several stages and events. :ref:`figure-26`
-describes the events that make up the power up process for the
-processer from the PMIC. This diagram is used elsewhere to convey
-additional information. I saw no need to bust it up into smaller
-diagrams. It is from the processor datasheet supplied by Texas
-Instruments.
-
-.. _figure-26,Figure 26:
-
-.. figure:: media/image40.png
- :width: 400px
- :align: center
- :alt: Fig-26: Power Rail Power Up Sequencing
-
- Fig-26: Power Rail Power Up Sequencing
-
-:ref:`figure-27` the voltage rail sequencing for the**TPS65941213 and TPS65941111** as it
-powers up and the voltages on each rail. The power sequencing starts at
-15 and then goes to one. That is the way the *TPS65941213 and TPS65941111* is configured.
-You can refer to the TPS65941213 and TPS65941111 datasheet for more information.
-
-.. _figure-27,Figure 27:
-
-.. figure:: media/image41.png
- :width: 400px
- :align: center
- :alt: Fig-27: TPS65941213 and TPS65941111 Power Sequencing Timing
-
- Fig-27: TPS65941213 and TPS65941111 Power Sequencing Timing
-
-.. _power-led:
-
-Power LED
-*********************************************
-
-The power LED is a blue LED that will turn on once the *TPS65941213 and TPS65941111* has
-finished the power up procedure. If you ever see the LED flash once,
-that means that the**TPS65941213 and TPS65941111** started the process and encountered an
-issue that caused it to shut down. The connection of the LED is shown in
-:ref:`figure-25`.
-
-.. _TPS65941213-and-TPS65941111-power-up-process:
-
-TPS65941213 and TPS65941111 Power Up Process
-*********************************************
-
-:ref:`figure-28` shows the interface between the **TPS65941213 and TPS65941111** and the
-processor. It is a cut from the PDF form of the schematic and reflects
-what is on the schematic.
-
-.. _figure-28,Figure 28:
-
-.. figure:: media/image42.jpg
- :width: 400px
- :align: center
- :alt: Fig-28: Power Processor Interfaces
-
-When voltage is applied, DC or USB, the *TPS65941213 and TPS65941111* connects the power
-to the SYS output pin which drives the switchers and LDOs in
-the **TPS65941213 and TPS65941111**.
-
-At power up all switchers and LDOs are off except for the *VRTC LDO*
-(1.8V), which provides power to the VRTC rail and controls
-the **RTC_PORZn** input pin to the processor, which starts the power up
-process of the processor. Once the RTC rail powers up, the *RTC_PORZn*
-pin, driven by the *LDO_PGOOD* signal from the *TPS65941213 and TPS65941111*, of the
-processor is released.
-
-Once the *RTC_PORZn* reset is released, the processor starts the
-initialization process. After the RTC stabilizes, the processor launches
-the rest of the power up process by activating the**PMIC_POWER_EN**
-signal that is connected to the *TPS65941213 and TPS65941111* which starts the *TPS65941213 and TPS65941111*
-power up process.
-
-The *LDO_PGOOD* signal is provided by the**TPS65941213 and TPS65941111** to the processor.
-As this signal is 1.8V from the *TPS65941213 and TPS65941111* by virtue of the *TPS65941213 and TPS65941111*
-VIO rail being set to 1.8V, and the *RTC_PORZ* signal on the processor
-is 3.3V, a voltage level shifter, *U4*, is used. Once the LDOs and
-switchers are up on the *TPS65941213 and TPS65941111*, this signal goes active releasing
-the processor. The LDOs on the *TPS65941213 and TPS65941111* are used to power the VRTC
-rail on the processor.
-
-.. _processor-control-interface:
-
-Processor Control Interface
-*********************************************
-
-:ref:`figure-28` above shows two interfaces between the processor and
-the**TPS65941213 and TPS65941111** used for control after the power up sequence has
-completed.
-
-The first is the *I2C0* bus. This allows the processor to turn on and
-off rails and to set the voltage levels of each regulator to supports
-such things as voltage scaling.
-
-The second is the interrupt signal. This allows the *TPS65941213 and TPS65941111* to alert
-the processor when there is an event, such as when the power button is
-pressed. The interrupt is an open drain output which makes it easy to
-interface to 3.3V of the processor.
-
-.. _low-power-mode-support:
-
-Low Power Mode Support
-*********************************************
-
-This section covers three general power down modes that are available.
-These modes are only described from a Hardware perspective as it relates
-to the HW design.
-
-RTC Only
-*********************************************
-
-In this mode all rails are turned off except the *VDD_RTC*. The
-processor will need to turn off all the rails to enter this mode.
-The **VDD_RTC** staying on will keep the RTC active and provide for the
-wakeup interfaces to be active to respond to a wake up event.
-
-RTC Plus DDR
-*********************************************
-
-In this mode all rails are turned off except the *VDD_RTC* and
-the **VDDS_DDR**, which powers the LPDDR4 memory. The processor will need
-to turn off all the rails to enter this mode. The *VDD_RTC* staying on
-will keep the RTC active and provide for the wakeup interfaces to be
-active to respond to a wake up event.
-
-The *VDDS_DDR* rail to the LPDDR4 is provided by the 1.5V rail of
-the **TPS65941213 and TPS65941111** and with *VDDS_DDR* active, the LPDDR4 can be placed in
-a self refresh mode by the processor prior to power down which allows
-the memory data to be saved.
-
-Currently, this feature is not included in the standard software
-release. The plan is to include it in future releases.
-
-Voltage Scaling
-*********************************************
-
-For a mode where the lowest power is possible without going to sleep,
-this mode allows the voltage on the ARM processor to be lowered along
-with slowing the processor frequency down. The I2C0 bus is used to
-control the voltage scaling function in the *TPS65941213 and TPS65941111*.
-
-.. _sitara-am3358bzcz100-processor:
-
-TI J721E DRA829/TDA4VM/AM752x Processor
------------------------------------------
-
-The board is designed to use the TI J721E DRA829/TDA4VM/AM752x processor in the
-15 x 15 package.
-
-.. _description:
-
-Description
-*********************************************
-
-:ref:`figure-29` is a high level block diagram of the processor. For more information on the processor, go to `https://www.ti.com/product/TDA4VM <https://www.ti.com/product/TDA4VM>`_
-
-.. _figure-29,Figure 29:
-
-.. figure:: media/image43.png
- :width: 400px
- :align: center
- :alt: Fig-29: Jacinto TDA4VMBZCZ Block Diagram
-
- Fig-29: Jacinto TDA4VMBZCZ Block Diagram
-
-
-.. _high-level-features:
-
-High Level Features
-*********************************************
-
-:ref:`table-5` below shows a few of the high level features of the Jacinto
-processor.
-
-.. _table-5,Table 5:
-
-
-.. list-table:: Table 5: Processor Features
- :header-rows: 1
-
- * - Operating Systems
- - Linux, Android, Windows Embedded CE,QNX,ThreadX
- - MMC/SD
- - 3
- * - Standby Power
- - 7 mW
- - CAN
- - 2
- * - ARM CPU
- - 1 ARM Cortex-A8
- - UART (SCI)
- - 6
- * - ARM MHz (Max.)
- - 275,500,600,800,1000
- - ADC
- - 8-ch 12-bit
- * - ARM MIPS (Max.)
- - 1000,1200,2000
- - PWM (Ch)
- - 3
- * - Graphics Acceleration
- - 1 3D
- - eCAP
- - 3
- * - Other Hardware Acceleration
- - 2 PRU-ICSS,Crypto Accelerator
- - eQEP
- - 3
- * - On-Chip L1 Cache
- - 64 KB (ARM Cortex-A8)
- - RTC
- - 1
- * - On-Chip L2 Cache
- - 256 KB (ARM Cortex-A8)
- - I2C
- - 3
- * - Other On-Chip Memory
- - 128 KB
- - McASP
- - 2
- * - Display Options
- - LCD
- - SPI
- - 2
- * - General Purpose Memory
- - 1 16-bit (GPMC, NAND flash, NOR Flash, SRAM)
- - DMA (Ch)
- - 64-Ch EDMA
- * - DRAM
- - 1 16-bit (LPDDR-400,DDR2-532, DDR3-400)
- - IO Supply (V)
- - 1.8V(ADC),3.3V
- * - USB Ports
- - 2
- - Operating Temperature Range (C)
- - -40 to 90
-
-.. _documentation:
-
-Documentation
-**********************
-
-Full documentation for the processor can be found on the TI website at `https://www.ti.com/product/TDA4VM <https://www.ti.com/product/TDA4VM>`_ for the current processor used on the board. Make sure that you always use the latest datasheets and Technical Reference Manuals (TRM).
-
-.. _crystal-circuitry:
-
-Crystal Circuitry
-***********************
-
-:ref:`figure-30` is the crystal circuitry for the TDA4VM processor.
-
-.. _figure-30,Figure 30:
-
-.. figure:: media/image44.png
- :width: 400px
- :align: center
- :alt: Fig-30: Processor Crystals
-
- Fig-30: Processor Crystals
-
-.. _reset-circuitry:
-
-Reset Circuitry
-*********************************************
-
-:ref:`figure-31` is the board reset circuitry. The initial power on reset is
-generated by the **TPS65941213 and TPS65941111** power management IC. It also handles the
-reset for the Real Time Clock.
-
-The board reset is the SYS_RESETn signal. This is connected to the
-NRESET_INOUT pin of the processor. This pin can act as an input or an
-output. When the reset button is pressed, it sends a warm reset to the
-processor and to the system.
-
-On the revision A5D board, a change was made. On power up, the
-NRESET_INOUT signal can act as an output. In this instance it can cause
-the SYS_RESETn line to go high prematurely. In order to prevent this,
-the PORZn signal from the TPS65941213 and TPS65941111 is connected to the SYS_RESETn line
-using an open drain buffer. These ensure that the line does not
-momentarily go high on power up.
-
-.. _figure-31,Figure 31:
-
-.. figure:: media/image45.png
- :width: 400px
- :align: center
- :alt: Fig-31: Board Reset Circuitry
-
- Fig-31: Board Reset Circuitry
-
-This change is also in all revisions after A5D.
-
-LPDDR4 Memory
-
-BeagleBone AI-64 uses a single MT41K256M16HA-125 512MB LPDDR4 device
-from Micron that interfaces to the processor over 16 data lines, 16
-address lines, and 14 control lines. On rev C we added the Kingston
-*KE4CN2H5A-A58* device as a source for the LPDDR4 device.
-
-The following sections provide more details on the design.
-
-.. _memory-device:
-
-Memory Device
-*********************************************
-
-The design supports the standard DDR3 and LPDDR4 x16 devices and is built
-using the LPDDR4. A single x16 device is used on the board and there is
-no support for two x8 devices. The DDR3 devices work at 1.5V and the
-LPDDR4 devices can work down to 1.35V to achieve lower power. The LPDDR4 comes in a 96-BALL FBGA package
-with 0.8 mil pitch. Other standard DDR3 devices can also be supported,
-but the LPDDR4 is the lower power device and was chosen for its ability
-to work at 1.5V or 1.35V. The standard frequency that the LPDDR4 is run
-at on the board is 400MHZ.
-
-.. _ddr3l-memory-design:
-
-LPDDR4 Memory Design
-*********************************************
-
-:ref:`figure-32` is the schematic for the LPDDR4 memory device. Each of the
-groups of signals is described in the following lines.
-
-*Address Lines:* Provide the row address for ACTIVATE commands, and the
-column address and auto pre-charge bit (A10) for READ/WRITE commands, to
-select one location out of the memory array in the respective bank. A10
-sampled during a PRECHARGE command determines whether the PRECHARGE applies to one bank (A10 LOW, bank selected by BA[2:0]) or all banks (A10 HIGH). The address
-inputs also provide the op-code during a LOAD MODE command. Address
-inputs are referenced to VREFCA. A12/BC#: When enabled in the mode
-register (MR), A12 is sampled during READ and WRITE commands to
-determine whether burst chop (on-the-fly) will be performed (HIGH BL8
-or no burst chop, LOW BC4 burst chop).
-
-*Bank Address Lines:* BA[2:0] define the bank to which an ACTIVATE, READ, WRITE, or PRECHARGE command is being applied. BA[2:0] define which mode register (MR0, MR1, MR2, or MR3) is loaded during the LOAD MODE command. BA[2:0] are referenced to VREFCA.
-
-*CK and CK# Lines:* are differential clock inputs. All address and
-control input signals are sampled on the crossing of the positive edge
-of CK and the negative edge of CK#. Output data strobe (DQS, DQS#) is
-referenced to the crossings of CK and CK#.
-
-*Clock Enable Line:* CKE enables (registered HIGH) and disables
-(registered LOW) internal circuitry and clocks on the DRAM. The specific
-circuitry that is enabled/disabled is dependent upon the DDR3 SDRAM
-configuration and operating mode. Taking CKE LOW provides PRECHARGE
-power-down and SELF REFRESH operations (all banks idle) or active
-power-down (row active in any bank). CKE is synchronous for powerdown
-entry and exit and for self refresh entry. CKE is asynchronous for self
-refresh exit. Input buffers (excluding CK, CK#, CKE, RESET#, and ODT)
-are disabled during powerdown. Input buffers (excluding CKE and RESET#)
-are disabled during SELF REFRESH. CKE is referenced to VREFCA.
-
-.. _figure-32,Figure 32:
-
-.. figure:: media/image46.png
- :width: 400px
- :align: center
- :alt: Fig-32: LPDDR4 Memory Design
-
- Fig-32: LPDDR4 Memory Design
-
-*Chip Select Line:* CS# enables (registered LOW) and disables
-(registered HIGH) the command decoder. All commands are masked when CS#
-is registered HIGH. CS# provides for external rank selection on systems
-with multiple ranks. CS# is considered part of the command code. CS# is
-referenced to VREFCA.
-
-*Input Data Mask Line:* DM is an input mask signal for write data. Input
-data is masked when DM is sampled HIGH along with the input data during
-a write access. Although the DM ball is input-only, the DM loading is
-designed to match that of the DQ and DQS balls. DM is referenced to
-VREFDQ.
-
-*On-die Termination Line:* ODT enables (registered HIGH) and disables
-(registered LOW) termination resistance internal to the LPDDR4 SDRAM.
-When enabled in normal operation, ODT is only applied to each of the
-following balls: DQ[7:0], DQS, DQS#, and DM for the x8; DQ[3:0], DQS,
-DQS#, and DM for the x4. The ODT input is ignored if disabled via the
-LOAD MODE command. ODT is referenced to VREFCA.
-
-.. _power-rails-1:
-
-Power Rails
-******************
-
-The *LPDDR4* memory device and the DDR3 rails on the processor are
-supplied by the**TPS65941213 and TPS65941111**. Default voltage is 1.5V but can be scaled
-down to 1.35V if desired.
-
-.. _vref:
-
-VREF
-***************
-
-The *VREF* signal is generated from a voltage divider on the **VDDS_DDR**
-rail that powers the processor DDR rail and the LPDDR4 device itself.
-*Figure 33* below shows the configuration of this signal and the
-connection to the LPDDR4 memory device and the processor.
-
-.. _figure-33,Figure 33:
-
-.. figure:: media/image47.jpg
- :width: 400px
- :align: center
- :alt: Fig-33: LPDDR4 VREF Design
-
- Fig-33: LPDDR4 VREF Design
-
-
-
-.. _gb-emmc-memory:
-
-4GB eMMC Memory
------------------------------------
-
-The eMMC is a communication and mass data storage device that includes a
-Multi-MediaCard (MMC) interface, a NAND Flash component, and a
-controller on an advanced 11-signal bus, which is compliant with the MMC
-system specification. The nonvolatile eMMC draws no power to maintain
-stored data, delivers high performance across a wide range of operating
-temperatures, and resists shock and vibration disruption.
-
-One of the issues faced with SD cards is that across the different
-brands and even within the same brand, performance can vary. Cards use
-different controllers and different memories, all of which can have bad
-locations that the controller handles. But the controllers may be
-optimized for reads or writes. You never know what you will be getting.
-This can lead to varying rates of performance. The eMMC card is a known
-controller and when coupled with the 8bit mode, 8 bits of data instead
-of 4, you get double the performance which should result in quicker boot
-times.
-
-The following sections describe the design and device that is used on
-the board to implement this interface.
-
-.. _emmc-device:
-
-eMMC Device
-*********************************************
-
-The device used is one of two different devices:
-
-* Micron *MTFC4GLDEA 0M WT*
-* Kingston *KE4CN2H5A-A58*
-
-The package is a 153 ball WFBGA device on both devices.
-
-.. _emmc-circuit-design:
-
-eMMC Circuit Design
-*********************************************
-
-:ref:`figure-34` is the design of the eMMC circuitry. The eMMC device is
-connected to the MMC1 port on the processor. MMC0 is still used for the
-microSD card as is currently done on the BeagleBone Black. The size
-of the eMMC supplied is now 4GB.
-
-The device runs at 3.3V both internally and the external I/O rails. The
-VCCI is an internal voltage rail to the device. The manufacturer
-recommends that a 1uF capacitor be attached to this rail, but a 2.2uF
-was chosen to provide a little margin.
-
-Pullup resistors are used to increase the rise time on the signals to
-compensate for any capacitance on the board.
-
-.. _figure-34,Figure 34:
-
-.. figure:: media/image48.png
- :width: 400px
- :align: center
- :alt: Fig-34: eMMC Memory Design
-
- Fig-34: eMMC Memory Design
-
-
-
-The pins used by the eMMC1 in the boot mode are listed below in *Table 6*.
-
-.. _table-6,Table 6:
-
-.. figure:: media/image49.png
- :width: 400px
- :align: center
- :alt: Table 6: eMMC Boot Pins
-
- Table 6: eMMC Boot Pins
-
-
-For eMMC devices the ROM will only support raw mode. The ROM Code reads
-out raw sectors from image or the booting file within the file system
-and boots from it. In raw mode the booting image can be located at one
-of the four consecutive locations in the main area: offset 0x0 / 0x20000
-(128 KB) / 0x40000 (256 KB) / 0x60000 (384 KB). For this reason, a
-booting image shall not exceed 128KB in size. However it is possible to
-flash a device with an image greater than 128KB starting at one of the
-aforementioned locations. Therefore the ROM Code does not check the
-image size. The only drawback is that the image will cross the
-subsequent image boundary. The raw mode is detected by reading sectors
-#0, #256, #512, #768. The content of these sectors is then verified for
-presence of a TOC structure. In the case of a *GP Device*, a
-Configuration Header (CH)*must* be located in the first sector followed
-by a *GP header*. The CH might be void (only containing a CHSETTINGS
-item for which the Valid field is zero).
-
-The ROM only supports the 4-bit mode. After the initial boot, the switch
-can be made to 8-bit mode for increasing the overall performance of the
-eMMC interface.
-
-.. _board-id-eeprom:
-
-Board ID EEPROM
------------------------------------
-
-BeagleBone is equipped with a single 32Kbit(4KB) 24LC32AT-I/OT
-EEPROM to allow the SW to identify the board. *Table 7* below defined
-the contents of the EEPROM.
-
-.. _table-7,Table 7:
-
-.. list-table:: Table 7: EEPROM Contents
- :header-rows: 1
-
- * - Name
- - Size (bytes)
- - Contents
- * - Header
- - 4
- - 0xAA, 0x55, 0x33, EE
- * - Board Name
- - 8
- - Name for board in ASCII: A335BNLT
- * - Version
- - 4
- - Hardware version code for board in ASCII: 00A3 for Rev A3, 00A4 for Rev A4, 00A5 for Rev A5,00A6 for Rev A6,00B0 for Rev B, and 00C0 for Rev C.
- * - Serial Number
- - 12
- - Serial number of the board. This is a 12 character string which is: WWYY4P16nnnn where: WW 2 digit week of the year of production YY 2 digit year of production BBBK BeagleBone AI-64 nnnn incrementing board number
- * - Configuration Option
- - 32
- - Codes to show the configuration setup on this board.All FF
- * - RSVD
- - 6
- - FF FF FF FF FF FF
- * - RSVD
- - 6
- - FF FF FF FF FF FF
- * - RSVD
- - 6
- - FF FF FF FF FF FF
- * - Available
- - 4018
- - Available space for other non-volatile codes/data
-
-:ref:`figure-35` shows the new design on the EEPROM interface.
-
-.. _figure-35,Figure 35:
-
-.. figure:: media/image50.png
- :width: 400px
- :align: center
- :alt: Figure 35. EEPROM Design Rev A5
-
- Fig-35: EEPROM Design Rev A5
-
-
-
-The EEPROM is accessed by the processor using the I2C 0 bus. The *WP*
-pin is enabled by default. By grounding the test point, the write
-protection is removed.
-
-The first 48 locations should not be written to if you choose to use the
-extras storage space in the EEPROM for other purposes. If you do, it
-could prevent the board from booting properly as the SW uses this
-information to determine how to set up the board.
-
-.. _micro-secure-digital:
-
-Micro Secure Digital
------------------------------------
-
-The microSD connector on the board will support a microSD card that can
-be used for booting or file storage on BeagleBone AI-64.
-
-.. _microsd-design:
-
-microSD Design
-*********************************************
-
-:ref:`figure-36` below is the design of the microSD interface on the board.
-
-.. _figure-36,Figure 36:
-
-.. figure:: media/image51.png
- :width: 400px
- :align: center
- :alt: Figure 36. microSD Design
-
- Fig-36: microSD Design
-
-
-
-The signals *MMC0-3* are the data lines for the transfer of data between
-the processor and the microSD connector.
-
-The *MMC0_CLK* signal clocks the data in and out of the microSD card.
-
-The *MMCO_CMD* signal indicates that a command versus data is being sent.
-
-There is no separate card detect pin in the microSD specification. It
-uses *MMCO_DAT3* for that function. However, most microSD connectors
-still supply a CD function on the connectors. In BeagleBone AI-64
-design, this pin is connected to the**MMC0_SDCD** pin for use by the
-processor. You can also change the pin to *GPIO0_6*, which is able to
-wake up the processor from a sleep mode when an microSD card is inserted
-into the connector.
-
-Pullup resistors are provided on the signals to increase the rise times
-of the signals to overcome PCB capacitance.
-
-Power is provided from the *VDD_3V3B* rail and a 10uF capacitor is
-provided for filtering.
-
-.. _user-leds:
-
-User LEDs
------------------------------------
-
-There are four user LEDs on BeagleBone AI-64. These are connected to
-GPIO pins on the processor. *Figure 37* shows the interfaces for the
-user LEDs.
-
-.. _figure-37,Figure 37:
-
-.. figure:: media/image52.png
- :width: 400px
- :align: center
- :alt: Figure 37. User LEDs
-
- Fig-37: User LEDs
-
-Resistors R71-R74 were changed to 4.75K on the revision A5B and later
-boards.
-
-:ref:`table-8` shows the signals used to control the four LEDs from the
-processor.
-
-.. _table-8,Table 8:
-
-.. list-table:: Table 8: User LED Control Signals/Pins
- :header-rows: 1
-
- * - LED
- - GPIO SIGNAL
- - PROC PIN
- * - USR0
- - GPIO1_21
- - V15
- * - USR1
- - GPIO1_22
- - U15
- * - USR2
- - GPIO1_23
- - T15
- * - USR3
- - GPIO1_24
- - V16
-
-
-
-A logic level of “1†will cause the LEDs to turn on.
-
-.. _boot-configuration:
-
-Boot Configuration
------------------------------------
-
-The design supports two groups of boot options on the board. The user
-can switch between these modes via the Boot button. The primary boot
-source is the onboard eMMC device. By holding the Boot button, the user
-can force the board to boot from the microSD slot. This enables the eMMC
-to be overwritten when needed or to just boot an alternate image. The
-following sections describe how the boot configuration works.
-
-In most applications, including those that use the provided demo
-distributions available from `beagleboard.org <http://beagleboard.org/>`_ the processor-external boot code is composed of two stages. After the
-primary boot code in the processor ROM passes control, a secondary stage
-(secondary program loader -- "SPL" or "MLO") takes over. The SPL stage
-initializes only the required devices to continue the boot process, and
-then control is transferred to the third stage "U-boot". Based on the
-settings of the boot pins, the ROM knows where to go and get the SPL and
-UBoot code. In the case of BeagleBone AI-64, that is either eMMC or
-microSD based on the position of the boot switch.
-
-.. _boot-configuration-design:
-
-Boot Configuration Design
-*********************************************
-
-:ref:`figure-38` shows the circuitry that is involved in the boot
-configuration process. On power up, these pins are read by the processor
-to determine the boot order. S2 is used to change the level of one bit
-from HI to LO which changes the boot order.
-
-.. _figure-38,Figure 38:
-
-.. figure:: media/image53.png
- :width: 400px
- :align: center
- :alt: Figure 38. Processor Boot Configuration Design
-
- Fig-38: Processor Boot Configuration Design
-
-It is possible to override these setting via the expansion headers. But
-be careful not to add too much load such that it could interfere with
-the operation of the display interface or LCD panels. If you choose to
-override these settings, it is strongly recommended that you gate these
-signals with the *SYS_RESETn* signal. This ensures that after coming out
-of reset these signals are removed from the expansion pins.
-
-.. _default-boot-options:
-
-Default Boot Options
------------------------------------
-
-Based on the selected option found in :ref:`figure-39` below, each of the
-boot sequences for each of the two settings is shown.
-
-.. _figure-39,Figure 39:
-
-.. figure:: media/image54.jpg
- :width: 400px
- :align: center
- :alt: Figure 39. Processor Boot Configuration
-
- Fig-39: Processor Boot Configuration
-
-The first row in :ref:`figure-39` is the default setting. On boot, the
-processor will look for the eMMC on the MMC1 port first, followed by the
-microSD slot on MMC0, USB0 and UART0. In the event there is no microSD
-card and the eMMC is empty, UART0 or USB0 could be used as the board
-source.
-
-If you have a microSD card from which you need to boot from, hold the
-boot button down. On boot, the processor will look for the SPIO0 port
-first, then microSD on the MMC0 port, followed by USB0 and UART0. In the
-event there is no microSD card and the eMMC is empty, USB0 or UART0
-could be used as the board source.
-
-.. _ethernet:
-
-10/100 Ethernet
------------------------------------
-
-BeagleBone AI-64 is equipped with a 10/100 Ethernet interface. It
-uses the same PHY as is used on the BeagleBone Black. The design is
-described in the following sections.
-
-.. _ethernet-processor-interface:
-
-Ethernet Processor Interface
-*********************************************
-
-:ref:`figure-40` shows the connections between the processor and the PHY. The
-interface is in the MII mode of operation.
-
-.. _figure-40,Figure 40:
-
-.. figure:: media/image55.png
- :width: 400px
- :align: center
- :alt: Figure 40. Ethernet Processor Interface
-
- Fig-40: Ethernet Processor Interface
-
-
-
-This is the same interface as is used on BeagleBone. No changes were
-made in this design for the board.
-
-.. _ethernet-connector-interface:
-
-Ethernet Connector Interface
-*********************************************
-
-The off board side of the PHY connections are shown in *Figure 41*
-below.
-
-.. _figure-41,Figure 41:
-
-.. figure:: media/image56.png
- :width: 400px
- :align: center
- :alt: Figure 41. Ethernet Connector Interface
-
- Fig-41: Ethernet Connector Interface
-
-This is the same interface as is used on BeagleBone. No changes were
-made in this design for the board.
-
-.. _ethernet-phy-power-reset-and-clocks:
-
-Ethernet PHY Power, Reset, and Clocks
-*********************************************
-
-:ref:`figure-42` shows the power, reset, and lock connections to
-the **LAN8710A** PHY. Each of these areas is discussed in more detail in
-the following sections.
-
-.. _figure-42,Figure 42:
-
-.. figure:: media/image57.png
- :width: 400px
- :align: center
- :alt: .Figure 42. Ethernet PHY, Power, Reset, and Clocks
-
- Fig-42: Ethernet PHY, Power, Reset, and Clocks
-
-
-
-VDD_3V3B Rail
-*****************
-
-The VDD_3V3B rail is the main power rail for the *LAN8710A*. It
-originates at the VD_3V3B regulator and is the primary rail that
-supports all of the peripherals on the board. This rail also supplies
-the VDDIO rails which set the voltage levels for all of the I/O signals
-between the processor and the **LAN8710A**.
-
-VDD_PHYA Rail
-*******************
-
-A filtered version of VDD_3V3B rail is connected to the VDD rails of the
-LAN8710 and the termination resistors on the Ethernet signals. It is
-labeled as *VDD_PHYA*. The filtering inductor helps block transients
-that may be seen on the VDD_3V3B rail.
-
-PHY_VDDCR Rail
-*********************
-
-The *PHY_VDDCR* rail originates inside the LAN8710A. Filter and bypass
-capacitors are used to filter the rail. Only circuitry inside the
-LAN8710A uses this rail.
-
-SYS_RESET
-******************
-
-The reset of the LAN8710A is controlled via the *SYS_RESETn* signal, the
-main board reset line.
-
-Clock Signals
-*********************
-
-A crystal is used to create the clock for the LAN8710A. The processor
-uses the *RMII_RXCLK* signal to provide the clocking for the data
-between the processor and the LAN8710A.
-
-.. _lan8710a-mode-pins:
-
-LAN8710A Mode Pins
-*********************
-
-There are mode pins on the LAN8710A that sets the operational mode for
-the PHY when coming out of reset. These signals are also used to
-communicate between the processor and the LAN8710A. As a result, these
-signals can be driven by the processor which can cause the PHY not to be
-initialized correctly. To ensure that this does not happen, three low
-value pull up resistors are used. *Figure 43* below shows the three mode
-pin resistors.
-
-.. _figure-43,Figure 43:
-
-.. figure:: media/image97.png
- :width: 400px
- :align: center
- :alt: Figure 43. Ethernet PHY Mode Pins
-
- Fig-43: Ethernet PHY Mode Pins
-
-This will set the mode to be 111, which enables all modes and enables
-auto-negotiation.
-
-.. _hdmi-interface-1:
-
-Display Port Interface
------------------------------------
-
-BeagleBone AI-64 has an onboard Display Port framer that converts the LCD
-signals and audio signals to drive a Display Port monitor. The design uses the on chip
-internal Display Port Framer.
-
-The following sections provide more detail into the design of this
-interface.
-
-.. _supported-resolutions:
-
-Supported Resolutions
-****************************
-
-The maximum resolution supported by BeagleBone AI-64 is 1280x1024 @
-60Hz. *Table 9* below shows the supported resolutions. Not all
-resolutions may work on all monitors, but these have been tested and
-shown to work on at least one monitor. EDID is supported on the
-BeagleBone AI-64. Based on the EDID reading from the connected monitor,
-the highest compatible resolution is selected.
-
-.Table 9. HDMI Supported Monitor Adapter Resolutions
-[cols"4,1",options"header",]
-
-.. list-table:: Table 9. HDMI Supported Monitor Adapter Resolutions
- :header-rows: 1
-
- * - RESOLUTION
- - AUDIO
- * - 800 x 600 @60Hz
- -
- * - 800 x 600 @56Hz
- -
- * - 640 x 480 @75Hz
- -
- * - 640 x 480 @60Hz
- - YES
- * - 720 x 400 @70Hz
- -
- * - 1280 x 1024 @75Hz
- -
- * - 1024 x 768 @75Hz
- -
- * - 1024 x 768 @70Hz
- -
- * - 1024 x 768 @60Hz
- -
- * - 800 x 600 @75Hz
- -
- * - 800 x 600 @72Hz
- -
- * - 720 x 480 @60Hz
- - YES
- * - 1280 x 720 @60Hz
- - YES
- * - 1920x1080 @24Hz
- - YES
-
-
-.. note ::
-
- The updated software image used on the Rev A5B and later boards added support for 1920x1080@24HZ.
-
-
-Audio is limited to CEA supported resolutions. LCD panels only activate
-the audio in CEA modes. This is a function of the specification and is
-not something that can be fixed on the board via a hardware change or a
-software change.
-
-.. _hdmi-framer:
-
-Display Port Framer
-*********************************************
-
-insert processor Display Port framer doc here
-
-.. _hdmi-video-processor-interface:
-
-Display Port Video Processor Interface
-*********************************************
-
-insert processor Display Port V-interface doc here
-
-.. _hdmi-control-processor-interface:
-
-Display Port Control Processor Interface
-*********************************************
-
-insert processor Display Port C-interface doc here
-
-.. _interrupt-signal:
-
-Interrupt Signal
-*********************************************
-
-insert processor Display Port interrupt doc here
-
-.. _audio-interface:
-
-Audio Interface
-*********************************************
-
-insert processor Display Port audio doc here
-
-.. _power-connections:
-
-Power Connections
-*********************************************
-
-guesing this doesn’t exist on this device
-
-.. _hdmi-connector-interface:
-
-miniDP Connector Interface
-*********************************************
-
-insert processor Mini Display Port connector doc here
-
-.. _usb-host:
-
-USB Host
------------------------------------
-
-The board is equipped with a single USB host interface accessible from a
-single USB Type A female connector. :ref:`figure-48` is the design of the USB
-Host circuitry.
-
-.. _figure-48,Figure 48:
-
-.. figure:: media/image66.png
- :width: 400px
- :align: center
- :alt: Figure 48. USB Host circuit
-
- Fig-48: USB Host circuit
-
-.. _power-switch:
-
-Power Switch
-*********************************************
-
-*U8* is a switch that allows the power to the connector to be turned on
-or off by the processor. It also has an over current detection that can
-alert the processor if the current gets too high via the**USB1_OC**
-signal. The power is controlled by the *USB1_DRVBUS* signal from the
-processor.
-
-.. _esd-protection:
-
-ESD Protection
-*********************************************
-
-*U9* is the ESD protection for the signals that go to the connector.
-
-.. _filter-options:
-
-Filter Options
-*********************************************
-
-*FB7* and **FB8** were added to assist in passing the FCC emissions test.
-The *USB1_VBUS* signal is used by the processor to detect that the 5V is
-present on the connector. *FB7* is populated and *FB8* is replaced with
-a .1 ohm resistor.
-
-.. _pru-icss:
-
-PRU-ICSS
------------------------------------
-
-The PRU-ICSS module is located inside the TDA4VM processor. Access to
-these pins is provided by the expansion headers and is multiplexed with
-other functions on the board. Access is not provided to all of the
-available pins.
-
-All documentation is located at http://git.beagleboard.org/beagleboard/am335x_pru_package
-
-This feature is not supported by Texas Instruments.
-
-.. _pru-icss-features:
-
-PRU-ICSS Features
-*********************************************
-
-The features of the PRU-ICSS include:
-
-Two independent programmable real-time (PRU) cores:
-
-* 32-Bit Load/Store RISC architecture
-* 8K Byte instruction RAM (2K instructions) per core
-* 8K Bytes data RAM per core
-* 12K Bytes shared RAM
-* Operating frequency of 200 MHz
-* PRU operation is little endian similar to ARM processor
-* All memories within PRU-ICSS support parity
-* Includes Interrupt Controller for system event handling
-* Fast I/O interface
-
-*16 input pins and 16 output pins per PRU core. (Not all of these are
-accessible on BeagleBone AI-64).*
-
-.. _pru-icss-block-diagram:
-
-PRU-ICSS Block Diagram
-*****************************
-
-:ref:`figure-49` is a high level block diagram of the PRU-ICSS.
-
-.. _figure-49,Figure 49:
-
-.. figure:: media/image67.png
- :width: 400px
- :align: center
- :alt: PRU-ICSS Block Diagram
-
- PRU-ICSS Block Diagram
-
-.. _pru-icss-pin-access:
-
-PRU-ICSS Pin Access
-*********************************************
-
-Both PRU 0 and PRU1 are accessible from the expansion headers. Some may
-not be useable without first disabling functions on the board like LCD
-for example. Listed below is what ports can be accessed on each PRU.
-
-* 8 outputs or 9 inputs PRU1
-* 13 outputs or 14 inputs
-* UART0_TXD, UART0_RXD, UART0_CTS, UART0_RTS
-
-:ref:`table-11` below shows which PRU-ICSS signals can be accessed on the
-BeagleBone AI-64 and on which connector and pins they are accessible
-from. Some signals are accessible on the same pins.
-
-.. _table-11,Table 11:
-
-.. list-table:: Table 11: PRU0 and PRU1 Access
- :header-rows: 1
-
- * -
- - PIN
- - PROC
- - NAME
- -
- -
- -
- * - P8
- - 11
- - R12
- - GPIO1_13
- -
- - pr1_pru0_pru_r30_15 (Output)
- -
- * -
- - 12
- - T12
- - GPIO1_12
- -
- - pr1_pru0_pru_r30_14 (Output)
- -
- * -
- - 15
- - U13
- - GPIO1_15
- -
- - pr1_pru0_pru_r31_15 (Input)
- -
- * -
- - 16
- - V13
- - GPIO1_14
- -
- - pr1_pru0_pru_r31_14 (Input)
- -
- * -
- - 20
- - V9
- - GPIO1_31
- - pr1_pru1_pru_r30_13 (Output)
- - pr1_pru1_pru_r31_13 (INPUT)
- -
- * -
- - 21
- - U9
- - GPIO1_30
- - pr1_pru1_pru_r30_12 (Output)
- - pr1_pru1_pru_r31_12 (INPUT)
- -
- * -
- - 27
- - U5
- - GPIO2_22
- - pr1_pru1_pru_r30_8 (Output)
- - pr1_pru1_pru_r31_8 (INPUT)
- -
- * -
- - 28
- - V5
- - GPIO2_24
- - pr1_pru1_pru_r30_10 (Output)
- - pr1_pru1_pru_r31_10 (INPUT)
- -
- * -
- - 29
- - R5
- - GPIO2_23
- - pr1_pru1_pru_r30_9 (Output)
- - pr1_pru1_pru_r31_9 (INPUT)
- -
- * -
- - 39
- - T3
- - GPIO2_12
- - pr1_pru1_pru_r30_6 (Output)
- - pr1_pru1_pru_r31_6 (INPUT)
- -
- * -
- - 40
- - T4
- - GPIO2_13
- - pr1_pru1_pru_r30_7 (Output)
- - pr1_pru1_pru_r31_7 (INPUT)
- -
- * -
- - 41
- - T1
- - GPIO2_10
- - pr1_pru1_pru_r30_4 (Output)
- - pr1_pru1_pru_r31_4 (INPUT)
- -
- * -
- - 42
- - T2
- - GPIO2_11
- - pr1_pru1_pru_r30_5 (Output)
- - pr1_pru1_pru_r31_5 (INPUT)
- -
- * -
- - 43
- - R3
- - GPIO2_8
- - pr1_pru1_pru_r30_2 (Output)
- - pr1_pru1_pru_r31_2 (INPUT)
- -
- * -
- - 44
- - R4
- - GPIO2_9
- - pr1_pru1_pru_r30_3 (Output)
- - pr1_pru1_pru_r31_3 (INPUT)
- -
- * -
- - 45
- - R1
- - GPIO2_6
- - pr1_pru1_pru_r30_0 (Output)
- - pr1_pru1_pru_r31_0 (INPUT)
- -
- * -
- - 46
- - R2
- - GPIO2_7
- - pr1_pru1_pru_r30_1 (Output)
- - pr1_pru1_pru_r31_1 (INPUT)
- -
- * -
- -
- -
- -
- -
- -
- -
- * - P9
- - 17
- - A16
- - I2C1_SCL
- - pr1_uart0_txd
- -
- -
- * -
- - 18
- - B16
- - I2C1_SDA
- - pr1_uart0_rxd
- -
- -
- * -
- - 19
- - D17
- - I2C2_SCL
- - pr1_uart0_rts_n
- -
- -
- * -
- - 20
- - D18
- - I2C2_SDA
- - pr1_uart0_cts_n
- -
- -
- * -
- - 21
- - B17
- - UART2_TXD
- - pr1_uart0_rts_n
- -
- -
- * -
- - 22
- - A17
- - UART2_RXD
- - pr1_uart0_cts_n
- -
- -
- * -
- - 24
- - D15
- - UART1_TXD
- - pr1_uart0_txd
- - pr1_pru0_pru_r31_16 (Input)
- -
- * -
- - 25
- - A14
- - GPIO3_21footnote:[GPIO3_21 is also the 24.576MHZ clock input to the processor to enable HDMI audio. To use this pin the oscillator must be disabled.]
- - pr1_pru0_pru_r30_5 (Output)
- - pr1_pru0_pru_r31_5 (Input)
- -
- * -
- - 26
- - D16
- - UART1_RXD
- - pr1_uart0_rxd
- - pr1_pru1_pru_r31_16
- -
- * -
- - 27
- - C13
- - GPIO3_19
- - pr1_pru0_pru_r30_7 (Output)
- - pr1_pru0_pru_r31_7 (Input)
- -
- * -
- - 28
- - C12
- - SPI1_CS0
- - eCAP2_in_PWM2_out
- - pr1_pru0_pru_r30_3 (Output)
- - pr1_pru0_pru_r31_3 (Input)
- * -
- - 29
- - B13
- - SPI1_D0
- - pr1_pru0_pru_r30_1 (Output)
- - pr1_pru0_pru_r31_1 (Input)
- -
- * -
- - 30
- - D12
- - SPI1_D1
- - pr1_pru0_pru_r30_2 (Output)
- - pr1_pru0_pru_r31_2 (Input)
- -
- * -
- - 31
- - A13
- - SPI1_SCLK
- - pr1_pru0_pru_r30_0 (Output)
- - pr1_pru0_pru_r31_0 (Input)
- -
-
-
diff --git a/boards/beaglebone/ai-64/ch07.rst b/boards/beaglebone/ai-64/ch07.rst
deleted file mode 100644
index 699101b182ef40081e0b50924ddac34b4a858e59..0000000000000000000000000000000000000000
--- a/boards/beaglebone/ai-64/ch07.rst
+++ /dev/null
@@ -1,394 +0,0 @@
-:orphan:
-
-.. _connectors:
-
-Connectors
-#############
-
-This section describes each of the connectors on the board.
-
-.. _section-7-1,Section 7.1 Expansion Connectors:
-
-Expansion Connectors
------------------------------
-
-The expansion interface on the board is comprised of two 46 pin
-connectors. All signals on the expansion headers are 3.3V unless
-otherwise indicated.
-
-.. note ::
-
- Do not connect 5V logic level signals to these pins or the board will be damaged.
-
-.. note ::
-
- DO NOT APPLY VOLTAGE TO ANY I/O PIN WHEN POWER IS NOT SUPPLIED TO THE BOARD. IT WILL DAMAGE THE PROCESSOR AND VOID THE WARRANTY.
- NO PINS ARE TO BE DRIVEN UNTIL AFTER THE SYS RESET LINE GOES HIGH.
-
-:ref:`figure-50` shows the location of the expansion connectors.
-
-.. _figure-50,Figure 50:
-
-.. figure:: media/image68.jpg
- :width: 400px
- :align: center
- :alt: Figure 50. Expansion Connector Location
-
- Fig-50: Expansion Connector Location
-
-The location and spacing of the expansion headers are the same as on the BeagleBone Black.
-
-.. _connector-p8-and-p9:
-
-Connector P8 and P9
-**************************
-
-:ref:`table-12` shows the pin bindings for **P8** and **P9** expansion headers. Signals
-can be connected to theese connectors based on setting the pin mux on the
-processor, but this is the default settings on power up. The SW is
-responsible for setting the default function of each pin. There are some
-signals that have not been listed here. Refer to the processor
-documentation for more information on these pins and detailed
-descriptions of all of the pins listed. In some cases there may not be
-enough signals to complete a group of signals that may be required to
-implement a total interface.
-
-The *BALL NUMBER* Identifier is the pin number in the processor documentation.
-
-The *PIN No.* column is the pin number on the expansion header.
-
-The *ADDRESS* column is the pin CONFIGURATION address??? for each pin.
-
-The *MUXMODE[14:0] SETTINGS* are the possible pin configurations.
-
-
-*NOTE: DO NOT APPLY VOLTAGE TO ANY I/O PIN WHEN POWER IS NOT SUPPLIED TO
-THE BOARD. IT WILL DAMAGE THE PROCESSOR AND VOID THE WARRANTY.*
-
-*NO PINS ARE TO BE DRIVEN UNTIL AFTER THE SYS_RESET LINE GOES HIGH.*
-
-
-..
- #TODO# this is a total mess!
- | *PIN No.* | *ADDRESS* | *REGISTER NAME* | *BALL NUMBER* | *MUXMODE[14:0] SETTINGS* |||||||||||||||
- | *PIN No.* | *ADDRESS* | *REGISTER NAME* | *BALL NUMBER* | *0* | *1* | *2* | *3* | *4* | *5* | *6* | *7* | *8* | *9* | *10* | *11* | *12* | *13* | *14* | *Bootstrap* |
- | P8_03 | 0x00011C054 | PADCONFIG21 | AH21 | PRG1_PRU0_GPO19 | PRG1_PRU0_GPI19 | PRG1_IEP0_EDC_SYNC_OUT0 | PRG1_PWM0_TZ_OUT | | RMII5_TXD0 | MCAN6_TX | GPIO0_20 | | | VOUT0_EXTPCLKIN | VPFE0_PCLK | MCASP4_AFSX | | |
- |P8_04 |0x00011C0C4 | PADCONFIG49 | AC29 | PRG0_PRU0_GPO5 | PRG0_PRU0_GPI5 | | PRG0_PWM3_B2 | | RMII3_TXD0 | | GPIO0_48 | GPMC0_AD0 | | | | MCASP0_AXR3 | | | BOOTMODE2
- |P8_05 |0x00011C088 | PADCONFIG34 | AH25 | PRG1_PRU1_GPO12 | PRG1_PRU1_GPI12 | PRG1_RGMII2_TD1 | PRG1_PWM1_A0 | RGMII2_TD1 | | MCAN7_TX | GPIO0_33 | RGMII8_TD1 | | VOUT0_DATA12 | | MCASP9_AFSX | | |
- |P8_06 |0x00011C08C | PADCONFIG35 | AG25 | PRG1_PRU1_GPO13 | PRG1_PRU1_GPI13 | PRG1_RGMII2_TD2 | PRG1_PWM1_B0 | RGMII2_TD2 | | MCAN7_RX | GPIO0_34 | RGMII8_TD2 | | VOUT0_DATA13 | VPFE0_DATA8 | MCASP9_AXR0 | MCASP4_ACLKR | |
- |P8_07 |0x00011C03C | PADCONFIG15 | AD24 | PRG1_PRU0_GPO14 | PRG1_PRU0_GPI14 | PRG1_RGMII1_TD3 | PRG1_PWM0_A1 | RGMII1_TD3 | | MCAN5_RX | GPIO0_15 | | RGMII7_TD3 | VOUT0_DATA19 | VPFE0_DATA3 | MCASP7_AXR1 | | |
- |P8_08 |0x00011C038 | PADCONFIG14 | AG24 | PRG1_PRU0_GPO13 | PRG1_PRU0_GPI13 | PRG1_RGMII1_TD2 | PRG1_PWM0_B0 | RGMII1_TD2 | | MCAN5_TX | GPIO0_14 | | RGMII7_TD2 | VOUT0_DATA18 | VPFE0_DATA2 | MCASP7_AXR0 | | |
- |P8_09 |0x00011C044 | PADCONFIG17 | AE24 | PRG1_PRU0_GPO16 | PRG1_PRU0_GPI16 | PRG1_RGMII1_TXC | PRG1_PWM0_A2 | RGMII1_TXC | | MCAN6_RX | GPIO0_17 | | RGMII7_TXC | VOUT0_DATA21 | VPFE0_DATA5 | MCASP7_AXR3 | MCASP7_AFSR | |
- |P8_10 |0x00011C040 | PADCONFIG16 | AC24 | PRG1_PRU0_GPO15 | PRG1_PRU0_GPI15 | PRG1_RGMII1_TX_CTL | PRG1_PWM0_B1 | RGMII1_TX_CTL | | MCAN6_TX | GPIO0_16 | | RGMII7_TX_CTL | VOUT0_DATA20 | VPFE0_DATA4 | MCASP7_AXR2 | MCASP7_ACLKR | |
- |P8_11 |0x00011C0F4 | PADCONFIG61 | AB24 | PRG0_PRU0_GPO17 | PRG0_PRU0_GPI17 | PRG0_IEP0_EDC_SYNC_OUT1 | PRG0_PWM0_B2 | PRG0_ECAP0_SYNC_OUT | | | GPIO0_60 | GPMC0_AD5 | OBSCLK1 | | | MCASP0_AXR13 | | | BOOTMODE7
- |P8_12 |0x00011C0F0 | PADCONFIG60 | AH28 | PRG0_PRU0_GPO16 | PRG0_PRU0_GPI16 | PRG0_RGMII1_TXC | PRG0_PWM0_A2 | RGMII3_TXC | | | GPIO0_59 | | | DSS_FSYNC1 | | MCASP0_AXR12 | | |
- |P8_13 |0x00011C168 | PADCONFIG90 | V27 | RGMII5_TD1 | RMII7_TXD1 | I2C3_SCL | | VOUT1_DATA4 | TRC_DATA2 | EHRPWM0_B | GPIO0_89 | GPMC0_A5 | | | | MCASP11_ACLKX | | |
- |P8_14 |0x00011C130 | PADCONFIG76 | AF27 | PRG0_PRU1_GPO12 | PRG0_PRU1_GPI12 | PRG0_RGMII2_TD1 | PRG0_PWM1_A0 | RGMII4_TD1 | | | GPIO0_75 | | | | | MCASP1_AXR8 | | UART8_CTSn |
- |P8_15 |0x00011C0F8 | PADCONFIG62 | AB29 | PRG0_PRU0_GPO18 | PRG0_PRU0_GPI18 | PRG0_IEP0_EDC_LATCH_IN0 | PRG0_PWM0_TZ_IN | PRG0_ECAP0_IN_APWM_OUT | | | GPIO0_61 | GPMC0_AD6 | | | | MCASP0_AXR14 | | |
- |P8_16 |0x00011C0FC | PADCONFIG63 | AB28 | PRG0_PRU0_GPO19 | PRG0_PRU0_GPI19 | PRG0_IEP0_EDC_SYNC_OUT0 | PRG0_PWM0_TZ_OUT | | | | GPIO0_62 | GPMC0_AD7 | | | | MCASP0_AXR15 | | |
- |P8_17 |0x00011C00C | PADCONFIG3 | AF22 | PRG1_PRU0_GPO2 | PRG1_PRU0_GPI2 | PRG1_RGMII1_RD2 | PRG1_PWM2_A0 | RGMII1_RD2 | RMII1_CRS_DV | | GPIO0_3 | GPMC0_WAIT1 | RGMII7_RD2 | | | MCASP6_AXR0 | | UART1_RXD |
- |P8_18 |0x00011C010 | PADCONFIG4 | AJ23 | PRG1_PRU0_GPO3 | PRG1_PRU0_GPI3 | PRG1_RGMII1_RD3 | PRG1_PWM3_A2 | RGMII1_RD3 | RMII1_RX_ER | | GPIO0_4 | GPMC0_DIR | RGMII7_RD3 | | | MCASP6_AXR1 | | UART1_TXD |
- |P8_19 |0x00011C164 | PADCONFIG89 | V29 | RGMII5_TD2 | UART3_TXD | | SYNC3_OUT | VOUT1_DATA3 | TRC_DATA1 | EHRPWM0_A | GPIO0_88 | GPMC0_A4 | | | | MCASP10_AXR1 | | |
- |P8_20 |0x00011C134 | PADCONFIG77 | AF26 | PRG0_PRU1_GPO13 | PRG0_PRU1_GPI13 | PRG0_RGMII2_TD2 | PRG0_PWM1_B0 | RGMII4_TD2 | | | GPIO0_76 | | | | | MCASP1_AXR9 | | UART8_RTSn |
- |P8_21 |0x00011C07C | PADCONFIG31 | AF21 | PRG1_PRU1_GPO9 | PRG1_PRU1_GPI9 | PRG1_UART0_RXD | | SPI6_CS3 | RMII6_RXD1 | MCAN8_TX | GPIO0_30 | GPMC0_CSn0 | PRG1_IEP0_EDIO_DATA_IN_OUT30 | VOUT0_DATA9 | | MCASP4_AXR3 | | |
- |P8_22 |0x00011C014 | PADCONFIG5 | AH23 | PRG1_PRU0_GPO4 | PRG1_PRU0_GPI4 | PRG1_RGMII1_RX_CTL | PRG1_PWM2_B0 | RGMII1_RX_CTL | RMII1_TXD0 | | GPIO0_5 | GPMC0_CSn2 | RGMII7_RX_CTL | | | MCASP6_AXR2 | MCASP6_ACLKR | UART2_RXD |
- |P8_23 |0x00011C080 | PADCONFIG32 | AB23 | PRG1_PRU1_GPO10 | PRG1_PRU1_GPI10 | PRG1_UART0_TXD | PRG1_PWM2_TZ_IN | | RMII6_CRS_DV | MCAN8_RX | GPIO0_31 | GPMC0_CLKOUT | PRG1_IEP0_EDIO_DATA_IN_OUT31 | VOUT0_DATA10 | GPMC0_FCLK_MUX | MCASP5_ACLKX | | |
- |P8_24 |0x00011C018 | PADCONFIG6 | AD20 | PRG1_PRU0_GPO5 | PRG1_PRU0_GPI5 | | PRG1_PWM3_B2 | | RMII1_TX_EN | | GPIO0_6 | GPMC0_WEn | | | | MCASP3_AXR0 | | | BOOTMODE0
- |P8_25 |0x00011C090 | PADCONFIG36 | AH26 | PRG1_PRU1_GPO14 | PRG1_PRU1_GPI14 | PRG1_RGMII2_TD3 | PRG1_PWM1_A1 | RGMII2_TD3 | | MCAN8_TX | GPIO0_35 | RGMII8_TD3 | | VOUT0_DATA14 | | MCASP9_AXR1 | MCASP4_AFSR | |
- |P8_26 |0x00011C0D0 | PADCONFIG52 | AC27 | PRG0_PRU0_GPO8 | PRG0_PRU0_GPI8 | | PRG0_PWM2_A1 | | | MCAN9_RX | GPIO0_51 | GPMC0_AD2 | | | | MCASP0_AXR6 | | UART6_RXD |
- |P8_27 |0x00011C120 | PADCONFIG72 | AA28 | PRG0_PRU1_GPO8 | PRG0_PRU1_GPI8 | | PRG0_PWM2_TZ_OUT | | | MCAN11_RX | GPIO0_71 | GPMC0_AD10 | | | | MCASP1_AFSX | | |
- |P8_28 |0x00011C124 | PADCONFIG73 | Y24 | PRG0_PRU1_GPO9 | PRG0_PRU1_GPI9 | PRG0_UART0_RXD | | SPI3_CS3 | | PRG0_IEP0_EDIO_DATA_IN_OUT30 | GPIO0_72 | GPMC0_AD11 | | DSS_FSYNC3 | | MCASP1_AXR5 | | UART8_RXD |
- |P8_29 |0x00011C128 | PADCONFIG74 | AA25 | PRG0_PRU1_GPO10 | PRG0_PRU1_GPI10 | PRG0_UART0_TXD | PRG0_PWM2_TZ_IN | | | PRG0_IEP0_EDIO_DATA_IN_OUT31 | GPIO0_73 | GPMC0_AD12 | CLKOUT | | | MCASP1_AXR6 | | UART8_TXD |
- |P8_30 |0x00011C12C | PADCONFIG75 | AG26 | PRG0_PRU1_GPO11 | PRG0_PRU1_GPI11 | PRG0_RGMII2_TD0 | | RGMII4_TD0 | RMII4_TX_EN | | GPIO0_74 | GPMC0_A26 | | | | MCASP1_AXR7 | | |
- |P8_31A |0x00011C084 | PADCONFIG33 | AJ25 | PRG1_PRU1_GPO11 | PRG1_PRU1_GPI11 | PRG1_RGMII2_TD0 | | RGMII2_TD0 | RMII2_TX_EN | | GPIO0_32 | RGMII8_TD0 | EQEP1_I | VOUT0_DATA11 | | MCASP9_ACLKX | | |
- |P8_31B |0x00011C100 | PADCONFIG64 | AE29 | PRG0_PRU1_GPO0 | PRG0_PRU1_GPI0 | PRG0_RGMII2_RD0 | | RGMII4_RD0 | RMII4_RXD0 | | GPIO0_63 | UART4_CTSn | | | | MCASP1_AXR0 | | UART5_RXD |
- |P8_32A |0x00011C06C | PADCONFIG27 | AG21 | PRG1_PRU1_GPO5 | PRG1_PRU1_GPI5 | | | | RMII5_TX_EN | MCAN6_RX | GPIO0_26 | GPMC0_WPn | EQEP1_S | VOUT0_DATA5 | | MCASP4_AXR0 | | TIMER_IO4 |
- |P8_32B |0x00011C104 | PADCONFIG65 | AD28 | PRG0_PRU1_GPO1 | PRG0_PRU1_GPI1 | PRG0_RGMII2_RD1 | | RGMII4_RD1 | RMII4_RXD1 | | GPIO0_64 | UART4_RTSn | | | | MCASP1_AXR1 | | UART5_TXD |
- |P8_33A |0x00011C068 | PADCONFIG26 | AH24 | PRG1_PRU1_GPO4 | PRG1_PRU1_GPI4 | PRG1_RGMII2_RX_CTL | PRG1_PWM2_B2 | RGMII2_RX_CTL | RMII2_TXD0 | | GPIO0_25 | RGMII8_RX_CTL | EQEP1_B | VOUT0_DATA4 | VPFE0_DATA13 | MCASP8_AXR2 | MCASP8_ACLKR | TIMER_IO3 |
- |P8_33B |0x00011C1C0 | PADCONFIG112 | AA2 | SPI0_CS0 | UART0_RTSn | | | | | | GPIO0_111 | | | | | | | |
- |P8_34 |0x00011C01C | PADCONFIG7 | AD22 | PRG1_PRU0_GPO6 | PRG1_PRU0_GPI6 | PRG1_RGMII1_RXC | PRG1_PWM3_A1 | RGMII1_RXC | RMII1_TXD1 | AUDIO_EXT_REFCLK0 | GPIO0_7 | GPMC0_CSn3 | RGMII7_RXC | | | MCASP6_AXR3 | MCASP6_AFSR | UART2_TXD |
- |P8_35A |0x00011C064 | PADCONFIG25 | AD23 | PRG1_PRU1_GPO3 | PRG1_PRU1_GPI3 | PRG1_RGMII2_RD3 | | RGMII2_RD3 | RMII2_RX_ER | | GPIO0_24 | RGMII8_RD3 | EQEP1_A | VOUT0_DATA3 | VPFE0_WEN | MCASP8_AXR1 | MCASP3_AFSR | TIMER_IO2 |
- |P8_35B |0x00011C1D4 | PADCONFIG117 | Y3 | SPI1_CS0 | UART0_CTSn | | UART5_RXD | | | PRG0_IEP0_EDIO_OUTVALID | GPIO0_116 | PRG0_IEP0_EDC_LATCH_IN0 | | | | | | |
- |P8_36 |0x00011C020 | PADCONFIG8 | AE20 | PRG1_PRU0_GPO7 | PRG1_PRU0_GPI7 | PRG1_IEP0_EDC_LATCH_IN1 | PRG1_PWM3_B1 | | AUDIO_EXT_REFCLK1 | MCAN4_TX | GPIO0_8 | | | | | MCASP3_AXR1 | | |
- |P8_37A |0x00011C1AC | PADCONFIG107 | Y27 | RGMII6_RD2 | UART4_RTSn | | UART5_TXD | | TRC_DATA19 | EHRPWM5_A | GPIO0_106 | GPMC0_A22 | | | | MCASP11_AXR5 | | |
- |P8_37B |0x00011C02C | PADCONFIG11 | AD21 | PRG1_PRU0_GPO10 | PRG1_PRU0_GPI10 | PRG1_UART0_RTSn | PRG1_PWM2_B1 | SPI6_CS2 | RMII5_CRS_DV | | GPIO0_11 | GPMC0_BE0n_CLE | PRG1_IEP0_EDIO_DATA_IN_OUT29 | OBSCLK2 | | MCASP3_AFSX | | |
- |P8_38A |0x00011C1A8 | PADCONFIG106 | Y29 | RGMII6_RD3 | UART4_CTSn | | UART5_RXD | CLKOUT | TRC_DATA18 | EHRPWM_TZn_IN4 | GPIO0_105 | GPMC0_A21 | | | | MCASP11_AXR4 | | |
- |P8_38B |0x00011C024 | PADCONFIG9 | AJ20 | PRG1_PRU0_GPO8 | PRG1_PRU0_GPI8 | | PRG1_PWM2_A1 | | RMII5_RXD0 | MCAN4_RX | GPIO0_9 | GPMC0_OEn_REn | | VOUT0_DATA22 | | MCASP3_AXR2 | | |
- |P8_39 |0x00011C118 | PADCONFIG70 | AC26 | PRG0_PRU1_GPO6 | PRG0_PRU1_GPI6 | PRG0_RGMII2_RXC | | RGMII4_RXC | RMII4_TXD0 | | GPIO0_69 | GPMC0_A25 | | | | MCASP1_AXR3 | | |
- |P8_40 |0x00011C11C | PADCONFIG71 | AA24 | PRG0_PRU1_GPO7 | PRG0_PRU1_GPI7 | PRG0_IEP1_EDC_LATCH_IN1 | | SPI3_CS0 | | MCAN11_TX | GPIO0_70 | GPMC0_AD9 | | | | MCASP1_AXR4 | | UART2_TXD |
- |P8_41 |0x00011C110 | PADCONFIG68 | AD29 | PRG0_PRU1_GPO4 | PRG0_PRU1_GPI4 | PRG0_RGMII2_RX_CTL | PRG0_PWM2_B2 | RGMII4_RX_CTL | RMII4_TXD1 | | GPIO0_67 | GPMC0_A24 | | | | MCASP1_AXR2 | | |
- |P8_42 |0x00011C114 | PADCONFIG69 | AB27 | PRG0_PRU1_GPO5 | PRG0_PRU1_GPI5 | | | | | | GPIO0_68 | GPMC0_AD8 | | | | MCASP1_ACLKX | | | BOOTMODE6
- |P8_43 |0x00011C108 | PADCONFIG66 | AD27 | PRG0_PRU1_GPO2 | PRG0_PRU1_GPI2 | PRG0_RGMII2_RD2 | PRG0_PWM2_A2 | RGMII4_RD2 | RMII4_CRS_DV | | GPIO0_65 | GPMC0_A23 | | | | MCASP1_ACLKR | MCASP1_AXR10 | |
- |P8_44 |0x00011C10C | PADCONFIG67 | AC25 | PRG0_PRU1_GPO3 | PRG0_PRU1_GPI3 | PRG0_RGMII2_RD3 | | RGMII4_RD3 | RMII4_RX_ER | | GPIO0_66 | | | | | MCASP1_AFSR | MCASP1_AXR11 | |
- |P8_45 |0x00011C140 | PADCONFIG80 | AG29 | PRG0_PRU1_GPO16 | PRG0_PRU1_GPI16 | PRG0_RGMII2_TXC | PRG0_PWM1_A2 | RGMII4_TXC | | | GPIO0_79 | | | | | MCASP2_AXR2 | | |
- |P8_46 |0x00011C144 | PADCONFIG81 | Y25 | PRG0_PRU1_GPO17 | PRG0_PRU1_GPI17 | PRG0_IEP1_EDC_SYNC_OUT1 | PRG0_PWM1_B2 | SPI3_CLK | | | GPIO0_80 | GPMC0_AD13 | | | | MCASP2_AXR3 | | | BOOTMODE3
- |P9_11 |0x00011C004 | PADCONFIG1 | AC23 | PRG1_PRU0_GPO0 | PRG1_PRU0_GPI0 | PRG1_RGMII1_RD0 | PRG1_PWM3_A0 | RGMII1_RD0 | RMII1_RXD0 | | GPIO0_1 | GPMC0_BE1n | RGMII7_RD0 | | | MCASP6_ACLKX | | UART0_RXD |
- |P9_12 |0x00011C0B8 | PADCONFIG46 | AE27 | PRG0_PRU0_GPO2 | PRG0_PRU0_GPI2 | PRG0_RGMII1_RD2 | PRG0_PWM2_A0 | RGMII3_RD2 | RMII3_CRS_DV | | GPIO0_45 | UART3_RXD | | | | MCASP0_ACLKR | | |
- |P9_13 |0x00011C008 | PADCONFIG2 | AG22 | PRG1_PRU0_GPO1 | PRG1_PRU0_GPI1 | PRG1_RGMII1_RD1 | PRG1_PWM3_B0 | RGMII1_RD1 | RMII1_RXD1 | | GPIO0_2 | GPMC0_WAIT0 | RGMII7_RD1 | | | MCASP6_AFSX | | UART0_TXD |
- |P9_14 |0x00011C178 | PADCONFIG94 | U27 | RGMII5_RD3 | UART3_CTSn | | UART6_RXD | VOUT1_DATA8 | TRC_DATA6 | EHRPWM2_A | GPIO0_93 | GPMC0_A9 | | | | MCASP11_AXR0 | | |
- |P9_15 |0x00011C0C0 | PADCONFIG48 | AD25 | PRG0_PRU0_GPO4 | PRG0_PRU0_GPI4 | PRG0_RGMII1_RX_CTL | PRG0_PWM2_B0 | RGMII3_RX_CTL | RMII3_TXD1 | | GPIO0_47 | | | | | MCASP0_AXR2 | | |
- |P9_16A |0x00011C17C | PADCONFIG95 | U24 | RGMII5_RD2 | UART3_RTSn | | UART6_TXD | VOUT1_DATA9 | TRC_DATA7 | EHRPWM2_B | GPIO0_94 | GPMC0_A10 | | | | MCASP11_AXR1 | | |
- |P9_16B |0x00011C1DC | PADCONFIG119 | Y1 | SPI1_CLK | UART5_CTSn | I2C4_SDA | UART2_RXD | | | | GPIO0_118 | PRG0_IEP0_EDC_SYNC_OUT0 | | | | | | |
- |P9_17A |0x00011C074 | PADCONFIG29 | AC21 | PRG1_PRU1_GPO7 | PRG1_PRU1_GPI7 | PRG1_IEP1_EDC_LATCH_IN1 | | SPI6_CS0 | RMII6_RX_ER | MCAN7_TX | GPIO0_28 | | | VOUT0_DATA7 | VPFE0_DATA15 | MCASP4_AXR1 | | UART3_TXD |
- |P9_17B |0x00011C1D0 | PADCONFIG116 | AA3 | SPI0_D1 | | I2C6_SCL | | | | | GPIO0_115 | | | | | | | |
- |P9_18A |0x00011C0A4 | PADCONFIG41 | AH22 | PRG1_PRU1_GPO19 | PRG1_PRU1_GPI19 | PRG1_IEP1_EDC_SYNC_OUT0 | PRG1_PWM1_TZ_OUT | SPI6_D1 | RMII6_TXD1 | PRG1_ECAP0_IN_APWM_OUT | GPIO0_40 | | | VOUT0_PCLK | | MCASP5_AXR1 | | |
- |P9_18B |0x00011C1E4 | PADCONFIG121 | Y2 | SPI1_D1 | | I2C6_SDA | | | | | GPIO0_120 | PRG0_IEP1_EDC_SYNC_OUT0 | | | | | | |
- |P9_19A |0x00011C208 | PADCONFIG130 | W5 | MCAN0_RX | | | | I2C2_SCL | | | GPIO1_1 | | | | | | | |
- |P9_19B |0x00011C13C | PADCONFIG79 | AF29 | PRG0_PRU1_GPO15 | PRG0_PRU1_GPI15 | PRG0_RGMII2_TX_CTL | PRG0_PWM1_B1 | RGMII4_TX_CTL | | | GPIO0_78 | | | | | MCASP2_AXR1 | | UART2_RTSn |
- |P9_20A |0x00011C20C | PADCONFIG131 | W6 | MCAN0_TX | | | | I2C2_SDA | | | GPIO1_2 | | | | | | | |
- |P9_21A |0x00011C0A0 | PADCONFIG40 | AJ22 | PRG1_PRU1_GPO18 | PRG1_PRU1_GPI18 | PRG1_IEP1_EDC_LATCH_IN0 | PRG1_PWM1_TZ_IN | SPI6_D0 | RMII6_TXD0 | PRG1_ECAP0_SYNC_IN | GPIO0_39 | | VOUT0_VP2_VSYNC | VOUT0_VSYNC | | MCASP5_AXR0 | | VOUT0_VP0_VSYNC |
- |P9_22A |0x00011C09C | PADCONFIG39 | AC22 | PRG1_PRU1_GPO17 | PRG1_PRU1_GPI17 | PRG1_IEP1_EDC_SYNC_OUT1 | PRG1_PWM1_B2 | SPI6_CLK | RMII6_TX_EN | PRG1_ECAP0_SYNC_OUT | GPIO0_38 | | VOUT0_VP2_DE | VOUT0_DE | VPFE0_DATA10 | MCASP5_AFSX | | VOUT0_VP0_DE | BOOTMODE1
- |P9_22B |0x00011C170 | PADCONFIG92 | U29 | RGMII5_TXC | RMII7_TX_EN | I2C6_SCL | | VOUT1_DATA6 | TRC_DATA4 | EHRPWM1_B | GPIO0_91 | GPMC0_A7 | | | | MCASP10_AXR2 | | |
- |P9_23 |0x00011C028 | PADCONFIG10 | AG20 | PRG1_PRU0_GPO9 | PRG1_PRU0_GPI9 | PRG1_UART0_CTSn | PRG1_PWM3_TZ_IN | SPI6_CS1 | RMII5_RXD1 | | GPIO0_10 | GPMC0_ADVn_ALE | PRG1_IEP0_EDIO_DATA_IN_OUT28 | VOUT0_DATA23 | | MCASP3_ACLKX | | |
- |P9_24A |0x00011C034 | PADCONFIG13 | AJ24 | PRG1_PRU0_GPO12 | PRG1_PRU0_GPI12 | PRG1_RGMII1_TD1 | PRG1_PWM0_A0 | RGMII1_TD1 | | MCAN4_RX | GPIO0_13 | | RGMII7_TD1 | VOUT0_DATA17 | VPFE0_DATA1 | MCASP7_AFSX | | |
- |P9_24B |0x00011C1E0 | PADCONFIG120 | Y5 | SPI1_D0 | UART5_RTSn | I2C4_SCL | UART2_TXD | | | | GPIO0_119 | PRG0_IEP1_EDC_LATCH_IN0 | | | | | | |
- |P9_25A |0x00011C200 | PADCONFIG128 | AC4 | UART1_CTSn | MCAN3_RX | | | SPI2_D0 | EQEP0_S | | GPIO0_127 | | | | | | | |
- |P9_25B |0x00011C1A4 | PADCONFIG105 | W26 | RGMII6_RXC | | | AUDIO_EXT_REFCLK2 | VOUT1_DE | TRC_DATA17 | EHRPWM4_B | GPIO0_104 | GPMC0_A20 | VOUT1_VP0_DE | | | MCASP10_AXR7 | | |
- |P9_26A |0x00011C030 | PADCONFIG12 | AF24 | PRG1_PRU0_GPO11 | PRG1_PRU0_GPI11 | PRG1_RGMII1_TD0 | PRG1_PWM3_TZ_OUT | RGMII1_TD0 | | MCAN4_TX | GPIO0_12 | | RGMII7_TD0 | VOUT0_DATA16 | VPFE0_DATA0 | MCASP7_ACLKX | | |
- |P9_27A |0x00011C0BC | PADCONFIG47 | AD26 | PRG0_PRU0_GPO3 | PRG0_PRU0_GPI3 | PRG0_RGMII1_RD3 | PRG0_PWM3_A2 | RGMII3_RD3 | RMII3_RX_ER | | GPIO0_46 | UART3_TXD | | | | MCASP0_AFSR | | |
- |P9_27B |0x00011C1F4 | PADCONFIG125 | AB1 | UART0_RTSn | TIMER_IO7 | SPI0_CS3 | MCAN2_TX | SPI2_CLK | EQEP0_B | | GPIO0_124 | | | | | | | |
- |P9_28A |0x00011C230 | PADCONFIG140 | U2 | ECAP0_IN_APWM_OUT | SYNC0_OUT | CPTS0_RFT_CLK | | SPI2_CS3 | I3C0_SDAPULLEN | SPI7_CS0 | GPIO1_11 | | | | | | | |
- |P9_28B |0x00011C0B0 | PADCONFIG44 | AF28 | PRG0_PRU0_GPO0 | PRG0_PRU0_GPI0 | PRG0_RGMII1_RD0 | PRG0_PWM3_A0 | RGMII3_RD0 | RMII3_RXD1 | | GPIO0_43 | | | | | MCASP0_AXR0 | | |
- |P9_29A |0x00011C0D8 | PADCONFIG54 | AB25 | PRG0_PRU0_GPO10 | PRG0_PRU0_GPI10 | PRG0_UART0_RTSn | PRG0_PWM2_B1 | SPI3_CS2 | PRG0_IEP0_EDIO_DATA_IN_OUT29 | MCAN10_RX | GPIO0_53 | GPMC0_AD4 | | | | MCASP0_AFSX | | |
- |P9_29B |0x00011C23C | PADCONFIG143 | V5 | TIMER_IO1 | ECAP2_IN_APWM_OUT | OBSCLK0 | | | | SPI7_D1 | GPIO1_14 | | | | | | | | BOOTMODE5
- |P9_30A |0x00011C0B4 | PADCONFIG45 | AE28 | PRG0_PRU0_GPO1 | PRG0_PRU0_GPI1 | PRG0_RGMII1_RD1 | PRG0_PWM3_B0 | RGMII3_RD1 | RMII3_RXD0 | | GPIO0_44 | | | | | MCASP0_AXR1 | | |
- |P9_30B |0x00011C238 | PADCONFIG142 | V6 | TIMER_IO0 | ECAP1_IN_APWM_OUT | SYSCLKOUT0 | | | | SPI7_D0 | GPIO1_13 | | | | | | | | BOOTMODE4
- |P9_31A |0x00011C0D4 | PADCONFIG53 | AB26 | PRG0_PRU0_GPO9 | PRG0_PRU0_GPI9 | PRG0_UART0_CTSn | PRG0_PWM3_TZ_IN | SPI3_CS1 | PRG0_IEP0_EDIO_DATA_IN_OUT28 | MCAN10_TX | GPIO0_52 | GPMC0_AD3 | | | | MCASP0_ACLKX | | UART6_TXD |
- |P9_31B |0x00011C234 | PADCONFIG141 | U3 | EXT_REFCLK1 | SYNC1_OUT | | | | | SPI7_CLK | GPIO1_12 | | | | | | | |
- |P9_33A |0x00011C0CC | PADCONFIG51 | AC28 | PRG0_PRU0_GPO7 | PRG0_PRU0_GPI7 | PRG0_IEP0_EDC_LATCH_IN1 | PRG0_PWM3_B1 | PRG0_ECAP0_SYNC_IN | | MCAN9_TX | GPIO0_50 | GPMC0_AD1 | | | | MCASP0_AXR5 | | |
- |P9_33B |0x04301C140 | WKUP_PADCONFIG80 | K24 | MCU_ADC0_AIN4 | | | | | | | | | | | | | | |
- |P9_35A |0x00011C0E0 | PADCONFIG56 | AH27 | PRG0_PRU0_GPO12 | PRG0_PRU0_GPI12 | PRG0_RGMII1_TD1 | PRG0_PWM0_A0 | RGMII3_TD1 | | | GPIO0_55 | | | DSS_FSYNC0 | | MCASP0_AXR8 | | |
- |P9_35B |0x04301C148 | WKUP_PADCONFIG82 | K29 | MCU_ADC0_AIN6 | | | | | | | | | | | | | | |
- |P9_36A |0x00011C0E4 | PADCONFIG57 | AH29 | PRG0_PRU0_GPO13 | PRG0_PRU0_GPI13 | PRG0_RGMII1_TD2 | PRG0_PWM0_B0 | RGMII3_TD2 | | | GPIO0_56 | | | DSS_FSYNC2 | | MCASP0_AXR9 | | |
- |P9_36B |0x04301C144 | WKUP_PADCONFIG81 | K27 | MCU_ADC0_AIN5 | | | | | | | | | | | | | | |
- |P9_37A |0x00011C0E8 | PADCONFIG58 | AG28 | PRG0_PRU0_GPO14 | PRG0_PRU0_GPI14 | PRG0_RGMII1_TD3 | PRG0_PWM0_A1 | RGMII3_TD3 | | | GPIO0_57 | UART4_RXD | | | | MCASP0_AXR10 | | |
- |P9_37B |0x04301C138 | WKUP_PADCONFIG78 | K28 | MCU_ADC0_AIN2 | | | | | | | | | | | | | | |
- |P9_38A |0x00011C0EC | PADCONFIG59 | AG27 | PRG0_PRU0_GPO15 | PRG0_PRU0_GPI15 | PRG0_RGMII1_TX_CTL | PRG0_PWM0_B1 | RGMII3_TX_CTL | | | GPIO0_58 | UART4_TXD | | DSS_FSYNC3 | | MCASP0_AXR11 | | |
- |P9_38B |0x04301C13C | WKUP_PADCONFIG79 | L28 | MCU_ADC0_AIN3 | | | | | | | | | | | | | | |
- |P9_39A |0x04301C130 | WKUP_PADCONFIG76 | K25 | MCU_ADC0_AIN0 | | | | | | | | | | | | | | |
- |P9_39B |0x00011C0DC | PADCONFIG55 | AJ28 | PRG0_PRU0_GPO11 | PRG0_PRU0_GPI11 | PRG0_RGMII1_TD0 | PRG0_PWM3_TZ_OUT | RGMII3_TD0 | | | GPIO0_54 | | CLKOUT | | | MCASP0_AXR7 | | |
- |P9_40A |0x00011C148 | PADCONFIG82 | AA26 | PRG0_PRU1_GPO18 | PRG0_PRU1_GPI18 | PRG0_IEP1_EDC_LATCH_IN0 | PRG0_PWM1_TZ_IN | SPI3_D0 | | MCAN12_TX | GPIO0_81 | GPMC0_AD14 | | | | MCASP2_AFSX | | UART2_RXD |
- |P9_40B |0x04301C134 | WKUP_PADCONFIG77 | K26 | MCU_ADC0_AIN1 | | | | | | | | | | | | | | |
- |P9_41 |0x00011C204 | PADCONFIG129 | AD5 | UART1_RTSn | MCAN3_TX | | | SPI2_D1 | EQEP0_I | | GPIO1_0 | | | | | | | |
- |P9_42A |0x00011C1F0 | PADCONFIG124 | AC2 | UART0_CTSn | TIMER_IO6 | SPI0_CS2 | MCAN2_RX | SPI2_CS0 | EQEP0_A | | GPIO0_123 | | | | | | | |
- |P9_42B |0x00011C04C | PADCONFIG19 | AJ21 | PRG1_PRU0_GPO17 | PRG1_PRU0_GPI17 | PRG1_IEP0_EDC_SYNC_OUT1 | PRG1_PWM0_B2 | | RMII5_TXD1 | MCAN5_TX | GPIO0_18 | | | | VPFE0_DATA6 | MCASP3_AXR3 | | | |
-
-
-.. _power-jack:
-
-Power Jack
-----------------------------
-
-The DC power jack is located next to the RJ45 Ethernet connector as
-shown in :ref:`figure-51`. This uses the same power connector as is used on
-the BeagleBone Black. The connector has a 2.1mm diameter center post
-(5VDC) and a 5.5mm diameter outer dimension on the barrel (GND).
-
-.. _figure-51,Figure 51:
-
-.. figure:: media/image69.jpg
- :width: 400px
- :align: center
- :alt: Figure 51. 5VDC Power Jack
-
- Fig-51: 5VDC Power Jack
-
-The board requires a regulated 5VDC +/-.25V supply at 1A. A higher
-current rating may be needed if capes are plugged into the expansion
-headers. Using a higher current power supply will not damage the board.
-
-.. _usb-client:
-
-USB Client
-----------------------------
-
-The USB Client connector is accessible on the bottom side of the board
-under the row of four LEDs as shown in :ref:`figure-52`. It uses a 5 pin
-miniUSB cable, the same as is used on the BeagleBone Black. The cable
-is provided with the board. The cable can also be used to power the
-board.
-
-.. _figure-52,Figure 52:
-
-.. figure:: media/image71.jpg
- :width: 400px
- :align: center
- :alt: Figure 52. USB Client
-
- Fig-52: USB Client
-
-This port is a USB Client only interface and is intended for connection
-to a PC.
-
-.. _usb-host-1:
-
-USB Host
-----------------------------
-
-There is a single USB Host connector on the board and is shown in
-*Figure 53* below.
-
-.. figure:: media/image71.jpg
- :width: 400px
- :align: center
- :alt: Figure 53. USB Host Connector
-
- Fig-53: USB Host Connector
-
-.. _figure-53.-usb-host-connector:
-
-
-
-The port is USB 2.0 HS compatible and can supply up to 500mA of current.
-If more current or ports is needed, then a HUB can be used.
-
-.. _serial-header:
-
-Serial Header
-----------------------------
-
-Each board has a debug serial interface that can be accessed by using a
-special serial cable that is plugged into the serial header as shown in
-*Figure 54* below.
-
-.. figure:: media/image71.jpg
- :width: 400px
- :align: center
- :alt: Figure 54. Serial Debug Header
-
- Figure 54. Serial Debug Header
-
-.. _figure-54.-serial-debug-header:
-
-Two signals are provided, TX and RX on this connector. The levels on
-these signals are 3.3V. In order to access these signals, a FTDI USB to
-Serial cable is recommended as shown in *Figure 55* below.
-
-.. figure:: media/image73.jpg
- :width: 400px
- :align: center
- :alt: Figure-55
-
-The cable can be purchased from several different places and must be the
-3.3V version TTL-232R-3V3. Information on the cable itself can be found
-direct from FTDI at: `http://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_TTL232R_CABLES.pdf <http://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_TTL-232R_CABLES.pdf>`_
-
-Pin 1 of the cable is the ai-64 wire. That must align with the pin 1 on
-the board which is designated by the white dot next to the connector on
-the board.
-
-Refer to the support WIKI `http://elinux.org/BeagleBoneBlack <http://elinux.org/BeagleBoneBlack>`_ for more sources of this cable and other options that will work.
-
-Table is the pinout of the connector as reflected in the schematic. It
-is the same as the FTDI cable which can be found at `http://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_TTL-232R_CABLES.pdf <http://www.ftdichip.com/Support/Documents/DataSheets/Cables/DS_TTL-232R_CABLES.pdf>`_ with the exception that only three pins are used on the board. The pin numbers are defined in *Table 14*. The signals are from the perspective of the board.
-
-.. _table-14.-j1-serial-header-pins:
-
-.. list-table:: Table 14: J1 Serial Header Pins
- :header-rows: 1
-
- * - PIN NUMBER
- - SIGNAL
- * - *1*
- - Ground
- * - *4*
- - Receive
- * - *5*
- - Transmit
-
-*Figure 56* shows the pin location on the board.
-
-.. figure:: media/image75.jpg
- :width: 400px
- :align: center
- :alt: Fig-56 Serial Header
-
- Fig-56: Serial Header
-
-.. _hdmi:
-
-HDMI
-----------------------------
-
-Access to the HDMI interface is through the HDMI connector that is
-located on the bottom side of the board as shown in *Figure 57* below.
-
-.. figure:: media/image71.jpg
- :width: 400px
- :align: center
- :alt: Figure 57. HDMI Connector
-
- Fig-5: HDMI Connector
-
-.. _figure-57.-hdmi-connector:
-
-The connector is microHDMI connector. This was done due to the space
-limitations we had in finding a place to fit the connector. It requires
-a microHDMI to HDMI cable as shown in *Figure 58* below. The cable can
-be purchased from several different sources.
-
-.. figure:: media/image77.jpg
- :width: 400px
- :align: center
- :alt: Figure 58. HDMI Cable
-
- Figure 58. HDMI Cable
-
-.. _microsd:
-
-microSD
-----------------------------
-
-A microSD connector is located on the back or bottom side of the board
-as shown in *Figure 59* below. The microSD card is not supplied with the
-board.
-
-.. figure:: media/image71.jpg
- :width: 400px
- :align: center
- :alt: Figure 59. microSD Connector
-
- Figure 59. microSD Connector
-
-.. _figure-59.-microsd-connector:
-
-When plugging in the SD card, the writing on the card should be up.
-Align the card with the connector and push to insert. Then release.
-There should be a click and the card will start to eject slightly, but
-it then should latch into the connector. To eject the card, push the SD
-card in and then remove your finger. The SD card will be ejected from
-the connector.
-
-Do not pull the SD card out or you could damage the connector.
-
-.. _ethernet-1:
-
-Ethernet
-----------------------------
-
-The board comes with a single 10/100 Ethernet interface located next to
-the power jack as shown in *Figure 60*.
-
-.. figure:: media/image71.jpg
- :width: 400px
- :align: center
- :alt: Figure 60. Ethernet Connector
-
- Figure 60. Ethernet Connector
-
-The PHY supports AutoMDX which means either a straight or a swap cable
-can be used
-
-.. _jtag-connector:
-
-JTAG Connector
-----------------------------
-
-A place for an optional 20 pin CTI JTAG header is provided on the board
-to facilitate the SW development and debugging of the board by using
-various JTAG emulators. This header is not supplied standard on the
-board. To use this, a connector will need to be soldered onto the board.
-
-If you need the JTAG connector you can solder it on yourself. No other
-components are needed. The connector is made by Samtec and the part
-number is FTR-110-03-G-D-06. You can purchase it from `www.digikey.com <http://www.digikey.com/>`_
diff --git a/boards/beaglebone/ai-64/ch08.rst b/boards/beaglebone/ai-64/ch08.rst
index be8128ab04036007006d10e58b835d8ddec6e45b..446ebd2a138ba0b363461a67b4f6395f1c19902c 100644
--- a/boards/beaglebone/ai-64/ch08.rst
+++ b/boards/beaglebone/ai-64/ch08.rst
@@ -14,7 +14,7 @@ key to ensure proper orientation of the cape. On AI-64 you can see a clear
silkscreen marking for the cape orientation. Most of BeagleBone capes
can be used with your BeagleBone AI-64 also like shown in :ref:`bbai-cape-placement-figure` below.
-.. _bbai-cape-placement-figure, BeagleBone Ai Cape Placement figure:
+.. _bbai-cape-placement-figure:
.. figure:: images/ch08/cape-placement.jpg
:width: 400px
@@ -65,7 +65,7 @@ will also be compatible with BeeagleBone AI-64.
This section is still being worked on, please make sure you have the latest system reference manual (SRM).
-.. todo::
+.. todo
Add BeagleBone AI-64 LCD pins information.
Add BeagleBone AI-64 eMMC pins information.
@@ -87,7 +87,7 @@ The address of the EEPROM will be set via either jumpers or a dipswitch
on each expansion board. :ref:`expansion-board-eeprom-without-write-protect-figure`
below is the design of the EEPROM circuit.
-.. _expansion-board-eeprom-without-write-protect-figure, Expansion board EEPROM without write protect figure:
+.. _expansion-board-eeprom-without-write-protect-figure:
.. figure:: images/ch08/eeprom.png
:width: 400px
@@ -174,7 +174,7 @@ discretion of the cape designer.
VSYS_IO_3V3
-.. _expansion-board-eeprom-with-write-protect-figure, Expansion board EEPROM with write protect figure:
+.. _expansion-board-eeprom-with-write-protect-figure:
.. figure:: images/ch08/eeprom-write-protect.png
:width: 400px
@@ -187,7 +187,7 @@ VSYS_IO_3V3
.. _eeprom-data-format:
EEPROM Data Format
-***************************
+===================
:ref:`expansion-board-eeprom-table`
shows the format of the contents of the expansion board
@@ -198,7 +198,7 @@ by the user when the EEPROM contents are dumped.
*Clean/Update table*
-.. _expansion-board-eeprom-table, Expansion Board EEPROM table:
+.. _expansion-board-eeprom-table:
.. list-table:: Expansion Board EEPROM
:header-rows: 1
@@ -267,9 +267,9 @@ by the user when the EEPROM contents are dumped.
.. _pin-usage:
Pin Usage
-***************************
+==========
-:ref:`eeprom-pin-usage-table`` shows the locations in the EEPROM to set the I/O pin usage for
+:ref:`eeprom-pin-usage-table` shows the locations in the EEPROM to set the I/O pin usage for
the cape. It contains the value to be written to the Pad Control
Registers. Details on this can be found in section *9.2.2* of the
*TDA4VM Technical Reference Manual*, The table is left blank as a
@@ -300,7 +300,7 @@ for the AIN signals.
-.. _eeprom-pin-usage-table, EEPROM Pin Usage table:
+.. _eeprom-pin-usage-table:
.. list-table:: EEPROM Pin Usage
:header-rows: 1
@@ -1450,7 +1450,7 @@ for the AIN signals.
.. _pin-usage-consideration:
Pin Usage Consideration
--------------------------------------------
+========================
This section covers things to watch for when hooking up to certain pins
on the expansion headers.
@@ -1458,7 +1458,7 @@ on the expansion headers.
.. _expansion-connectors-1:
Expansion Connectors
--------------------------------------------
+====================
A combination of male and female headers is used for access to the
expansion headers on the main board. There are three possible mounting
@@ -1474,14 +1474,14 @@ and used for each of the different configurations.
.. _non-stacking-headers-single-cape:
Non-Stacking Headers-Single Cape
-*********************************
+=================================
For non-stacking capes single configurations or where the cape can be
the last board on the stack, the two 46 pin expansion headers use the
same connectors. :ref:`single-expansion-connector-figure` is a picture of
the connector. These are dual row 23 position 2.54mm x 2.54mm connectors.
-.. _single-expansion-connector-figure,Single expansion connector figure:
+.. _single-expansion-connector-figure:
.. figure:: images/ch08/single-expansion-connector.jpg
:width: 400px
@@ -1491,7 +1491,7 @@ the connector. These are dual row 23 position 2.54mm x 2.54mm connectors.
Fig-Single expansion connector
The connector is typically mounted on the bottom side of the board as
-shown in :ref:`single-cape-expansion-connector-figure` . These are very common connectors and should be
+shown in :ref:`single-cape-expansion-connector-figure`. These are very common connectors and should be
easily located. You can also use two single row 23 pin headers for each
of the dual row headers.
@@ -1502,8 +1502,7 @@ of the dual row headers.
Fig-Single cape expansion connector on BeagleBone Proto Cape with EEPROM from onlogic
-.. _single-cape-expansion-connector-figure, Single cape expansion connector figure:
-
+.. _single-cape-expansion-connector-figure:
It is allowed to only populate the pins you need. As this is a
non-stacking configuration, there is no need for all headers to be
@@ -1522,7 +1521,7 @@ amount of the pin that goes past the contact point of the connector on
BeagleBone AI-64
-.. _single-cape-connectors-figure, Single Cape Connectors:
+.. _single-cape-connectors-figure:
.. list-table:: Single Cape Connectors
:header-rows: 1
@@ -1554,13 +1553,13 @@ depth into the connector is sufficient
.. _main-expansion-headers-stacking:
Main Expansion Headers-Stacking
-*********************************
+================================
For stacking configuration, the two 46 pin expansion headers use the
same connectors. :ref:`expansion-connector-figure` is a picture of the
connector. These are dual row 23 position 2.54mm x 2.54mm connectors.
-.. _expansion-connector-figure, Expansion connector figure:
+.. _expansion-connector-figure:
.. figure:: images/ch08/expansion-connector.jpg
:width: 400px
@@ -1571,10 +1570,10 @@ connector. These are dual row 23 position 2.54mm x 2.54mm connectors.
The connector is mounted on the top side of the board with longer tails
to allow insertion into BeagleBone AI-64.
-:ref:`stacked-cape-expansion-connector-figure`` is the
+:ref:`stacked-cape-expansion-connector-figure` is the
connector configuration for the connector.
-.. _stacked-cape-expansion-connector-figure, Stacked cape expansion connector figure:
+.. _stacked-cape-expansion-connector-figure:
.. figure:: images/ch08/can-cape.jpg
:width: 250px
@@ -1598,10 +1597,10 @@ know and they will be added to this document. The first item in **Table
amount of the pin that goes past the contact point of the connector on
BeagleBone AI-64.
-The third part listed in :ref:`stacked-cape-connectors-figure`` will have
+The third part listed in :ref:`stacked-cape-connectors-figure` will have
insertion force issues.
-.. _stacked-cape-connectors-figure, Stacked cape connectors figure:
+.. _stacked-cape-connectors-figure:
.. list-table:: Stacked Cape Connectors
:header-rows: 1
@@ -1634,28 +1633,28 @@ one that has the correct mating depth.
.. _stacked-capes-wsignal-stealing:
Stacked Capes w/Signal Stealing
-*********************************
+================================
-:ref:`stacked-with-signal-stealing-expansion-connector-figure`` is the connector configuration for stackable capes that does
+:ref:`stacked-with-signal-stealing-expansion-connector-figure` is the connector configuration for stackable capes that does
not provide all of the signals upwards for use by other boards. This is
useful if there is an expectation that other boards could interfere with
the operation of your board by exposing those signals for expansion.
This configuration consists of a combination of the stacking and
nonstacking style connectors.
-.. _stacked-with-signal-stealing-expansion-connector-figure, Stacked with signal stealing expansion connector figure:
+.. _stacked-with-signal-stealing-expansion-connector-figure:
.. figure:: images/ch08/stealing-expansion-connector.jpg
:width: 400px
:align: center
:alt: Fig-Stacked with signal stealing expansion connector figure
- Fig: Stacked with signal stealing expansion connector figure
+ Stacked with signal stealing expansion connector figure
.. _retention-force:
Retention Force
-***************************
+================
The length of the pins on the expansion header has a direct relationship
to the amount of force that is used to remove a cape from BeagleBone
@@ -1673,20 +1672,20 @@ consider when selecting a connector and its pin length.
.. _beaglebone-ai-64-female-connectors:
BeagleBone AI-64 Female Connectors
-************************************
+===================================
:ref:`connector-pin-insertion-depth` shows the key measurements used in calculating how much the
pin extends past the contact point on the connector, what we call
overhang.
-.. _connector-pin-insertion-depth, Connector pin insertion depth figure:
+.. _connector-pin-insertion-depth:
.. figure:: images/ch08/berg-stip-insertion.jpg
:width: 400px
:align: center
:alt: Fig:Connector Pin Insertion Depth
- Fig:Connector Pin Insertion Depth
+ Connector Pin Insertion Depth
To calculate the amount of the pin that extends past the Point of
Contact, use the following formula:
@@ -1700,7 +1699,7 @@ than the insertion.
.. _signal-usage:
Signal Usage
------------------------
+=============
Based on the pin muxing capabilities of the processor, each expansion
pin can be configured for different functions. When in the stacking
@@ -1710,7 +1709,7 @@ detected will be used to set the pin muxing of each pin. This will
prevent other modes from being supported on stacked cards and may result
in them being inoperative.
-In :ref:`section-7-1`` of this document, the functions of the pins are defined
+In :ref:`section-7-1` of this document, the functions of the pins are defined
as well as the pin muxing options. Refer to this section for more
information on what each pin is. To simplify things, if you use the
default name as the function for each pin and use those functions, it
@@ -1729,20 +1728,20 @@ BOARD. IT WILL DAMAGE THE PROCESSOR AND VOID THE WARRANTY.*
.. _cape-power:
Cape Power
--------------------------------------------
+===========
This section describes the power rails for the capes and their usage.
.. _main-board-power:
Main Board Power
-***************************
+=================
The :ref:`expansion-header-voltages-table` describes the voltages from the
main board that are available on the expansion connectors and their ratings.
All voltages are supplied by connector**P9**. The current ratings listed are per pin.
-.. _expansion-header-voltages-table, Expansion header voltages figure:
+.. _expansion-header-voltages-table:
.. list-table:: Expansion Voltages
@@ -1794,7 +1793,7 @@ the USB and DC external supplies.
.. _expansion-board-external-power:
Expansion Board External Power
-*******************************
+===============================
A cape can have a jack or terminals to bring in whatever voltages may be
needed by that board. Care should be taken not to let this voltage be
@@ -1823,11 +1822,11 @@ the expansion headers to prevent damage to the board.*
.. _standard-cape-size:
Standard Cape Size
-***************************
+===================
:ref:`cape-board-dimensions-figure` shows the outline of the standard cape. The dimensions are in inches.
-.. _cape-board-dimensions-figure, Cape board dimensions figure:
+.. _cape-board-dimensions-figure:
.. figure:: images/ch08/cape-dimension.jpg
:width: 400px
@@ -1845,7 +1844,7 @@ align it with the notch on the board silkscreen.
.. _extended-cape-size:
Extended Cape Size
-***************************
+===================
Capes larger than the standard board size are also allowed. A good
example would be the new BeagleBone AI-64 robotics cape.
diff --git a/boards/pocketbeagle/original/ch02.rst b/boards/pocketbeagle/original/ch02.rst
index 31f60e74fe5deaf9b9c302a06216f1269ecc4ad6..1c7904f961b0310b62d4364f753c77283a048904 100644
--- a/boards/pocketbeagle/original/ch02.rst
+++ b/boards/pocketbeagle/original/ch02.rst
@@ -14,13 +14,13 @@ Document Change History
.. table:: Change History
- ========+======================================+====================+========
- **Rev** | **Changes** | **Date** | **By**
- ========+======================================+====================+========
- A.x | Production Document | *December 7, 2017* | JK
- --------+--------------------------------------+--------------------+--------
- 0.0.5 | Converted to .rst and gitlab hosting | *July 21, 2022* | DK
- ========+======================================+====================+========
+ +--------+--------------------------------------+--------------------+--------+
+ |**Rev** | **Changes** | **Date** | **By** |
+ +========+======================================+====================+========+
+ |A.x | Production Document | *December 7, 2017* | JK |
+ +--------+--------------------------------------+--------------------+--------+
+ |0.0.5 | Converted to .rst and gitlab hosting | *July 21, 2022* | DK |
+ +--------+--------------------------------------+--------------------+--------+
.. _board_changes:
diff --git a/books/beaglebone-cookbook/01basics/basics.rst b/books/beaglebone-cookbook/01basics/basics.rst
index b85bd045ab1fe60ba6651a9c310c8c4c960f60e8..e60dcd0af2c5c8eeb5f0f22ba2f6fb736904d958 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 1a92078cb45a0772206330d45cb921ecff2c2ca5..6a80812e4fd88c6090f8f1294ef9cd7bcd9de37d 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, 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:
-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 c796ba35bbdd089bf0de0f0f125d2ac637d35321..a4d568098bb7996e3cddfebc077558f365d9f36b 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
* 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 b5fb69abef7b0a2711b1a49776e4882dcb269ee3..eff2f3e05459e6cad4f9ab829862b498625995a8 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 89ff503d37fa6dc721d9c96e1284a56b6f5569a1..a78e2dcf047139473d23b3fd05e7d3f8945b13d5 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 22df18ea064dab4b23928be7100ee4f893b18c71..8c1f61e49b7d59af32e7701fd12b197e4d4e9848 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 7b0966b78ba324c9bc7d0e1104b96856f8fdcdb3..88cf1e101644a87ac8ac3c0a3fedebbb04f9da14 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 a69b133b4a1727a080f67e9e312c4c0aae364d47..4f894ee487a0c7aac7457ac5a407905372fe1491 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 796d056e9b12f3622d70a739bdcdf14805a1016d..0285e96f1bd72caad8ac172a5f70876f405a99bf 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 2e6e6faf9656705176598c701b18a1f84b0114b5..18e1f84cf7ddecb7edd60ea41671f1ccc594a186 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>`_ |
- +-----------------------------------------------------+---------------------------------------------------------------------------+
+ +-----------------------------------------------------+---------------------------------------------------------------------------------------+
diff --git a/books/pru-cookbook/01case/case.rst b/books/pru-cookbook/01case/case.rst
index 8082060ee5bcc66e3c66810087ca20a35deb448f..5f5cbd4427e75a72d89f3c8fc7c38beff29ad000 100644
--- a/books/pru-cookbook/01case/case.rst
+++ b/books/pru-cookbook/01case/case.rst
@@ -19,8 +19,8 @@ operation.
But what if you have a project that needs the flexibility of an OS and the timing
of a microcontroller? This is where the BeagleBoard excels since it has both
-an ARM procssor running Linux and two footnote:[Four if you are on the BeagleBone AI];
-**P**rogrammable **R**eal-Time **U**nits (PRUs).
+an ARM procssor running Linux and two [#]_
+**P**\ rogrammable **R**\ eal-Time **U**\ nits (PRUs).
The PRUs have 32-bit cores which run
independently of the ARM processor, therefore they can
be programmed to respond quickly to inputs and produce very precisely timed
@@ -39,23 +39,25 @@ Here we present:
* `BeagleLogic <https://github.com/abhishek-kakkar/BeagleLogic/wiki>`_
* `NeoPixels -- 5050 RGB LEDs with Integrated Drivers (Falcon Christmas) <http://falconchristmas.com>`_
* `RGB LED Matrix (Falcon Christmas) <http://falconchristmas.com>`_
-* `simpPRU -- A python-like language for programming the PRUs`_ <https://github.com/VedantParanjape/simpPRU>
-.. * `MachineKit <http://www.machinekit.io/>`_
-.. * `ArduPilot <http://ardupilot.org/>, <http://ardupilot.org/dev/docs/beaglepilot.html>`_
-.. * `BeagleScope <https://github.com/ZeekHuge/BeagleScope>`_
+* `simpPRU -- A python-like language for programming the PRUs <https://github.com/VedantParanjape/simpPRU>`_
+* `MachineKit <http://www.machinekit.io/>`_
+* `BeaglePilot <http://ardupilot.org/dev/docs/beaglepilot.html>`_
+* `BeagleScope <https://github.com/ZeekHuge/BeagleScope>`_
The following are resources used in this chapter.
.. admonition:: Resources
- * `Pocket Beagle System Reference Manual https://github.com/beagleboard/pocketbeagle/wiki/System-Reference-Manual#673_PRUICSS_Pin_Access`_
- * `BeagleBone Black P8 Header Table https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP8HeaderTable.pdf`_
- * `BeagleBone Black P9 Header Table https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf`_
- * `BeagleBone AI System Reference Manual https://github.com/beagleboard/beaglebone-ai/wiki/System-Reference-Manual`_
+ * `Pocket Beagle System Reference Manual <https://docs.beagleboard.io/latest/boards/pocketbeagle/original/index.html>`_
+ * `BeagleBone Black P8 Header Table <https://docs.beagleboard.io/latest/boards/beaglebone/black/ch07.html#id2>`_
+ * `P8 Header Table from exploringBB <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP8HeaderTable.pdf>`_
+ * `BeagleBone Black P9 Header Table <https://docs.beagleboard.io/latest/boards/beaglebone/black/ch07.html#id3>`_
+ * `P9 Header Table from exploringBB <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf>`_
+ * `BeagleBone AI System Reference Manual <https://docs.beagleboard.io/latest/boards/beaglebone/ai/index.html>`_
Robotics Control Library
--------------------------
+**************************
Robotics is an embedded application that often requires both an SBC to control the
high-level tasks (such as path planning, line following, communicating with the user)
@@ -65,17 +67,16 @@ to turn, or how to balance in response to an IMU input). The
`robot <https://www.hackster.io/edumip/edumip-13a29c>`_
demonstrates that by using the PRU, the Blue can handle both the high
and low -level tasks without an additional microcontroller. The EduMIP is shown
-in :ref:`<case_blue>`.
+in :ref:`case_blue`.
.. _case_blue:
-Blue balancing
-~~~~~~~~~~~~~~~
-
.. figure:: figures/blue.png
:align: center
:alt: Blue balancing
+ Blue balancing
+
The `Robotics Control Library <http://strawsondesign.com/docs/roboticscape/>`_ is a
package that is already installed on the Beagle
that contains a C library and example/testing programs. It uses the PRU to extend the
@@ -88,14 +89,14 @@ Controlling Eight Servos
*************************
Problem
-~~~~~~~~
+--------
You need to control eight servos, but the Bone doesn't have enough pulse width
modulation (PWM) channels
and you don't want to add hardware.
Solution
-~~~~~~~~~
+---------
The Robotics Control Library provides eight additional PWM channels
via the PRU that can be used out of the box.
@@ -104,7 +105,7 @@ via the PRU that can be used out of the box.
The I/O pins on the Beagles have a mutliplexer that lets you select what I/O
appears on a given pin. The Blue has the mux already configured to to run these
examples. Follow the instructions in
- :ref:`../03details/details.html#details_configure_servos, Configuring Pins for Controlling Servos`
+ :ref:`details_configure_servos`
to configure the pins for the Black and the Pocket.
@@ -138,7 +139,7 @@ The ``-f 10`` says to use a frequency of 10 Hz and the ``-p 1.5`` says to set th
rc_test_servo -c 1 -p 0.0
Discussion
-~~~~~~~~~~~
+------------
The BeagleBone Blue sends these eight outputs to it's servo channels. The others use the pins shown in the
:ref:`case__register_to_pin_table`.
@@ -146,7 +147,7 @@ The BeagleBone Blue sends these eight outputs to it's servo channels. The other
.. _case__register_to_pin_table:
PRU register to pin table
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
.. table::
@@ -172,13 +173,9 @@ PRU register to pin table
You can find these details in the
-`P8 Header Table <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP8HeaderTable.pdf>`_,
-`P9 Header Table <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf>`_,
-`Pocket Beagle System Reference Manual <https://github.com/beagleboard/pocketbeagle/wiki/System-Reference-Manual#673_PRUICSS_Pin_Access>`_
-(Here is a more usable version of the `table <https://docs.google.com/spreadsheets/d/1FRGvYOyW1RiNSEVprvstfJAVeapnASgDXHtxeDOjgqw/edit?usp=sharing>`_.)
-and
-`BeagleBone AI System Reference Manual <https://github.com/beagleboard/beaglebone-ai/wiki/System-Reference-Manual>`_.
-(Here is a more usable version of the `table <https://docs.google.com/spreadsheets/d/1dFSBVem86vAUD7MLXvqdS-N0Efi8_g_O1iTqzql8DAo/edit#gid=0>`_.)
+
+* `Pocket Beagle pinout <https://docs.google.com/spreadsheets/d/1FRGvYOyW1RiNSEVprvstfJAVeapnASgDXHtxeDOjgqw/edit?usp=sharing>`_
+* `BeagleBone AI PRU pins <https://docs.google.com/spreadsheets/d/1dFSBVem86vAUD7MLXvqdS-N0Efi8_g_O1iTqzql8DAo/edit#gid=0>`_
Be default the PRUs are already loaded with the code needed to run the
@@ -187,15 +184,15 @@ servos. All you have to do is run the command.
.. [/opt/source/Robotics_Cape_Installer/pru_firmware/src/pru1-servo.asm]
Controlling Individual Servos
-******************************
+*******************************
Problem
-~~~~~~~~~
+--------
``rc_test_servos`` is nice, but I need to control the servos individually.
Solution
-~~~~~~~~~
+---------
You can modify ``rc_test_servos.c``. You'll find it on the bone online at
https://github.com/beagleboard/librobotcontrol/blob/master/examples/src/rc_test_servos.c.
@@ -208,29 +205,29 @@ Controlling More Than Eight Channels
*************************************
Problem
-~~~~~~~~~~
+--------
I need more than eight PWM channels, or I need less jitter on the off time.
Solution
-~~~~~~~~~~
+---------
This is a more advanced problem and required reprograming the PRUs. See
-:ref:`../05blocks/blocks.html#blocks_pwm, PWM Generator` for an example.
+:ref:`blocks_pwm` for an example.
Reading Hardware Encoders
**************************
Problem
-~~~~~~~~~~
+--------
I want to use four encoders to measure four motors, but I only see hardware for three.
Solution
-~~~~~~~~~~
+---------
-The forth encoder can be implemented on the PRU. If you run ``rc_test_encoders_eqep`` on the Blue, you will see the output of
-encoders E1-E3 which are connected to the eEQP hardware.
+The forth encoder can be implemented on the PRU. If you run ``rc_test_encoders_eqep``
+on the Blue, you will see the output of encoders E1-E3 which are connected to the eEQP hardware.
.. code-block:: bash
@@ -246,7 +243,8 @@ pins shown in :ref:`case_pin_mapping`.
.. _case_pin_mapping:
eQEP to pin mapping
-~~~~~~~~~~~~~~~~~~~~
+--------------------
+
.. table::
+----+--------+-----------+-----------+--------+--------+------------+-------------+
@@ -272,22 +270,23 @@ eQEP to pin mapping
The I/O pins on the Beagles have a mutliplexer that lets you select what I/O
appears on a given pin. The Blue has the mux already configured to to run these
examples. Follow the instructions in
- :ref:`../03details/details.html#details_configure_encoders, Configuring Pins for Controlling Encoders`
+ :ref:`details_configure_encoders`
to configure the pins for the Black and the Pocket.
Reading PRU Encoder
-*********************
+=====================
Problem
-~~~~~~~~
+--------
I want to access the PRU encoder.
Solution
-~~~~~~~~~
+---------
The forth encoder is implemented on the PRU and accessed with `sudo rc_test_encoders_pru`
+
.. note::
This command needs root permission, so the `sudo` is needed.
@@ -309,17 +308,17 @@ Here's what you will see
BeagleLogic -- a 14-channel Logic Analyzer
--------------------------------------------
+********************************************
Problem
-********
+--------
I need a 100Msps, 14-channel logic analyzer
Solution
-*********
+---------
-`BeagleLogic <https://beaglelogic.readthedocs.io/en/latest/>`_ is a 100Msps,
+`BeagleLogic documentation <https://beaglelogic.readthedocs.io/en/latest/>`_ is a 100Msps,
14-channel logic analyzer that runs on the Beagle.
.. admonition:: information
@@ -335,8 +334,8 @@ Solution
https://github.com/abhishek-kakkar/BeagleLogic/wiki
-The quickest solution is to get the `no-setup-required image <https://github.com/abhishek-kakkar/BeagleLogic/wiki/BeagleLogic-%22no-setup-required%22-setup:-Introducing-System-Image!>`_. It points to an older image
-(beaglelogic-stretch-2017-07-13-4gb.img.xz) but should still work.
+The quickest solution is to get the `no-setup-required image <https://github.com/abhishek-kakkar/BeagleLogic/wiki/BeagleLogic-%22no-setup-required%22-setup:-Introducing-System-Image!>`_.
+It points to an older image (beaglelogic-stretch-2017-07-13-4gb.img.xz) but should still work.
If you want to be running a newer image, there are instructions on the site for `installing BeagleLogic <https://beaglelogic.readthedocs.io/en/latest/install.html>`_, but I had to do the additional steps in :ref:`case_installing_beaglelogic`.
@@ -344,10 +343,8 @@ If you want to be running a newer image, there are instructions on the site for
.. _case_installing_beaglelogic:
-Installing BeagleLogic
-~~~~~~~~~~~~~~~~~~~~~~~
-
.. code-block:: bash
+ :caption: Installing BeagleLogic
bone$ *git clone https://github.com/abhishek-kakkar/BeagleLogic*
bone$ *cd BeagleLogic/kernel*
@@ -365,16 +362,15 @@ Then click *Begin Capture* to capture your data, at up to 100 MHz!
.. _case_beaglelogic_capture:
-BeagleLogic Data Capture
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/beaglelogic_capture.png
:align: center
:alt: BeagleLogic Data Capture
+ BeagleLogic Data Capture
+
Discussion
-************
+-----------
BeagleLogic is a complete system that includes firmware for the PRUs,
a kernel module and a web interface that create a powerful 100 MHz
@@ -383,7 +379,7 @@ logic analyzer on the Bone with no additional hardware needed.
.. tip::
If you need buffered inputs, consider
- http://standalone.beaglelogic.net/en/latest/[BeagleLogic Standalone],
+ `BeagleLogic Standalone <http://standalone.beaglelogic.net/en/latest/>`_,
a turnkey Logic Analyzer built on top of BeagleLogic.
@@ -434,10 +430,10 @@ explaining how the PRUs get this type of performance.
NeoPixels -- 5050 RGB LEDs with Integrated Drivers (Falcon Christmas)
-----------------------------------------------------------------------
+***********************************************************************
Problem
-*********
+--------
You have an `Adafruit NeoPixel LED string <http://www.adafruit.com/products/1138>`_,
`Adafruit NeoPixel LED matrix <http://www.adafruit.com/products/1487>`_ or
@@ -448,10 +444,10 @@ and want to light it up.
.. TODO Show how to drive ws2812's with FPP.
Solution
-*********
+---------
If you are driving just one string you can write your own code
-(See :ref:`../05blocks/blocks.adoc#blocks_ws2812, WS2812 Driver`)
+(See :ref:`blocks_ws2812`)
If you plan to drive multiple strings, then consider
Falcon Christmas (`FPP <https://falconchristmas.com/>`_).
FPP can be used to drive both LEDs with an integrated
@@ -460,7 +456,7 @@ set up for the integrated drive and in the next section the no driver LEDs will
show.
Hardware
-*********
+----------
For this setup we'll wire a single string of NeoPixels to the Beagle.
I've attached the black wire on the string to ground on the Beagle
@@ -475,7 +471,7 @@ line 27. It's the 20th entry in the list. You could pick any of the others
if you'd rather.
Software Setup
-***************
+---------------
Assuming the PocketBeagle is attached via the USB cable,
on your host computer browse to <http://192.168.7.2/> and you will see
@@ -483,35 +479,32 @@ on your host computer browse to <http://192.168.7.2/> and you will see
.. _case_fpp_program_control2:
-Falcon Play Program Control
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_program_control.png
:align: center
:alt: Falcon Play Program Control
+ Falcon Play Program Control
+
You can test the display by first setting up the Channel Outputs and then
going to *Display Testing*. :ref:`case_channel_outputs_menu2` shows where to
select Channel Outputs and :ref:`case_channel_outputs2` shows which settings to use.
.. _case_channel_outputs_menu2:
-Selecting Channel Outputs
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_channel_outputs_menu.png
:align: center
:alt: Selecting Channel Outputs
-.. _case_channel_outputs2:
+ Selecting Channel Outputs
-Channel Outputs Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _case_channel_outputs2:
.. figure:: figures/fpp_channel_outputs_strings.png
:align: center
:alt: Channel Outputs Settings
+ Channel Outputs Settings
+
Click on the *Pixel Strings* tab. Earlier we noted that *P1.31* is attached
to port 20. Note that at the bottom of the screen, port 20 has a PIXEL COUNT
of 24. We're telling FPP our string has 24 NeoPixels and they are attached
@@ -524,13 +517,12 @@ Next we need to test the display. Select **Display Testing** shown in
.. _case_display_testing_menu2:
-Selecting Display Testing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_display_testing_menu2.png
:align: center
:alt: Selecting Display Testing
+ Selecting Display Testing
+
Set the *End Channel* to *72*. (72 is 3*24)
Click *Enable Test Mode* and your matrix should light up. Try the different
testing patterns shown in :ref:`case_display_testing2`.
@@ -544,13 +536,12 @@ testing patterns shown in :ref:`case_display_testing2`.
.. _case_display_testing2:
-Display Testing Options
-~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_display_testing2.png
:align: center
:alt: Display Testing Options
+ Display Testing Options
+
You can control the LED string using the E1.31 protocol.
(https://www.doityourselfchristmas.com/wiki/index.php?title=E1.31_(Streaming-ACN)_Protocol)
First configure the input channels by going to Channel Inputs as shown in
@@ -558,54 +549,52 @@ First configure the input channels by going to Channel Inputs as shown in
.. _case_channel_inputs:
-Going to Channel Inputs
-~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_channel_inputs.png
:align: center
:alt: Going to Channel Inputs
+ Going to Channel Inputs
+
Tell it you have 72 LEDs and enable the input as shown in :ref:`case_set_inputs`.
.. _case_set_inputs:
-Setting Channel Inputs
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_inputs_setup2.png
:align: center
:alt: Setting Channel Inputs
+ Setting Channel Inputs
+
Finally go to the Status Page as shown in :ref:`case_status`.
.. _case_status:
-Watching the status
-~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_status.png
:align: center
:alt: Watching Status
+ Watching the status
+
Now run a program on another computer that generated E1.31 packets.
-:ref:`case_1.31_example` is an example python program.
+:ref:`case_e1.31_example` is an example python program.
-.. _cse_e1.31_example:
+.. _case_e1.31_example:
-.e1.31-test.py
-~~~~~~~~~~~~~~
+.. literalinclude:: code/e1.31-test.py
+ :caption: e1.31-test.py -Example of generating packets to control the NeoPixels
+ :linenos:
-:downlod:`e1.31-test.py <code/e1.31-test.py>`- Example of generating packets to control the NeoPixels
+:download:`e1.31-test.py <code/e1.31-test.py>`
.. TODO document the code
.. _case_rgb_matrix:
RGB LED Matrix -- No Integrated Drivers (Falcon Christmas)
------------------------------------------------------------
+************************************************************
Problem
-*************************
+--------
You want to use a RGB LED Matrix display that doesn't have integrated
drivers such as the
@@ -614,20 +603,17 @@ shown in :ref:`case_adfruit_matrix`.
.. _case_adfruit_matrix:
-Adafruit LED Matrix
-~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/ledmatrix.jpg
:align: center
:alt: Adafruit LED Matrix
+ Adafruit LED Matrix
+
Solution
-*************************
+---------
-`Falcon Christmas <http://falconchristmas.com>`_ makes a software package
-called
-`Falcon Player <http://falconchristmas.com/forum/index.php/board,8.0.html>`_ (FPP) which can drive
-such displays.
+`Falcon Christmas <http://falconchristmas.com>`_ makes a software package called
+`Falcon Player <http://falconchristmas.com/forum/index.php/board,8.0.html>`_ (FPP) which can drive such displays.
.. admonition:: information:
@@ -642,7 +628,7 @@ such displays.
http://www.falconchristmas.com/wiki/FPP:FAQ#What_is_FPP.3F
Hardware
-~~~~~~~~~
+---------
The Beagle hardware can be either a BeagleBone Black with the
`Octoscroller Cape <https://oshpark.com/shared_projects/7mSHNZcD>`_, or a
@@ -658,20 +644,18 @@ to full white at the same time you will need at least a 4A supply.
.. _case_pocket:
-Pocket Beagle Driving a P5 RGB LED Matrix via the PocketScroller Cape
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pocketscroller.jpg
:align: center
:alt: Pocket Beagle Driving a P5 RGB LED Matrix via the PocketScroller Cape
+ Pocket Beagle Driving a P5 RGB LED Matrix via the PocketScroller Cape
Software
-~~~~~~~~~~
+---------
The FPP software is most easily installed by downloading the
-`current FPP release <https://github.com/FalconChristmas/fpp/releases/>`_, flashing an SD card and
-booting from it.
+`current FPP release <https://github.com/FalconChristmas/fpp/releases/>`_,
+flashing an SD card and booting from it.
.. tip::
@@ -685,66 +669,60 @@ on your host computer browse to http://192.168.7.2/ and you will see
.. _case_fpp_program_control:
-Falcon Play Program Control
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_program_control.png
:align: center
:alt: Falcon Play Program Control
+ Falcon Play Program Control
+
You can test the display by first setting up the Channel Outputs and then
going to *Display Testing*. :ref:`case_channel_outputs_menu` shows where to
select Channel Outputs and :ref:`case_channel_outputs` shows which settings to use.
.. _case_channel_outputs_menu:
-Selecting Channel Outputs
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_channel_outputs_menu.png
:align: center
:alt: Selecting Channel Outputs
-.. _case_channel_outputs:
+ Selecting Channel Outputs
-Channel Outputs Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _case_channel_outputs:
.. figure:: figures/fpp_channel_outputs.png
:align: center
:alt: Channel Outputs Settings
-Click on the **LED Panels** tab and then the only changes I made was
-to select the **Single Panel Size** to be
-*64x32* and to check the **Enable LED Panel Output**.
+ Channel Outputs Settings
+
+Click on the **LED Panels** tab and then the only changes I made was to select the
+**Single Panel Size** to be *64x32* and to check the **Enable LED Panel Output**.
Next we need to test the display. Select *Display Testing* shown in
:ref:`case_display_testing_menu`.
.. _case_display_testing_menu:
-Selecting Display Testing
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_display_testing_menu.png
:align: center
:alt: Selecting Display Testing
+ Selecting Display Testing
+
Set the **End Channel** to **6144**. (6144 is 3*64*32)
Click **Enable Test Mode** and your matrix should light up. Try the different
testing patterns shown in :ref:`case_display_testing`.
.. _case_display_testing:
-Display Testing Options
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_display_testing.png
:align: center
:alt: Display Testing Options
+ Display Testing Options
+
xLights - Creating Content for the Display
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===========================================
Once you are sure your LED Matrix is working correctly you can program it
with a sequence.
@@ -776,13 +754,12 @@ Run xLights and you'll see :ref:`case_xlights_setup`.
.. _case_xlights_setup:
-xLights Setup
-~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_setup.png
:align: center
:alt: xLights Setup
+ xLights Setup
+
We'll walk you through a simple setup to get an animation to display on the
RGB Matrix. xLights can use a protocol called E1.31 to send information to
the display. Setup xLights by clicking on *Add Ethernet* and entering the values
@@ -790,13 +767,12 @@ shown in :ref:`case_xlights_setup_e1_31`.
.. _case_xlights_setup_e1_31:
-Setting Up E1.31
-~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_setup_e1_31.png
:align: center
:alt: Setting Up E1.31
+ Setting Up E1.31
+
The **IP Address** is the Bone's address as seen from the host computer.
Each LED is one channel, so one RGB LED is three channels. The P5 board
has 3*64*32 or 6144 channels. These are grouped into universes of 512
@@ -809,37 +785,34 @@ Your setup should look like :ref:`case_xlights_setup_done`. Click the
.. _case_xlights_setup_done:
-xLights setup for P5 display
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_setup_done.png
:align: center
:alt: xLights setup for P5 display
+ xLights setup for P5 display
+
Next click on the **Layout** tab. Click on the *Matrix* button as shown in
:ref:`case_xlights_matrix`, then click on the black area where you want your
matrix to appear.
.. _case_xlights_matrix:
-Setting up the Matrix Layout
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_layout.png
:align: center
:alt: Setting up the Matrix Layout
+ Setting up the Matrix Layout
+
:ref:`case_xlights_layout_details` shows the setting to use for the P5 matrix.
.. _case_xlights_layout_details:
-Layout details for P5 matrix
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_layout_details.png
:align: center
:alt: Layout details for P5 matrix
+ Layout details for P5 matrix
+
All I changed was **# Strings**, **Nodes/String**, **Starting Location** and most
importantly, expand **String Properties** and select at **String Type** of
**RGB Nodes**. Above the setting you should see that **Start Chan** is 1 and
@@ -851,19 +824,18 @@ Now click on the *Sequencer* tab and then click on the **New Sequence** button
.. _case_seq_new:
-Starting a new sequence
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_seq_new.png
:align: center
:alt: Starting a new sequence
+ Starting a new sequence
+
Then click on **Animation**, **20fps (50ms)**, and **Quick Start**. Learning how to
do sequences is beyond the scope of this cookbook, however I'll shown you how
do simple sequence just to be sure xLights is talking to the Bone.
Setting Up E1.31 on the Bone
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+==============================
First we need to setup FPP to take input from xLights. Do this by going to
the *Input/Output Setup* menu and selecting *Channel Inputs*. Then
@@ -872,13 +844,12 @@ enter *12* for *Universe Count* and click *set* and you will see
.. _case_inputs_setup:
-E1.31 Inputs
-~~~~~~~~~~~~~
-
.. figure:: figures/fpp_inputs_setup.png
:align: center
:alt: .E1.31 Inputs
+ E1.31 Inputs
+
Click on the **Save** button above the table.
Then go to the **Status/Control** menu and select **Status Page**.
@@ -887,15 +858,14 @@ Then go to the **Status/Control** menu and select **Status Page**.
.. _case_mode_bridge:
-Bridge Mode
-~~~~~~~~~~~~~
-
.. figure:: figures/fpp_mode_bridge.png
:align: center
:alt: Bridge Mode
+ Bridge Mode
+
Testing the xLights Connection
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+===============================
The Bone is now listening for commands from xLights via the E1.31 protocol.
A quick way to verify everything is t o return to xLights and go to the
@@ -903,28 +873,26 @@ A quick way to verify everything is t o return to xLights and go to the
.. _case_xlights_test:
-xLights test page
-~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_test.png
:align: center
:alt: xLights test page
+ xLights test page
+
Click the box under **Select channels...**, click **Output to lights** and
select **Twinkle 50%**. You matrix should have a colorful twinkle pattern
(:ref:`case_xlights_twinkle`).
.. _case_xlights_twinkle:
-xLights Twinkle test pattern
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_twinkle.jpg
:align: center
:alt: xLights Twinkle test pattern
+ xLights Twinkle test pattern
+
A Simple xLights Sequence
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
Now that the xLights to FPP link is tested you can generate a sequence to
play. Close the Test window and click on the **Sequencer** tab. Then drag
@@ -935,19 +903,18 @@ toolbar. Your matrix should now be displaying your effect.
.. _case_seq_drag:
-Drag an effect to the timeline
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/xlights_seq_drag.png
:align: center
:alt: Drag an effect to the timeline
+ Drag an effect to the timeline
+
The setup requires the host computer to send the animation data to the Bone.
The next section shows how to save the sequence and play it on the Bone
standalone.
Saving a Sequence and Playing it Standalone
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================================
In xLights save your sequence by hitting Ctrl-S and giving it a name. I called
mine *fire* since I used a fire effect. Now, switch back to FPP and select
@@ -957,13 +924,12 @@ the *Content Setup* menu and select *File Manager*. Click the black
.. _case_file_manager:
-FPP file manager
-~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_file_manager.png
:align: center
:alt: FPP file manager
+ FPP file manager
+
Once your sequence is uploaded, got to **Content Steup** and select **Playlists**.
Enter you playlist name (I used **fire**) and click **Add**. Then click
**Add a Sequence/Entry** and select **Sequence Only**
@@ -971,13 +937,12 @@ Enter you playlist name (I used **fire**) and click **Add**. Then click
.. _case_playlist:
-Adding a new playlist to FPP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_playlist.png
:align: center
:alt: Adding a new playlist to FPP
+ Adding a new playlist to FPP
+
Be sure to click **Save Playlist** on the right. Now return to
**Status/Control** and **Status Page** and make sure **FPPD Mode:** is set
to **Standalone**. You should see your playlist. Click the **Play**
@@ -985,19 +950,18 @@ button and your sequence will play.
.. _case_playlist_status:
-Adding a new playlist to FPP
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/fpp_playlist_status.png
:align: center
:alt: Playing a playlist
+ Adding a new playlist to FPP
+
The beauty of the PRU is that the Beagle can play a detailed sequence at
20 frames per second and the ARM procossor is only 15% used. The PRUs
are doing all the work.
simpPRU -- A python-like language for programming the PRUs
------------------------------------------------------------
+===========================================================
`simpPRU <https://github.com/VedantParanjape/simpPRU>`_ is a simple, python-like
programming languge designed to make programming the PRUs easy.
@@ -1029,8 +993,9 @@ Now, suppose you wanted to run the
`LED blink <https://simppru.readthedocs.io/en/latest/examples/led_blink/>`_
example which is reproduced here.
-LED Blink (blink.sim)
-~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/blink.sim
+ :caption: LED Blink (blink.sim)
+ :linenos:
:download:`blink.sim <code/blink.sim>`
@@ -1046,7 +1011,7 @@ Just run simppru
Current mode for P1_31 is: pruout
Detected TI AM335x PocketBeagle
---------------------------------
+================================
The +--load+ flag caused the compiled code to be copied to +/lib/firmware+.
To start just do:
@@ -1064,16 +1029,14 @@ Your LED should now be blinking.
Check out the many examples (https://simppru.readthedocs.io/en/latest/examples/led_blink/).
-simpPRU Examples
-~~~~~~~~~~~~~~~~
-
.. figure:: figures/LEDblink.png
:align: center
:alt: simpPRU Examples
+ simpPRU Examples
MachineKit
------------
+===========
`MachineKit <http://www.machinekit.io/>`_ is a platform for machine control
applications. It can control machine tools, robots, or other automated devices. It can control servo
@@ -1120,3 +1083,7 @@ multi-copters, traditional helicopters, fixed wing aircraft and rovers. ArduPilo
colleges and universities around the world.
http://www.machinekit.io/about/
+
+.. rubric:: Footnotes
+
+.. [#] Four if you are on the BeagleBone AI
diff --git a/books/pru-cookbook/02start/start.rst b/books/pru-cookbook/02start/start.rst
index dee7273df5bb6ed688a21156b65cf02433d76667..80ee433d0fb94fda96f35a8d6101e3efacc6306e 100644
--- a/books/pru-cookbook/02start/start.rst
+++ b/books/pru-cookbook/02start/start.rst
@@ -13,15 +13,15 @@ code (and the whole book) on the PRU Cookbook github site:
https://github.com/MarkAYoder/PRUCookbook.
Selecting a Beagle
-====================
+********************
Problem
-----------
+--------
Which Beagle should you use?
Solution
-----------
+---------
http://beagleboard.org/boards lists the many Beagles from which to choose.
Here we'll give examples for the venerable `BeagleBone Black <http://beagleboard.org/black>`_,
@@ -41,13 +41,12 @@ member of the open hardware Beagle family.
.. _start_black:
-BeagleBone Black
-~~~~~~~~~~~~~~~~~
-
.. figure:: figures/product_detail_black_sm.jpg
:align: center
:alt: BeableBone Black
+ BeagleBone Black
+
The Black has:
* AM335x 1GHz ARM® Cortex-A8 processor
@@ -71,13 +70,12 @@ The `Blue <http://beagleboard.org/blue>`_ is a good choice if you are doing robo
.. _start_blue:
-BeagleBone Blue
-~~~~~~~~~~~~~~~~
-
.. figure:: figures/beagle-blue.png
:align: center
:alt: BeagleBone Blue
+ BeagleBone Blue
+
The Blue has everything the Black has except it has no Ethernet or HDMI.
But it also has:
@@ -89,18 +87,17 @@ But it also has:
* User interface: 11 user programmable LEDs, 2 user programmable buttons
In addition you can mount the Blue on the
-https://www.renaissancerobotics.com/eduMIP.html[EduMIP kit] as shown in
+`EduMIP kit <https://www.renaissancerobotics.com/eduMIP.html>`_ as shown in
:ref:`start_edumip` to get a balancing robot.
.. _start_edumip:
-BeagleBone Blue EduMIP Kit
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/edumip.png
:align: center
:alt: BeagleBone Blue EduMIP Kit
+ BeagleBone Blue EduMIP Kit
+
https://www.hackster.io/53815/controlling-edumip-with-ni-labview-2005f8
shows how to assemble the robot and control it from
`LabVIEW <http://www.ni.com/en-us/shop/labview.html>`_.
@@ -114,13 +111,12 @@ compatible with the other Beagles.
.. _start_pocket:
-PocketBeagle
-~~~~~~~~~~~~~
-
.. figure:: figures/PocketBeagle-size-compare-small.jpg
:align: center
:alt: PocketBeagle
+ PocketBeagle
+
The Pocket is based on the same processor as the Black and Blue and has:
* 8 analog inputs
@@ -130,19 +126,18 @@ The Pocket is based on the same processor as the Black and Blue and has:
See http://beagleboard.org/pocket for more details.
BeagleBone AI
-~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
If you want to do deep learning, try the `BeagleBone AI <http://beagleboard.org/ai>`_.
.. _start_ai:
-BeagleBone AI
-~~~~~~~~~~~~~~
-
.. figure:: figures/BB_AI_BeautyAngle_800px.jpg
:align: center
:alt: BeableBone AI
+ BeagleBone AI
+
The AI has:
* Dual Arm® Cortex®-A15 microprocessor subsystem
@@ -163,7 +158,7 @@ The AI has:
Installing the Latest OS on Your Bone
-======================================
+****************************************
Problem
---------
@@ -185,17 +180,16 @@ one for all the other Beagles (
`AM3358 Debian 10.3 2020-04-06 4GB SD IoT <https://debian.beagleboard.org/images/bone-debian-10.3-iot-armhf-2020-04-06-4gb.img.xz>`_).
Download the one for your Beagle.
-Latest Debian images
-~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/latest-images.png
:align: center
:alt: Latest Debian images
+ Latest Debian images
+
It contains all the packages we'll need.
Flashing a Micro SD Card
-=========================
+*************************
Problem
---------
@@ -215,17 +209,16 @@ button and wait for it to finish.
.. _start_etcher:
-Etcher
-~~~~~~~~
-
.. figure:: figures/etcher.png
:align: center
:alt: Ether
+ Etcher
+
Once the SD is flashed, insert it in the Beagle and power it up.
Cloud9 IDE
-===========
+***********
Problem
------------
@@ -241,13 +234,12 @@ a web-based intergrated development environment (IDE) as shown in
.. _start_c9:
-Cloud9 IDE
-~~~~~~~~~~~~
-
.. figure:: figures/c9.png
:align: center
:alt: The Cloud9 IDE
+ Cloud9 IDE
+
Just point the browswer on your host computer to http://192.168.7.2
and start exploring. If you want the files in your home directory to appear
in the tree structure click the settings gear and select *Show Home in Favorites*
@@ -255,13 +247,12 @@ as shown in :ref:`start_c9_show_home`.
.. _start_c9_show_home:
-Cloud9 Showing Home files
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/c9ShowHome.png
:align: center
:alt: Cloud9 showing home files
+ Cloud9 Showing Home files
+
If you want to edit files beyond your home directory you can link to the root file system by:
@@ -277,7 +268,7 @@ If you want to edit files beyond your home directory you can link to the root fi
Now you can reach all the files from Cloud9.
Getting Example Code
-====================
+**********************
Problem
---------
@@ -302,7 +293,8 @@ it on your Beagle and then look in the *docs* directory.
04debug/ 08ai/ common/ index.adoc notes.html style.html
-Each chapter has its own directory and within that directory is a **code** directory that has all of the code.
+Each chapter has its own directory and within that directory
+is a **code** directory that has all of the code.
.. code-block::bash
@@ -313,7 +305,7 @@ Each chapter has its own directory and within that directory is a **code** direc
Go and explore.
Blinking an LED
-=================
+*****************
Problem
---------
@@ -330,8 +322,9 @@ is some code that blinks the ``USR3`` LED ten times using the PRU.
.. _start_hello:
-hello.pru0.c
-~~~~~~~~~~~~~
+.. literalinclude:: code/hello.pru0.c
+ :caption: hello.pru0.c
+ :linenos:
:download:`hello.pru0.c <code/hello.pru0.c>`
@@ -346,7 +339,7 @@ to run it right now do the following.
.. tip::
If the following doesn't work see
- `Compiling with clpru and lnkpru <../03details/details.html#_compiling_with_clpru_and_lnkpru>`_
+ :ref:`compiling_with_clpru_and_lnkpru`
for instillation instructions.
.. _start_running_code:
diff --git a/books/pru-cookbook/03details/details.rst b/books/pru-cookbook/03details/details.rst
index 24aa20a4bfae86634c1fa6ad1e84cc17776fc765..55f8761fda6acee8c5100a2fbbc7e2f10da22c7c 100644
--- a/books/pru-cookbook/03details/details.rst
+++ b/books/pru-cookbook/03details/details.rst
@@ -20,7 +20,7 @@ compile code and also start and stop the PRUs.
Getting Example Code
-=====================
+**********************
Problem
---------
@@ -42,10 +42,10 @@ It's all on a GitHub repository.
code to be identical for specific version. The version needs to be noted in the
documentation.
+.. _compiling_with_clpru_and_lnkpru:
Compiling with clpru and lnkpru
-================================
-
+********************************
Problem
---------
@@ -64,6 +64,7 @@ They are called ``clpru`` and ``lnkpru``. Do the following to see if ``clpru``
/usr/bin/clpru
.. tip::
+
If ``clpru`` isn't installed, follow the instructions at
https://elinux.org/Beagleboard:BeagleBoneBlack_Debian#TI_PRU_Code_Generation_Tools
to install it.
@@ -83,6 +84,7 @@ In fact there are PRU versions of many of the standard code generation tools.
code tools
~~~~~~~~~~~
+
.. code-block:: bash
bone$ ls /usr/bin/*pru
@@ -95,7 +97,7 @@ code tools
See the `PRU Assembly Language Tools <http://www.ti.com/lit/ug/spruhv6b/spruhv6b.pdf>`_ for more details.
Making sure the PRUs are configured
-====================================
+*************************************
Problem
---------
@@ -130,7 +132,7 @@ Uncomment the ``uboot_overlay`` line as shown and then reboot.
0 lrwxrwxrwx 1 root root 33 Jul 29 16:12 pruss-core1 -> /sys/class/remoteproc/remoteproc2
Compiling and Running
-======================
+**********************
Problem
---------
@@ -203,6 +205,7 @@ You can override the ``TARGET`` on the command line.
Notice the ``TARGET`` doesn't have the ``.c`` on the end.
You can also specify them when running ``make``.
+
.. code-block:: bash
bone$ cp gpio.pru0.c gpio.pru1.c
@@ -211,8 +214,10 @@ You can also specify them when running ``make``.
The setup file also contains instructions to figure out which Beagle you are running
and then configure the pins acordingly.
-setup.sh
-~~~~~~~~~
+
+.. literalinclude:: code/gpio_setup.sh
+ :caption: gpio_setup.sh
+ :linenos:
:download:`gpio_setup.sh <code/gpio_setup.sh>`
@@ -240,7 +245,7 @@ The ``Makefile`` stops the PRU, compiles the file and moves it where it will
be loaded, and then restarts the PRU.
Stopping and Starting the PRU
-==============================
+*******************************
Problem
---------
@@ -278,7 +283,7 @@ If you want to control the other PRU use:
.. _details_makefile:
The Standard Makefile
-=====================
+**********************
Problem
---------
@@ -299,8 +304,9 @@ It's assumed you already know how Makefiles work. If not, there are
many resources online that can bring you up to speed.
Here is the local ``Makefile`` used throughout this book.
-Local Makefile
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/Makefile
+ :caption: Local Makefile
+ :linenos:
:download:`Makefile <code/Makefile>`
@@ -312,7 +318,7 @@ Fortunately you shouldn't have to modify the `Makefile`.
.. _detail_linker:
The Linker Command File - am335x_pru.cmd
-=========================================
+******************************************
Problem
@@ -328,8 +334,10 @@ where to put what for the BeagleBone Black and Blue, and the Pocket.
The ``am57xx_pru.cmd`` does the same for the AI.
Both files can be found in ``/var/lib/cloud9/common``.
-am335x_pru.cmd
-~~~~~~~~~~~~~~~~
+
+.. literalinclude:: code/am335x_pru.cmd
+ :caption: am335x_pru.cmd
+ :linenos:
:download:`am335x_pru.cmd <code/am335x_pru.cmd>`
@@ -340,44 +348,44 @@ The cmd file for the AI is about the same, with appropriate addresses for the AI
Discussion
-----------
-
The important things to notice in the file are given in the following table.
AM335x_PRU.cmd important things
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
.. table::
- +-----+-----------------------------------------------------------------------------------------+
- |Line | Explanation |
- +=====+=========================================================================================+
- |16 | This is where the instructions are stored. See page 206 of the |
+ +-----+------------------------------------------------------------------------------------------------+
+ |Line | Explanation |
+ +=====+================================================================================================+
+ |16 | This is where the instructions are stored. See page 206 of the |
| | `AM335x Technical Reference Manual rev. P <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_ |
- | | Or see page 417 of |
- | | `AM572x Technical Reference Manual <http://www.ti.com/lit/pdf/spruhz6l>`_ for the AI. |
- +-----+-----------------------------------------------------------------------------------------+
- |22 | This is where PRU 0's DMEM 0 is mapped. It's also where PRU 1's |
- | | DMEM 1 is mapped. |
- +-----+-----------------------------------------------------------------------------------------+
- |23 | The reverse to above. PRU 0's DMEM 1 appears here and PRU 1's DMEM 0 |
- | | is here. |
- +-----+-----------------------------------------------------------------------------------------+
- |26 | The shared memory for both PRU's appears here. |
- +-----+-----------------------------------------------------------------------------------------+
- |72 | The `.text` section is where the code goes. It's mapped to `IMEM` |
- +-----+-----------------------------------------------------------------------------------------+
- |73 | The ((stack)) is then mapped to DMEM 0. Notice that DMEM 0 is one bank |
- +-----+-----------------------------------------------------------------------------------------+
- | | of memory for PRU 0 and another for PRU1, so they both get their own stacks. |
- +-----+-----------------------------------------------------------------------------------------+
- |74 | The `.bss` section is where the **heap** goes. |
- +-----+-----------------------------------------------------------------------------------------+
+ | | Or see page 417 of |
+ | | `AM572x Technical Reference Manual <http://www.ti.com/lit/pdf/spruhz6l>`_ for the AI. |
+ +-----+------------------------------------------------------------------------------------------------+
+ |22 | This is where PRU 0's DMEM 0 is mapped. It's also where PRU 1's |
+ | | DMEM 1 is mapped. |
+ +-----+------------------------------------------------------------------------------------------------+
+ |23 | The reverse to above. PRU 0's DMEM 1 appears here and PRU 1's DMEM 0 |
+ | | is here. |
+ +-----+------------------------------------------------------------------------------------------------+
+ |26 | The shared memory for both PRU's appears here. |
+ +-----+------------------------------------------------------------------------------------------------+
+ |72 | The `.text` section is where the code goes. It's mapped to `IMEM` |
+ +-----+------------------------------------------------------------------------------------------------+
+ |73 | The ((stack)) is then mapped to DMEM 0. Notice that DMEM 0 is one bank |
+ +-----+------------------------------------------------------------------------------------------------+
+ | | of memory for PRU 0 and another for PRU1, so they both get their own stacks. |
+ +-----+------------------------------------------------------------------------------------------------+
+ |74 | The `.bss` section is where the **heap** goes. |
+ +-----+------------------------------------------------------------------------------------------------+
Why is it important to understand this file? If you are going to store things
in DMEM, you need to be sure to start at address 0x0200 since the **stack** and
the **heap** are in the locations below 0x0200.
Loading Firmware
-==================
+*****************
Problem
---------
@@ -441,7 +449,7 @@ Therefore you copy your ``.out`` file to ``/lib/firmware/am335x-pru0-fw``.
.. _details_configure_servos:
Configuring Pins for Controlling Servos
-========================================
+****************************************
Problem
---------
@@ -455,8 +463,10 @@ It depends on which Beagle you are running on. If you are on the AI or Blue,
everything is already configured for you.
If you are on the Black or Pocket you'll need to run the following script.
-servos_setup.sh
-~~~~~~~~~~~~~~~~
+
+.. literalinclude:: code/servos_setup.sh
+ :caption: servos_setup.sh
+ :linenos:
:download:`servos_setup.sh <code/servos_setup.sh>`
@@ -470,7 +480,7 @@ assigns ``pins`` a list of pins to configure. Then the last part of the script
.. _details_configure_encoders:
Configuring Pins for Controlling Encoders
-==========================================
+*********************************************
Problem
---------
@@ -484,7 +494,9 @@ It depends on which Beagle you are running on. If you are on the AI or Blue,
everything is already configured for you.
If you are on the Black or Pocket you'll need to run the following script.
-.encoder_setup.sh
+.. literalinclude:: code/encoder_setup.sh
+ :caption: encoder_setup.sh
+ :linenos:
:download:`encoder_setup.sh <code/encoder_setup.sh>`
diff --git a/books/pru-cookbook/04debug/debug.rst b/books/pru-cookbook/04debug/debug.rst
index 7887b96c13784a3202985f7329a53411009bc2ac..42a54d4a220c75e8db8ac7b1a98a480fd1dcda0c 100644
--- a/books/pru-cookbook/04debug/debug.rst
+++ b/books/pru-cookbook/04debug/debug.rst
@@ -13,7 +13,7 @@ Finally, using one of the UARTS to send debugging information out a serial port
is shown.
Debugging via an LED
-=====================
+**********************
Problem
---------
@@ -28,17 +28,16 @@ flash. :ref:`debug_LED` shows an LED attached to pin P9_29 of the BeagleBone Bla
.. _debug_LED:
-LED used for debugging P9_29
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/LED_bb.png
:align: center
:alt: LED used for debugging P9_29
+ LED used for debugging P9_29
+
Make sure you have the LED in the correct way, or it won't work.
Discussion
----------
+-----------
If your output is changing more than a few times a second, the LED will be
blinking too fast and you'll need an oscilloscope or a logic analyzer to
@@ -50,7 +49,7 @@ RAM is discussed in :ref:`debug_prudebug`.
.. _dmesg_hw:
dmesg Hw
-=========
+***********
Problem
---------
@@ -60,16 +59,16 @@ when I load my code, but don't know what's causing it.
Solution
---------
+
The command ``dmesg`` outputs useful information when dealing with the kernel.
Simplying running ``dmesg -Hw`` can tell you a lot. The ``-H`` flag puts the
dates in the human readable form, the ``-w`` tells it to wait for more information.
Often I'll have a window open running ``dmesg -Hw``.
-.
Here's what ``dmesg`` said for the example above.
dmesg -Hw
-~~~~~~~~~~
+**********
.. code-block:: bash
@@ -83,7 +82,7 @@ to my code.
.. _debug_prudebug:
prudebug - A Simple Debugger for the PRU
-=========================================
+******************************************
Problem
---------
@@ -200,10 +199,7 @@ restart back at the beginning.
The ``dd`` command dumps the memory. Keep in mind the following.
-Important memory locations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Important memory locations
+-------+---------------------------------------------------------------------------+
|Address|Contents |
@@ -274,12 +270,10 @@ Here's the shared memory.
You can also use ``prudebug`` to set breakpoints and single step,
but I haven't used that feature much.
-:ref:`../05blocks/blocks.html#_memory_allocation, Memory Allocation` gives examples
-of how you can control where your vaiables are stored in memory.
-
+:ref:`memory_allocation` gives examples of how you can control where your vaiables are stored in memory.
UART
-======
+******
Problem
---------
@@ -297,44 +291,39 @@ use the UART (serial port) to output debug information. The PRU has it's
own UART that can send characters to a serial port.
You'll need a 3.3V FTDI cable to go between your Beagle and the USB port
-on your host computer as shown in :ref:`debug_ftdi`. [#debug1]_
+on your host computer as shown in :ref:`ftdi_cable`. [#debug1]_
you can get such a cable from places such as
`Sparkfun <https://www.sparkfun.com/products/9717>`_ or
`Adafruit <https://www.adafruit.com/product/70>`_.
-.. _debug_ftdi:
-
-FTDI cable
-~~~~~~~~~~~
+.. _ftdi_cable:
.. figure:: figures/FTDIcable.jpg
:align: center
:alt: FTDI cable
+ FTDI cable
+
Discussion
----------
+-----------
The Beagle side of the FTDI cable has a small triangle on it as shown in
:ref:`debug_ftdi_connector` which marks the ground pin, pin 1.
.. _debug_ftdi_connector:
-FTDI connector
-~~~~~~~~~~~~~~~~~
-
.. figure:: figures/FTDIconnector.jpg
:align: center
:alt: FTDI connector
+ FTDI connector
+
The :ref:`debug_FTDI` table shows which pins connect where and :ref:`debug_ftdi_pins`
is a wiring diagram for the BeagleBone Black.
.. _debug_FTDI:
-Wriing for FTDI cable to Beagle
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Wring for FTDI cable to Beagle
+--------+------+---------+-------------+--------+------+---------+
|FTDI pin|Color |Black pin|AI 1 pin |AI 2 pin|Pocket|Function |
@@ -348,15 +337,14 @@ Wriing for FTDI cable to Beagle
.. _debug_ftdi_pins:
-FTDI to BB Black
-~~~~~~~~~~~~~~~~~
-
.. figure:: figures/FTDIhookup_bb.png
:align: center
:alt: FTDI to BB Black
+ FTDI to BB Black
+
Details
-~~~~~~~~
+--------
Two examples of using the UART are presented here. The first
(:ref:`debug_uart1`) sends a character out the serial port then
@@ -375,7 +363,7 @@ Once an ENTER appears the string is sent back.
You need to set the pin muxes.
config-pin
-~~~~~~~~~~~
+-----------
.. code-block:: bash
@@ -391,8 +379,9 @@ config-pin
.. note::
- See :ref:`../08ai/ai.html#ai_device_tree, Configuring pins on the AI via device trees` for configuring
- pins on the AI. Make sure your `rx` pins are configured as input pins in the device tree.
+ See :ref:`ai_device_tree` for configuring
+ pins on the AI. Make sure your `rx` pins are
+ configured as input pins in the device tree.
For example
@@ -402,15 +391,16 @@ For example
.. * TODO - Add code for Blue.
-uart1.pru1_0.c
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/uart1.pru1_0.c
+ :caption: uart1.pru1_0.c
+ :linenos:
-Set the following variables so ``make`` will know what to compile.
+:download:`uart1.pru1_0.c <code/uart1.pru1_0.c>`
-make
-~~~~~
+Set the following variables so ``make`` will know what to compile.
.. code-block:: bash
+ :caption: make
bone$ *make TARGET=uart1.pru0*
/var/lib/cloud9/common/Makefile:29: MODEL=TI_AM335x_BeagleBone_Black,TARGET=uart1.pru0
@@ -433,19 +423,19 @@ In a terminal window on your host computer run
It will initially display the first charters (``H``) and then as you enter
characters on the keyboard, the rest of the message will appear.
-uart1.pru0.c output
-~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/uart1.pru0.png
:align: center
:alt: uart1.pru0.c output
+ uart1.pru0.c output
+
Here's the code (``uart1.pru1_0.c``) that does it.
.. _debug_uart1:
-uart1.pru1_0.c
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/uart1.pru1_0.c
+ :caption: uart1.pru1_0.c
+ :linenos:
:download:`uart1.pru1_0.c <code/uart1.pru1_0.c>`
@@ -472,15 +462,16 @@ receive register on the UART.
These simple lines should be enough to place in your code to print out
debugging information.
-uart2.pru0.c
-~~~~~~~~~~~~
+.. literalinclude:: code/uart2.pru0.c
+ :caption: uart2.pru0.c
+ :linenos:
-If you want to try ``uart2.pru0.c``, run the following:
+:download:`uart2.pru0.c <code/uart2.pru0.c>`
-make
-~~~~~
+If you want to try ``uart2.pru0.c``, run the following:
.. code-block:: bash
+ :caption: make
bone$ *make TARGET=uart2.pru0*
/var/lib/cloud9/common/Makefile:29: MODEL=TI_AM335x_BeagleBone_Black,TARGET=uart2.pru0
@@ -495,13 +486,12 @@ make
You will see:
-uart2.pru0.c output
-~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/uart2.pru0.png
:align: center
:alt: uart2.pru0.c output
+ uart2.pru0.c output
+
Type a few characters and hit ENTER. The PRU will playback what you typed,
but it won't echo it as you type.
@@ -514,8 +504,9 @@ wait for the FIFO to empty, which may cause your code to miss something.
.. _debug_uart2:
-uart2.pru1_0.c
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/uart2.pru1_0.c
+ :caption: uart2.pru1_0.c
+ :linenos:
:download:`uart2.pru1_0.c <code/uart2.pru1_0.c>`
@@ -524,11 +515,12 @@ More complex examples can be built using the principles shown in these examples.
Copyright
==========
-copyright.c
-~~~~~~~~~~~~~
+.. literalinclude:: code/copyright.c
+ :caption: copyright.c
+ :linenos:
:download:`copyright.c <code/copyright.c>`
.. rubric:: Footnotes
-.. [#debug1] FTDI images are from the BeagleBone Cookbook http://shop.oreilly.com/product/0636920033899.do
+.. [#debug1] `FTDI images are from the BeagleBone Cookbook <http://shop.oreilly.com/product/0636920033899.do>`_
diff --git a/books/pru-cookbook/05blocks/blocks.rst b/books/pru-cookbook/05blocks/blocks.rst
index e6de06e35ef9851530791b1518ba28ef68a765c4..1b62a966b494ee426a8889a35a6dc55f7a4723ce 100644
--- a/books/pru-cookbook/05blocks/blocks.rst
+++ b/books/pru-cookbook/05blocks/blocks.rst
@@ -16,8 +16,10 @@ Resources
* `Exploring BeagleBone by Derek Molloy <http://exploringbeaglebone.com/>`_
* `WS2812 Data Sheet <https://cdn-shop.adafruit.com/datasheets/WS2812.pdf>`_
+.. _memory_allocation:
+
Memory Allocation
-==================
+******************
Problem
@@ -35,13 +37,12 @@ shared memory (Shared RAM) as shown in :ref:`blocks_PRU_block_diagram`.
.. _blocks_PRU_block_diagram:
-PRU Block Diagram
-~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/blockDiagram.png
:align: center
:alt: PRU Block diagram
+ PRU Block Diagram
+
Each PRU accesses it's own DRAM starting at location 0x0000_0000. Each PRU
can also access the other PRU's DRAM starting at 0x0000_2000. Both PRUs
access the shared RAM at 0x0001_0000. The compiler can control where each
@@ -51,8 +52,9 @@ of these memories variables are stored.
.. _blocks_shared:
-shared.pro0.c - Examples of Using Different Memory Locations
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/shared.pru0.c
+ :caption: shared.pro0.c - Examples of Using Different Memory Locations
+ :linenos:
:download:`shared.pru0.c <code/shared.pru0.c>`
@@ -62,8 +64,7 @@ Discussion
Here's the line-by-line
-Line-byline for shared.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. table:: Line-byline for shared.pru0.c
+-------+---------------------------------------------------------------------------------------------------------+
|Line | Explanation |
@@ -155,9 +156,7 @@ therefore placed on the stack at run time. The ``shared.map`` file shows the
compile time allocations. We have to look in the memory itself to see what
happen at run time.
-Let's fire up ``prudebug``
-(:ref:`../04debug/debug.html#debug_prudebug, prudebug - A Simple Debugger for the PRU`)
-to see where things are.
+Let's fire up ``prudebug`` (:ref:`debug_prudebug`) to see where things are.
.. code-block:: bash
@@ -233,10 +232,10 @@ be sure if you are hand picking where things are put, not to put them in places
used by the compiler.
Auto Initialization of built-in LED Triggers
-=============================================
+*********************************************
Problem
------------
+---------
I see the built-in LEDs blink to their own patterns.
How do I turn this off? Can this be automated?
@@ -312,8 +311,9 @@ the code work. Fortunately the Makefile always runs it.
.. _blocks_write_init_pins:
-write_init_pins.sh
-~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/write_init_pins.sh
+ :caption: write_init_pins.sh
+ :linenos:
:download:`write_init_pins.sh <code/write_init_pins.sh>`
@@ -338,7 +338,7 @@ file contains everything needed to run the executable.
.. _blocks_pwm:
PWM Generator
-==============
+**************
One of the simplest things a PRU can to is generate a simple
signal starting with a single channel PWM that has a fixed frequency and
@@ -365,8 +365,9 @@ for details on making it work.
.. _blocks_pwm1:
-pwm1.pru0.c
-~~~~~~~~~~~~
+.. literalinclude:: code/pwm1.pru0.c
+ :caption: pwm1.pru0.c
+ :linenos:
:download:`pwm1.pru0.c <code/pwm1.pru0.c>`
@@ -385,7 +386,7 @@ On the Pocket run
.. note::
- See :ref:`../08ai/ai.html#ai_device_tree, Configuring pins on the AI via device trees`
+ See :ref:`ai_device_tree`
for configuring pins on the AI.
Then, tell ``Makefile`` which PRU you are compiling for and what your target file is
@@ -417,17 +418,17 @@ Discussion
Since this is our first example we'll discuss the many parts in detail.
-pwm1.pru0.c
-~~~~~~~~~~~~
+.. literalinclude:: code/pwm1.pru0.c
+ :caption: pwm1.pru0.c
+ :linenos:
+
+:download:`pwm1.pru0.c <code/pwm1.pru0.c>`
:ref:`blocks_pwm1_line_by_line` is a line-by-line expanation of the c code.
.. _blocks_pwm1_line_by_line:
-Line-by-line of pwm1.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Line-by-line of pwm1.pru0.c
+-----+-------------------------------------------------------------------------------------+
|Line | Explanation |
@@ -446,34 +447,32 @@ Line-by-line of pwm1.pru0.c
Here's what's in ``resource_table_empty.h``
-resource_table_empty.c
-~~~~~~~~~~~~~~~~~~~~~~~
-
-:download:`resource_table_empty.h <code/resource_table_empty.h>`
+.. literalinclude:: code/resource_table_empty.h
+ :caption: resource_table_empty.c
+ :linenos:
-Line-by-line (continuted)
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+:download:`resource_table_empty.c <code/resource_table_empty.h>`
-.. table::
+.. table:: Line-by-line (continuted)
+-----+-----------------------------------------------------------------------------------------------------------------+
|Line | Explanation |
+=====+=================================================================================================================+
- |6-7 | `pass:[__]R30` and `pass:[__]R31` are two variables that refer to the |
- | | PRU output (`pass:[__]R30`) and input (`pass:[__]R31`) registers. |
- | | When you write something to `pass:[__]R30` it will show up on the |
- | | corresponding output pins. When you read from `pass:[__]R31` |
+ |6-7 | ``__R30`` and ``__R31`` are two variables that refer to the |
+ | | PRU output (``__R30``) and input (``__R31``) registers. |
+ | | When you write something to ``__R30`` it will show up on the |
+ | | corresponding output pins. When you read from ``__R31`` |
| | you read the data on the input pins. |
| | NOTE: Both names begin with two underscore's. Section 5.7.2 of the |
- | | http://www.ti.com/lit/ug/spruhv7b/spruhv7b.pdf[PRU Optimizing C/C++ Compiler, v2.2, User's Guide] |
+ | | `PRU Optimizing C/C++ Compiler, v2.2, User's Guide <http://www.ti.com/lit/ug/spruhv7b/spruhv7b.pdf>`_ |
| | gives more details. |
+-----+-----------------------------------------------------------------------------------------------------------------+
- |11 | This line selects which GPIO pin to toggle. The table below shows which bits in `pass:[__]R30` |
+ |11 | This line selects which GPIO pin to toggle. The table below shows which bits in ``__R30`` |
| | map to which pins |
+-----+-----------------------------------------------------------------------------------------------------------------+
|14 | `CT_CFG.SYSCFG_bit.STANDBY_INIT` is set to `0` to enable the OCP master port. More details on this |
| | and thousands of other regesters see the |
- | | https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf[AM335x Technical Reference Manual]. Section 4 is on the PRU |
+ | | `TI AM335x TRM <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_. Section 4 is on the PRU |
| | and section 4.5 gives details for all the registers. |
+-----+-----------------------------------------------------------------------------------------------------------------+
@@ -483,10 +482,7 @@ Bit 0 is the LSB.
.. _blocks_mapping_bits:
-Mapping bit positions to pin names
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Mapping bit positions to pin names
+---+---+---------------------+-----------+
|PRU|Bit|Black pin |Pocket pin |
@@ -550,34 +546,32 @@ Mapping bit positions to pin names
.. note::
- See :ref:`../08ai/ai.html#ai_device_tree, Configuring pins on the AI via device trees`
+ See :ref:`ai_device_tree`
for all the PRU pins on the AI.
Since we are running on PRU 0, and we're using ``0x0001``,
that is bit 0, we'll be toggling ``P9_31``.
-Line-by-line (continued again)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. table::
+.. table:: Line-by-line (continued again)
+-----+-----------------------------------------------------------------------+
|Line | Explanation |
+=====+=======================================================================+
- |17 | Here is where the action is. This line reads ``pass:[__]R30`` and |
+ |17 | Here is where the action is. This line reads ``__R30`` and |
| | then ORs it with ``gpio``, setting the bits where there is |
| | a 1 in ``gpio`` and leaving the bits where there is a 0. |
| | Thus we are setting the bit we selected. Finally the new |
- | | value is written back to ``pass:[__]R30``. |
+ | | value is written back to ``__R30``. |
+-----+-----------------------------------------------------------------------+
- |18 | ``pass:[__]delay_cycles`` is an ((instrinsic function)) that delays |
+ |18 | ``__delay_cycles`` is an ((instrinsic function)) that delays |
| | with number of cycles passed to it. Each cycle is 5ns, |
| | and we are delaying 100,000,000 cycles which is |
| | 500,000,000ns, or 0.5 seconds. |
+-----+-----------------------------------------------------------------------+
|19 | This is like line 17, but ``~gpio`` inverts all the bits in ``gpio`` |
| | so that where we had a 1, there is now a 0. This 0 |
- | | is then ANDed with ``pass:[__]R30`` setting the corresponding |
+ | | is then ANDed with ``__R30`` setting the corresponding |
| | bit to 0. Thus we are clearing the bit we selected. |
+-----+-----------------------------------------------------------------------+
@@ -590,31 +584,30 @@ Line-by-line (continued again)
When you run this code and look at the output you will see something like the following figure.
-Output of pwm1.pru0.c with 100,000,000 delays cycles giving a 1s period
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: figures/pwm1.png
:align: center
:alt: pwm1.pru0.c output
+ Output of pwm1.pru0.c with 100,000,000 delays cycles giving a 1s period
+
Notice the on time (``+Width(1)``) is 500ms, just as we predicted.
The off time is 498ms, which is only 2ms off from our prediction.
The standard deviation is 0, or only 380as, which is 380 * 10^-18^!.
You can see how fast the PRU can run by setting both of the
-``pass:[__]delay_cycles`` to 0. This results in the next figure.
-
-Output of pwm1.pru0c with 0 delay cycles
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+``__delay_cycles`` to 0. This results in the next figure.
.. figure:: figures/pwm2.png
:align: center
:alt: pwm1.pru0.c output with 0 delay
+ Output of pwm1.pru0c with 0 delay cycles
+
Notice the period is 15ns which gives us a frequency of about 67MHz. At this high
frequency the breadboard that I'm using distorts the waveform so it's no longer a squarewave.
-The **on** time is 5.3ns and the **off** time is 9.8ns. That means **pass:[__]R30 |= gpio**
-took only one 5ns cycle and ``pass:[__]R30 &= ~gpio`` also only took one cycle, but there
+The **on** time is 5.3ns and the **off** time is 9.8ns. That means **__R30 |= gpio**
+took only one 5ns cycle and ``__R30 &= ~gpio`` also only took one cycle, but there
is also an extra cycle needed for the loop. This means the compiler was able to implement
the ``while`` loop in just three 5ns instructions! Not bad.
@@ -622,29 +615,35 @@ We want a square wave, so we need to add a delay to correct for the delay of loo
Here's the code that does just that.
-pwm2.pru0.c
-~~~~~~~~~~~~~
+.. literalinclude:: code/pwm2.pru0.c
+ :caption: pwm2.pru0.c
+ :linenos:
:download:`pwm2.pru0.c <code/pwm2.pru0.c>`
The output now looks like:
-Output of pwm2.pru0.c corrected delay
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pwm3.png
:align: center
:alt: pwm2.c corrected delay
-It's not hard to adjust the two ``pass:[__]delay_cycles``
+ Output of pwm2.pru0.c corrected delay
+
+It's not hard to adjust the two ``__delay_cycles``
to get the desired frequency and duty cycle.
-### Controlling the PWM Frequency
-#### Problem
+Controlling the PWM Frequency
+******************************
+
+Problem
+---------
+
You would like to control the frequency and
duty cycle of the PWM without recompiling.
-#### Solution
+Solution
+----------
+
Have the PRU read the **on** and **off** times from a shared memory location.
Each PRU has is own 8KB of data memory (DRAM) and 12KB of shared memory
(SHAREDMEM) that the ARM processor can also access. See :ref:`blocks_PRU_block_diagram`.
@@ -654,8 +653,7 @@ The DRAM 0 address is 0x0000 for PRU 0. The same DRAM appears at address
.. tip::
- See page
- 184 of the https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf[AM335x Technical Reference Manual].
+ See page 184 of the `AM335x TRM (184) <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_.
We take the previous PRU code and add the lines
@@ -692,15 +690,17 @@ the ARM can write values into the DRAM and change the PWM on and off times.
.. _blocks_pwm4:
-pwm4.pru0.c
-~~~~~~~~~~~~
+.. literalinclude:: code/pwm4.pru0.c
+ :caption: pwm4.pru0.c
+ :linenos:
:download:`pwm4.pru0.c <code/pwm4.pru0.c>`
Here is code that runs on the ARM side to set the on and off time values.
-pwm-test.c
-~~~~~~~~~~~~
+.. literalinclude:: code/pwm-test.c
+ :caption: pwm-test.c
+ :linenos:
:download:`pwm-test.c <code/pwm-test.c>`
@@ -708,13 +708,12 @@ A quick check on the 'scope shows :ref:`blocks_pwm_arm_control`.
.. _blocks_pwm_arm_control:
-Four Channel PWM with ARM control
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pwm4.png
:align: center
:alt: pwm4.png
+ Four Channel PWM with ARM control
+
From the 'scope you see a 1 cycle **on** time results in a 450ns wide pulse and a
3.06us period is 326KHz, much slower than the 10ns pulse we saw before. But it
may be more than fast enough for many applications. For example, most servos run at 50Hz.
@@ -722,39 +721,35 @@ may be more than fast enough for many applications. For example, most servos ru
But we can do better.
Loop Unrolling for Better Performance
-======================================
+***************************************
Problem
------------
+---------
The ARM controlled PRU code runs too slowly.
Solution
------------
+----------
-Simple loop unrolling can greatly improve the speed. ``pwm5.pru0.c`` is our unrolled
-version.
+Simple loop unrolling can greatly improve the speed. ``pwm5.pru0.c`` is our unrolled version.
-pwm5.pru0.c Unrolled
-~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm5.pru0.c
+ :caption: pwm5.pru0.c Unrolled
+ :linenos:
:download:`pwm5.pru0.c <code/pwm5.pru0.c>`
The output of ``pwm5.pru0.c`` is in the figure below.
-pwm5.pru0.c Unrolled version of pwm4.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pwm5_no_loop.png
:align: center
:alt: pwm5.pru0.c Unrolled version of pwm4.pru0.c
-It's running about 6 times faster than ``pwm4.pru0.c``.
+ pwm5.pru0.c Unrolled version of pwm4.pru0.c
-pwm4.pru0.c vs. pwm5.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It's running about 6 times faster than ``pwm4.pru0.c``.
-.. table::
+.. table:: pwm4.pru0.c vs. pwm5.pru0.c
+---------+-----------------+-----------------+---------+-----------------------+---------+
|Measure |pwm4.pru0.c time |pwm5.pru0.c time |Speedup |pwm5.pru0.c w/o UNROLL |Speedup |
@@ -786,7 +781,7 @@ it copies the code an then it's compiled.
This unrolling gets us an impressive 6x speedup.
Making All the Pulses Start at the Same Time
-=============================================
+**********************************************
Problem
-----------
@@ -802,21 +797,22 @@ in each channel starts about 15ns later than the channel above it.
.. _blocks_zoomed:
-pwm5.pru0 Zoomed In
-~~~~~~~~~~~~~~~~~~~~~
.. figure:: figures/pwm5_zoomed.png
:align: center
:alt: pwm5.pru0 zoomed.png
-The solution is to declare ``Rtmp`` (line 35) which holds the value for ``pass:[__]R30``.
+ pwm5.pru0 Zoomed In
+
+The solution is to declare ``Rtmp`` (line 35) which holds the value for ``__R30``.
-pwm6.pru0.c Sync'ed Version of pwm5.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm6.pru0.c
+ :caption: pwm6.pru0.c Sync'ed Version of pwm5.pru0.c
+ :linenos:
:download:`pwm6.pru0.c Sync'ed Version of pwm5.pru0.c <code/pwm6.pru0.c>`
Each channel writes it's value to ``Rtmp`` (lines 17 and 20) and then after
-each channel has updated, ``Rtmp`` is copied to ``pass:[__]R30`` (line 54).
+each channel has updated, ``Rtmp`` is copied to ``__R30`` (line 54).
Discussion
-----------
@@ -824,16 +820,16 @@ Discussion
The following figure shows the channel are sync'ed. Though the period is slightly
longer than before.
-pwm6.pru0 Synchronized Channels
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. figure:: figures/pwm6_synced.png
:align: center
:alt: pwm6.pru0 Synchronized Channels
+ pwm6.pru0 Synchronized Channels
+
Adding More Channels via PRU 1
-================================
+*******************************
Problem
-----------
@@ -857,15 +853,17 @@ will make the period half as long.
Here's the code (``pwm7.pru0.c``)
-pwm7.pru0.c Using Both PRUs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm7.pru0.c
+ :caption: pwm7.pru0.c Using Both PRUs
+ :linenos:
:download:`pwm7.pru0.c Using Both PRUs <code/pwm7.pru0.c>`
Be sure to run ``pwm7_setup.sh`` to get the correct pins configured.
-pwm7_setup.sh
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm7_setup.sh
+ :caption: pwm7_setup.sh
+ :linenos:
:download:`pw7_setup.sh <code/pwm7_setup.sh>`
@@ -908,6 +906,7 @@ Discussion
There weren't many changes to be made. Line 15 we set MAXCH to 2. Lines 44-48
is where the big change is.
+
.. code-block:: c
pru0_dram[2*ch ] = on [ch+PRUNUN*MAXCH]; // Copy to DRAM0 so the ARM can change it
@@ -924,30 +923,28 @@ behavior.
Running the code you will see the next figure.
-pwm7.pru0 Two PRUs running
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pwm7_two_prus_running.png
:align: center
:alt: pwm7.pru0 Two PRUs running
+ pwm7.pru0 Two PRUs running
+
What's going on there, the first channels look fine, but the PRU 1 channels
are blurred. To see what's happening, let's stop the oscilloscope.
-pwm7.pru0 Two PRUs stopped
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pwm7_two_prus_stopped.png
:align: center
:alt: pwm7 Two PRUs stopped
+ pwm7.pru0 Two PRUs stopped
+
The stopped display shows that the four channels are doing what we wanted, except
The PRU 0 channels have a period of 370ns while the PRU 1 channels at 330ns.
It appears the compiler has optimied the two PRUs slightly differenty.
Synchronizing Two PRUs
-=======================
+***********************
Problem
-----------
@@ -958,26 +955,28 @@ Solution
-----------
Use the Interrupt Controller (INTC). It allows one PRU to signal the other.
-Page 225 of the `AM335x Technical Reference Manual <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_
+Page 225 of the `AM335x TRM 225 <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_
has details of how it works. Here's the code for PRU 0, which at the end of the
``while`` loop signals PRU 1 to start(``pwm8.pru0.c``).
-pwm8.pru0.c PRU 0 using INTC to send a signal to PRU 1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm8.pru0.c
+ :caption: pwm8.pru0.c PRU 0 using INTC to send a signal to PRU 1
+ :linenos:
:download:`pwm8.pru0.c PRU 0 using INTC to send a signal to PRU 1 <code/pwm8.pru0.c>`
PRU 2's code waits for PRU 0 before going.
-pwm8.pru1.c PRU 1 waiting for INTC from PRU 0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm8.pru1.c
+ :caption: pwm8.pru1.c PRU 1 waiting for INTC from PRU 0
+ :linenos:
:download:`pwm8.pru1.c PRU 1 waiting for INTC from PRU 0 <code/pwm8.pru1.c>`
In ``pwm8.pru0.c`` PRU 1 waits for a signal from PRU 0, so be sure to start PRU 1 first.
.. code-block:: bash
-
+
bone$ *make TARGET=pwm8.pru0; make TARGET=pwm8.pru1*
Discussion
@@ -986,31 +985,27 @@ Discussion
The figure below shows the two PRUs are synchronized, though there is some extra
overhead in the process so the period is longer.
-pwm8.pru0 PRUs sycned
-~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/pwm8_prus_sycned.png
:align: center
:alt: pwm8.pru0 PRUs sycned
-This isn't much different from the previous examples.
+ pwm8.pru0 PRUs sycned
-pwm8.pru0.c changes from pwm7.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This isn't much different from the previous examples.
-.. table::
+.. table:: pwm8.pru0.c changes from pwm7.pru0.c
+-----+-------+---------------------------------------------------------------------------------------+
|PRU |Line |Change |
+=====+=======+=======================================================================================+
|0 |37-45 |For PRU 0 these define ``configInitc()`` which initializes the interupts. |
| | |See page 226 of the |
- | | |`AM335x Technical Reference Manual <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_ |
+ | | |`AM335x TRM <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_ |
| | |for a diagram explaining events, channels, hosts, etc. |
+-----+-------+---------------------------------------------------------------------------------------+
|0 |55-56 |Set a configuration register and call `configInitc`. |
+-----+-------+---------------------------------------------------------------------------------------+
- |1 |59-61 |PRU 1 then waits for PRU 0 to signal it. Bit 31 of ``pass:[__]R31`` corresponds |
+ |1 |59-61 |PRU 1 then waits for PRU 0 to signal it. Bit 31 of ``__R31`` corresponds |
| | |to the Host-1 channel which ``configInitc()`` set up. We also clear event 16 so |
| | |PRU 0 can set it again. |
+-----+-------+---------------------------------------------------------------------------------------+
@@ -1022,7 +1017,7 @@ pwm8.pru0.c changes from pwm7.pru0.c
This ends the multipart pwm example.
Reading an Input at Regular Intervals
-======================================
+**************************************
Problem
-----------
@@ -1032,15 +1027,11 @@ You have an input pin that needs to be read at regular intervals.
Solution
-----------
-You can use the ``pass:[__]R31`` register to read an input pin. Let's use the following
-pins.
+You can use the ``__R31`` register to read an input pin. Let's use the following pins.
.. _blocks_io_pins:
-Input/Output pins
-~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Input/Output pins
+---------+----------+-----+----------+---------+
|Direction|Bit number|Black|AI (ICSS2)|Pocket |
@@ -1054,25 +1045,27 @@ These values came from :ref:`blocks_mapping_bits`.
Configure the pins with ``input_setup.sh``.
-input_setup.sh
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/input_setup.sh
+ :caption: input_setup.sh
+ :linenos:
:download:`input_setup.sh <code/input_setup.sh>`
The following code reads the input pin and writes its value to the output pin.
-input.c
-~~~~~~~~~~
+.. literalinclude:: code/input.pru0.c
+ :caption: code/input.pru0.c
+ :linenos:
:download:`input.pru0.c <code/input.pru0.c>`
Discussion
-----------
-Just remember that ``pass:[__]R30`` is for outputs and ``pass:[__]R31`` is for inputs.
+Just remember that ``__R30`` is for outputs and ``__R31`` is for inputs.
Analog Wave Generator
-=======================
+**********************
Problem
-----------
@@ -1092,13 +1085,13 @@ a large duty cycle for when it is large.
This example was inspired by
`A PRU Sin Wave Generator <https://github.com/derekmolloy/exploringBB/tree/master/chp13/sineWave>`_
-in chapter 13 of
-`Exploring BeagleBone by Derek Molloy<http://exploringbeaglebone.com/>`_.
+in chapter 13 of `Exploring BeagleBone by Derek Molloy <http://exploringbeaglebone.com/>`_.
Here's the code.
-sine.pru0.c
-~~~~~~~~~~~~~
+.. literalinclude:: code/sine.pru0.c
+ :caption: sine.pru0.c
+ :linenos:
:download:`sine.pru0.c <code/sine.pru0.c>`
@@ -1124,32 +1117,27 @@ Suppose you want to generate a sawtooth waveform like the one shown in :ref:`blo
.. _blocks_sawtooth:
-Continuous Sawtooth Waveform
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sawtoothsmooth.png
:align: center
:alt: Continuous Sawtooth Waveform
+ Continuous Sawtooth Waveform
+
You need to sample the waveform and store one cycle. :ref:`blocks_sawtoothsampled`
shows a sampled version of the sawtooth. You need to generate ``MAXT`` samples;
here we show 20 samples, which may be enough. In the code ``MAXT`` is set to 100.
.. _blocks_sawtoothsampled:
-Sampled Sawtooth Waveform
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sawtoothsampled.png
:align: center
:alt: Sampled Sawtooth Waveform
-There's a lot going on here; let's take it line by line.
+ Sampled Sawtooth Waveform
-Line-by-line of sine.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There's a lot going on here; let's take it line by line.
-.. table::
+.. table:: Line-by-line of sine.pru0.c
+-------+---------------------------------------------------------------------------------+
|Line | Explanation |
@@ -1194,13 +1182,12 @@ Line-by-line of sine.pru0.c
.. _blocks_sawunfiltered:
-Unfiltered Sawtooth Waveform
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sawunfiltered.png
:align: center
:alt: Unfiltered Sawtooth Waveform
+ Unfiltered Sawtooth Waveform
+
It doesn't look like a sawtooth; but if you look at the left side you will
see each cycle has a longer and longer on time. The duty cycle is increasing.
Once it's almost 100% duty cycle, it switches to a very small duty cycle.
@@ -1214,13 +1201,12 @@ A simple low-pass filter, built with one resistor and one capacitor will do it.
.. _blocks_filterwiring:
-Low-Pass Filter Wiring Diagram
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/filter_bb.png
:align: center
:alt: Low-Pass Filter Wiring Diagram
+ Low-Pass Filter Wiring Diagram
+
.. note::
I used a 10K variable resistor and a 0.022uF capacitor.
@@ -1231,13 +1217,12 @@ Low-Pass Filter Wiring Diagram
.. _blocks_sawscope:
-Reconstructed Sawtooth Waveform
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sawscope.png
:align: center
:alt: Reconstructed Sawtooth Waveform
+ Reconstructed Sawtooth Waveform
+
Now that looks more like a sawtooth wave. The top plot is the time-domain
plot of the output of the low-pass filter. The bottom plot is the FFT of the top
plot, therefore it's the frequency domain. We are getting a sawtooth with a
@@ -1252,13 +1237,12 @@ resistor. You'll see something like :ref:`blocks_lowercutoff`.
.. _blocks_lowercutoff:
-Reconstructed Sawtooth Waveform with Lower Cutoff Frequency
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sawlowercutoff.png
:align: center
:alt: Reconstructed Sawtooth Waveform with Lower Cutoff Frequency
+ Reconstructed Sawtooth Waveform with Lower Cutoff Frequency
+
The high freqencies have been reduced, but the corner of the waveform has
been rounded. You can also adjust the cutoff to a higher frequency and you'll
get a sharper corner, but you'll also get more high frequencies. See
@@ -1266,13 +1250,12 @@ get a sharper corner, but you'll also get more high frequencies. See
.. _blocks_highercutoff:
-Reconstructed Sawtooth Waveform with Higher Cutoff Frequency
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sawhighercutoff.png
:align: center
:alt: Reconstructed Sawtooth Waveform with Higher Cutoff Frequency
+ Reconstructed Sawtooth Waveform with Higher Cutoff Frequency
+
Adjust to taste, though the real solution is to build a higher order filter.
Search for _second order **filter** and you'll find some nice circuits.
@@ -1285,24 +1268,22 @@ You can also get a triangle waveform by setting the ``#define``.
.. _blocks_triangle:
-Reconstructed Triangle Waveform
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/triangle.png
:align: center
:alt: Reconstructed Triangle Waveform
+ Reconstructed Triangle Waveform
+
And also the sine wave as shown in :ref:`blocks_sine`.
.. _blocks_sine:
-Reconstructed Sinusoid Waveform
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/sine.png
:align: center
:alt: Reconstructed Sinusoid Waveform
+ Reconstructed Sinusoid Waveform
+
Notice on the bottom plot the harmonics are much more suppressed.
Generating the sine waveform uses **floats**. This requires much more code.
@@ -1311,8 +1292,9 @@ You can look in `/tmp/cloud9-examples/sine.pru0.map` to see how much memory is b
.. _blocks_sine_map:
-/tmp/cloud9-examples/sine.pru0.map for Sine Wave
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/sine.map
+ :caption: /tmp/cloud9-examples/sine.pru0.map for Sine Wave
+ :linenos:
:download:`lines=1..22 <code/sine.map>`
@@ -1330,7 +1312,7 @@ to the PRU.
.. _blocks_ws2812:
WS2812 (NeoPixel) driver
-==========================
+***************************
Problem
-----------
@@ -1353,40 +1335,38 @@ Wire the input to ``P9_29`` and power to 3.3V and ground to ground as shown in
.. _blocks_neo_wiring:
-.NeoPixel Wiring
.. figure:: figures/neo_bb.png
:align: center
:alt: NeoPixel Wiring
+ NeoPixel Wiring
+
Test your wiring with the simple code in :ref:`blocks_neo1`
which to turns all pixels white.
.. _blocks_neo1:
-neo1.pru0.c - Code to turn all NeoPixels's white
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: bash
+.. literalinclude:: code/neo1.pru0.c
+ :caption: neo1.pru0.c - Code to turn all NeoPixels's white
+ :linenos:
:download:`neo1.pru0.c <code/neo1.pru0.c>`
Discussion
-----------
-:ref:`blocks_sequence` (taken from `WS2812 Data Sheet <https://cdn-shop.adafruit.com/datasheets/WS2812.pdf>`_) shows the following waveforms are used to send a bit of data.
+:ref:`blocks_sequence` (taken from `WS2812 Data Sheet <https://cdn-shop.adafruit.com/datasheets/WS2812.pdf>`_)
+shows the following waveforms are used to send a bit of data.
.. _blocks_sequence:
-NeoPixel bit sequence
-~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/neo_sequence.png
:align: center
:alt: NeoPixel bit sequence
-Where the times are:
+ NeoPixel bit sequence
-.. table::
+.. table:: Where the times are:
+-------+-------------+
|Label | Time in ns |
@@ -1411,12 +1391,11 @@ shows the waveform for sending a 0 value. Note the times are spot on.
.. _blocks_zero_scope:
-NeoPixel zero timing
-~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/neo_scope.png
:align: center
- :alt:
+ :alt: NeoPixel zero timing
+
+ NeoPixel zero timing
Each NeoPixel listens for a RGB value. Once a value has arrived all other values
that follow are passed on to the next NeoPixel which does the same thing.
@@ -1428,23 +1407,24 @@ grab the next value for itself and start over again.
Setting NeoPixels to Different Colors
-======================================
+***************************************
Problem
------------
+---------
I want to set the LEDs to different colors.
Solution
------------
+---------
-Wire your NeoPixels as shown in :ref:`blocks_neo_wiring` then run the code in
-:ref:`blocks_neo2`.
+Wire your NeoPixels as shown in :ref:`blocks_neo_wiring`
+then run the code in :ref:`blocks_neo2`.
.. _blocks_neo2:
-neo2.pru0.c - Code to turn on green, red, blue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/neo2.pru0.c
+ :caption: neo2.pru0.c - Code to turn on green, red, blue
+ :linenos:
:download:`neo2.pru0.c <code/neo2.pru0.c>`
@@ -1458,25 +1438,21 @@ used to control the green, red and blue values.
.. _blocks_new_data_seq:
-NeoPixel data sequence
-~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/neo_data_seq.png
:align: center
- :alt:
+ :alt: NeoPixel data sequence
+
+ NeoPixel data sequence
.. note::
-The usual order for colors is RGB (red, green, blue), but the NeoPixels use GRB (green, red, blue).
+ The usual order for colors is RGB (red, green, blue), but the NeoPixels use GRB (green, red, blue).
:ref:`blocks_neo2_line` is the line-by-line for ``neo2.pru0.c``.
.. _blocks_neo2_line:
-Line-by-line for neo2.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Line-by-line for neo2.pru0.c
+-------+---------------------------------------------------------------------------------+
|Line | Explanation |
@@ -1501,12 +1477,10 @@ Line-by-line for neo2.pru0.c
.. note::
-This will only change the first ``STR_LEN`` LEDs. The LEDs that follow will not
-be changed.
-====
+ This will only change the first ``STR_LEN`` LEDs. The LEDs that follow will not be changed.
Controlling Arbitrary LEDs
-============================
+***************************
Problem
-----------
@@ -1522,30 +1496,30 @@ string to the LEDs. :ref:`blocks_neo3` shows an example animates a red pixel
running around a ring of blue background. :ref:`blocks_neo3_video` shows
the code in action.
-.. _blocks_neo3_video:
+.. _blocks_neo3:
-neo3.pru0.c - Simple animation
+.. literalinclude:: code/neo3.pru0.c
+ :caption: neo3.pru0.c - Code to animate a red pixel running around a ring of blue
+ :linenos:
-:download:`ring_around.mp4 <figures/ring_around.mp4>`
+:download:`neo3.pru0.c <code/neo3.pru0.c>`
-.. _blocks_neo3:
+.. _blocks_neo3_video:
-neo3.pru0.c - Code to animate a red pixel running around a ring of blue
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Neo3 Video
+-----------
-:download:`neo3.pru0.c <code/neo3.pru0.c>`
+:download:`neo3.pru0.c - Simple animation <figures/ring_around.mp4>`
Discussion
-----------
-Here's the highlights.
-
-.. table::
+.. table:: Here's the highlights.
+-----+---------------------------------+
|Line |Explanation |
- +=====|=================================+
+ +=====+=================================+
|32,33|Initiallize the array of colors. |
+-----+---------------------------------+
|38-41|Update the array. |
@@ -1558,7 +1532,7 @@ Here's the highlights.
+-----+---------------------------------+
Controlling NeoPixels Through a Kernel Driver
-======================================
+*************************************************
Problem
-----------
@@ -1576,8 +1550,9 @@ an example.
.. _blocks_neo4:
-neo4.pru0.c - Code to talk to the PRU via rpmsg_pru
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/neo4.pru0.c
+ :caption: neo4.pru0.c - Code to talk to the PRU via rpmsg_pru
+ :linenos:
:download:`neo4.pru0.c <code/neo4.pru0.c>`
@@ -1614,32 +1589,41 @@ There's a lot here. I'll just hit some of the highlights in :ref:`blocks_neo4_l
.. _blocks_neo4_lines:
-Line-by-line for neo4.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
-
-|Line |Explanation
-
-|30 |The `CHAN_NAME` of `rpmsg-pru` matches that `prmsg_pru` driver that is
-is already installed. This connects this PRU to the driver.
-|32 |The `CHAN_PORT` tells it to use port 30. That's why we use
-`/dev/rpmsg_pru30`
-|40 |`payload[]` is the buffer that receives the data from the ARM.
-|42-48|Same as the previous NeoPixel examples.
-|52 |`color[]` is the state to be sent to the LEDs.
-|66-68|`color[]` is initialized.
-|70-85|Here are a number of details needed to set up the channel between
-the PRU and the ARM.
-|88 |Here we wait until the ARM sends us some numbers.
-|99 |Receive all the data from the ARM, store it in `payload[]`.
-|101-111|The data sent is: index red green blue. Pull off the index. If it's
-in the right range, pull off the red, green and blue values.
-|113 |The NeoPixels want the data in GRB order. Shift and OR everything
-together.
-|116-133|If the `index` = -1, send the contents of `color` to the LEDs. This
-code is same as before.
-|====
+.. table:: Line-by-line for neo4.pru0.c
+
+ +---------+---------------------------------------------------------------------------+
+ |Line | Explanation |
+ +=========+===========================================================================+
+ |30 | The `CHAN_NAME` of `rpmsg-pru` matches that `prmsg_pru` driver that is |
+ | | is already installed. This connects this PRU to the driver. |
+ +---------+---------------------------------------------------------------------------+
+ |32 | The `CHAN_PORT` tells it to use port 30. That's why we use |
+ | | `/dev/rpmsg_pru30` |
+ +---------+---------------------------------------------------------------------------+
+ |40 | `payload[]` is the buffer that receives the data from the ARM. |
+ +---------+---------------------------------------------------------------------------+
+ |42-48 | Same as the previous NeoPixel examples. |
+ +---------+---------------------------------------------------------------------------+
+ |52 | `color[]` is the state to be sent to the LEDs. |
+ +---------+---------------------------------------------------------------------------+
+ |66-68 | `color[]` is initialized. |
+ +---------+---------------------------------------------------------------------------+
+ |70-85 | Here are a number of details needed to set up the channel between |
+ | | the PRU and the ARM. |
+ +---------+---------------------------------------------------------------------------+
+ |88 | Here we wait until the ARM sends us some numbers. |
+ +---------+---------------------------------------------------------------------------+
+ |99 | Receive all the data from the ARM, store it in `payload[]`. |
+ +---------+---------------------------------------------------------------------------+
+ |101-111 | The data sent is: index red green blue. Pull off the index. If it's |
+ | | in the right range, pull off the red, green and blue values. |
+ +---------+---------------------------------------------------------------------------+
+ |113 | The NeoPixels want the data in GRB order. Shift and OR everything |
+ | | together. |
+ +---------+---------------------------------------------------------------------------+
+ |116-133 | If the `index` = -1, send the contents of `color` to the LEDs. This |
+ | | code is same as before. |
+ +---------+---------------------------------------------------------------------------+
You can now use programs running on the ARM to send colors to the PRU.
@@ -1647,8 +1631,9 @@ You can now use programs running on the ARM to send colors to the PRU.
.. _blocks_neo-rainbow:
-neo-rainbow.py - A python program using /dev/rpmsg_pru30
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/neo-rainbow.py
+ :caption: neo-rainbow.py - A python program using /dev/rpmsg_pru30
+ :linenos:
:download:`neo-rainbow.py <code/neo-rainbow.py>`
@@ -1659,7 +1644,6 @@ the last number, or you numbers will get blurred together.
Switching from pru0 to pru1 with rpmsg_pru
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
There are three things you need to change when switching from pru0 to pru1
when using rpmsg_pru.
@@ -1675,14 +1659,13 @@ when using rpmsg_pru.
These changes switch to the proper channel numbers to use pru1 instead of pru0.
RGB LED Matrix - No Integrated Drivers
-======================================
-
+***************************************
Problem
-----------
You have a RGB LED matrix
-(:ref:`../01case/case.html#case_rgb_matrix, 1.4. RGB LED Matrix - No Integrated Drivers`) and want to know
+(:ref:`case_rgb_matrix`) and want to know
at a low level how the PRU works.
Solution
@@ -1735,8 +1718,9 @@ high-level view of how to drive the display.
.. _blocks_rgb_python:
-rgb_python.py - Python code for driving RGB LED matrix
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/rgb_python.py
+ :caption: rgb_python.py - Python code for driving RGB LED matrix
+ :linenos:
:download:`rgb_python.py <code/rgb_python.py>`
@@ -1744,8 +1728,9 @@ Be sure to run the :ref:`blocks_rgb_setup` script before running the python code
.. _blocks_rgb_setup:
-rgb_python_setup.sh
-~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/rgb_python_setup.sh
+ :caption: rgb_python_setup.sh
+ :linenos:
:download:`rgb_python_setup.sh <code/rgb_python_setup.sh>`
@@ -1762,26 +1747,27 @@ Your display should look like :ref:`blocks_rgb_python_jpg`.
.. _blocks_rgb_python_jpg:
-Display running rgb_python.py
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/rgb_python.jpg
:align: center
:alt: Display running rgb_python.py
+ Display running rgb_python.py
+
So why do only two lines appear at a time? That's how the display works.
Currently lines 6 and 22 are showing, then a moment later 7 and 23 show, etc.
The display can only display two lines at a time, so it cycles through all the
lines. Unfortunately, python is too slow to make the display appear
all at once. Here's where the PRU comes in.
-:ref:``blocks_rgb1`` is the PRU code to drive the RGB LED matrix. Be sure to run
-``bone$ source rgb_setup.sh`` first.
+:ref:``blocks_rgb1`` is the PRU code to drive the RGB LED matrix.
+Be sure to run ``bone$ source rgb_setup.sh`` first.
.. _blocks_rgb1:
-PRU code for driving the RGB LED matrix
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: code/rgb1.pru0.c
+ :caption: PRU code for driving the RGB LED matrix
+ :linenos:
:download:`rgb1.pru0.c <code/rgb1.pru0.c>`
@@ -1790,33 +1776,31 @@ The results are shown in :ref:`blocks_rgb_pru`.
.. _blocks_rgb_pru:
-Display running rgb1.c on PRU 0
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/rgb_pru.jpg
:align: center
:alt: Display running rgb1.pru0.c on PRU 0
+ Display running rgb1.c on PRU 0
+
The PRU is fast enough to quickly write to the display so that it appears
as if all the LEDs are on at once.
Discussion
-----------
-There are a lot of details needed to make this simple display work. Let's
-go over some of them.
+There are a lot of details needed to make this simple display work.
+Let's go over some of them.
First, the connector looks like :ref:`blocks_matrix_j1`.
.. _blocks_matrix_j1:
-RGB Matrix J1 connector
-~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/matrix_j1.jpg
:align: center
:alt: RGB Matrix J1 connector, 200
+ RGB Matrix J1 connector
+
Notice the labels on the connect match the labels in the code.
:ref:`blocks_pocket_scroller_pins` shows how the pins on the display are
mapped to the pins on the Pocket Beagle.
@@ -1826,10 +1810,7 @@ mapped to the pins on the Pocket Beagle.
.. _blocks_pocket_scroller_pins:
-PocketScroller pin table
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: PocketScroller pin table
+-----------------+---------------+------------------------+------------------+-------------------+
|J1 Connector Pin |Pocket Headers |gpio port and bit number|Linux gpio number |PRU R30 bit number |
@@ -1870,12 +1851,11 @@ https://docs.google.com/spreadsheets/d/1FRGvYOyW1RiNSEVprvstfJAVeapnASgDXHtxeDOj
.. _blocks_rgb_waveforms:
-Oscilloscope display of CLK, OE, LAT and R1
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/rgb_waveforms.png
:align: center
- :alt: .Oscilloscope display of CLK, OE, LAT and R1
+ :alt: Oscilloscope display of CLK, OE, LAT and R1
+
+ Oscilloscope display of CLK, OE, LAT and R1
The top waveform is the CLK, the next is OE, followed by LAT and finally R1.
The OE (output enable) is active low, so most of the time the display is visible.
@@ -1883,9 +1863,7 @@ The sequence is:
* Put data on the R1, G1, B1, R2, G2 and B2 lines
* Toggle the clock.
-* Repeat the first two steps as one row of data is transfered. There are
-384 LEDs (2 rows of 32 RGB LEDs times 3 LED per RGB), but we are clocking in
-six bits (R1, G1, etc.) at a time, so 384/6=64 values need to be clocked in.
+* Repeat the first two steps as one row of data is transfered. There are 384 LEDs (2 rows of 32 RGB LEDs times 3 LED per RGB), but we are clocking in six bits (R1, G1, etc.) at a time, so 384/6=64 values need to be clocked in.
* Once all the values are in, disable the display (OE goes high)
* Then toggle the latch (LAT) to latch the new data.
* Turn the display back on.
@@ -1901,13 +1879,12 @@ comparision.
.. _blocks_rgb_fpp:
-FPP waveforms
-~~~~~~~~~~~~~~
-
.. figure:: figures/rgb_fpp.png
:align: center
:alt: FPP waveforms
+ FPP waveforms
+
Getting More Colors
~~~~~~~~~~~~~~~~~~~~~
@@ -1927,7 +1904,7 @@ The Adafruit description goes on to say:
This is what FPP does, but it's beyond the scope of this project.
Compiling and Inserting rpmsg_pru
-======================================
+***********************************
Problem
-----------
@@ -1970,8 +1947,9 @@ It's now installed and ready to go.
Copyright
==========
-copyright.c
-~~~~~~~~~~~~~
+.. literalinclude:: code/copyright.c
+ :caption: copyright.c
+ :linenos:
:download:`copyright.c <code/copyright.c>`
diff --git a/books/pru-cookbook/06io/io.html b/books/pru-cookbook/06io/io.html
deleted file mode 100644
index 5bb5425db9ef3699741ac9d74701f36aac6519b4..0000000000000000000000000000000000000000
--- a/books/pru-cookbook/06io/io.html
+++ /dev/null
@@ -1,1003 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.8">
-<title>Accessing More I/O</title>
-<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
-<style>
-/* Asciidoctor default stylesheet | MIT License | http://asciidoctor.org */
-/* Uncomment @import statement below to use as custom stylesheet */
-/*@import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700";*/
-article,aside,details,figcaption,figure,footer,header,hgroup,main,nav,section,summary{display:block}
-audio,canvas,video{display:inline-block}
-audio:not([controls]){display:none;height:0}
-script{display:none!important}
-html{font-family:sans-serif;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%}
-a{background:transparent}
-a:focus{outline:thin dotted}
-a:active,a:hover{outline:0}
-h1{font-size:2em;margin:.67em 0}
-abbr[title]{border-bottom:1px dotted}
-b,strong{font-weight:bold}
-dfn{font-style:italic}
-hr{-moz-box-sizing:content-box;box-sizing:content-box;height:0}
-mark{background:#ff0;color:#000}
-code,kbd,pre,samp{font-family:monospace;font-size:1em}
-pre{white-space:pre-wrap}
-q{quotes:"\201C" "\201D" "\2018" "\2019"}
-small{font-size:80%}
-sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
-sup{top:-.5em}
-sub{bottom:-.25em}
-img{border:0}
-svg:not(:root){overflow:hidden}
-figure{margin:0}
-fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
-legend{border:0;padding:0}
-button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
-button,input{line-height:normal}
-button,select{text-transform:none}
-button,html input[type="button"],input[type="reset"],input[type="submit"]{-webkit-appearance:button;cursor:pointer}
-button[disabled],html input[disabled]{cursor:default}
-input[type="checkbox"],input[type="radio"]{box-sizing:border-box;padding:0}
-button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
-textarea{overflow:auto;vertical-align:top}
-table{border-collapse:collapse;border-spacing:0}
-*,*::before,*::after{-moz-box-sizing:border-box;-webkit-box-sizing:border-box;box-sizing:border-box}
-html,body{font-size:100%}
-body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;font-weight:400;font-style:normal;line-height:1;position:relative;cursor:auto;tab-size:4;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
-a:hover{cursor:pointer}
-img,object,embed{max-width:100%;height:auto}
-object,embed{height:100%}
-img{-ms-interpolation-mode:bicubic}
-.left{float:left!important}
-.right{float:right!important}
-.text-left{text-align:left!important}
-.text-right{text-align:right!important}
-.text-center{text-align:center!important}
-.text-justify{text-align:justify!important}
-.hide{display:none}
-img,object,svg{display:inline-block;vertical-align:middle}
-textarea{height:auto;min-height:50px}
-select{width:100%}
-.center{margin-left:auto;margin-right:auto}
-.stretch{width:100%}
-.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
-div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0;direction:ltr}
-a{color:#2156a5;text-decoration:underline;line-height:inherit}
-a:hover,a:focus{color:#1d4b8f}
-a img{border:none}
-p{font-family:inherit;font-weight:400;font-size:1em;line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
-p aside{font-size:.875em;line-height:1.35;font-style:italic}
-h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
-h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
-h1{font-size:2.125em}
-h2{font-size:1.6875em}
-h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
-h4,h5{font-size:1.125em}
-h6{font-size:1em}
-hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em;height:0}
-em,i{font-style:italic;line-height:inherit}
-strong,b{font-weight:bold;line-height:inherit}
-small{font-size:60%;line-height:inherit}
-code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
-ul,ol,dl{font-size:1em;line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
-ul,ol{margin-left:1.5em}
-ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0;font-size:1em}
-ul.square li ul,ul.circle li ul,ul.disc li ul{list-style:inherit}
-ul.square{list-style-type:square}
-ul.circle{list-style-type:circle}
-ul.disc{list-style-type:disc}
-ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
-dl dt{margin-bottom:.3125em;font-weight:bold}
-dl dd{margin-bottom:1.25em}
-abbr,acronym{text-transform:uppercase;font-size:90%;color:rgba(0,0,0,.8);border-bottom:1px dotted #ddd;cursor:help}
-abbr{text-transform:none}
-blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
-blockquote cite{display:block;font-size:.9375em;color:rgba(0,0,0,.6)}
-blockquote cite::before{content:"\2014 \0020"}
-blockquote cite a,blockquote cite a:visited{color:rgba(0,0,0,.6)}
-blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
-@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
-h1{font-size:2.75em}
-h2{font-size:2.3125em}
-h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
-h4{font-size:1.4375em}}
-table{background:#fff;margin-bottom:1.25em;border:solid 1px #dedede}
-table thead,table tfoot{background:#f7f8f7}
-table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
-table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
-table tr.even,table tr.alt,table tr:nth-of-type(even){background:#f8f8f7}
-table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
-h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
-h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
-.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
-.clearfix::after,.float-group::after{clear:both}
-*:not(pre)>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background-color:#f7f7f8;-webkit-border-radius:4px;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed;word-wrap:break-word}
-*:not(pre)>code.nobreak{word-wrap:normal}
-*:not(pre)>code.nowrap{white-space:nowrap}
-pre,pre>code{line-height:1.45;color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;text-rendering:optimizeSpeed}
-em em{font-style:normal}
-strong strong{font-weight:400}
-.keyseq{color:rgba(51,51,51,.8)}
-kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background-color:#f7f7f7;border:1px solid #ccc;-webkit-border-radius:3px;border-radius:3px;-webkit-box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em white inset;box-shadow:0 1px 0 rgba(0,0,0,.2),0 0 0 .1em #fff inset;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
-.keyseq kbd:first-child{margin-left:0}
-.keyseq kbd:last-child{margin-right:0}
-.menuseq,.menuref{color:#000}
-.menuseq b:not(.caret),.menuref{font-weight:inherit}
-.menuseq{word-spacing:-.02em}
-.menuseq b.caret{font-size:1.25em;line-height:.8}
-.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
-b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
-b.button::before{content:"[";padding:0 3px 0 2px}
-b.button::after{content:"]";padding:0 2px 0 3px}
-p a>code:hover{color:rgba(0,0,0,.9)}
-#header,#content,#footnotes,#footer{width:100%;margin-left:auto;margin-right:auto;margin-top:0;margin-bottom:0;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
-#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
-#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
-#content{margin-top:1.25em}
-#content::before{content:none}
-#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
-#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
-#header>h1:only-child,body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
-#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:-ms-flexbox;display:-webkit-flex;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap}
-#header .details span:first-child{margin-left:-.125em}
-#header .details span.email a{color:rgba(0,0,0,.85)}
-#header .details br{display:none}
-#header .details br+span::before{content:"\00a0\2013\00a0"}
-#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
-#header .details br+span#revremark::before{content:"\00a0|\00a0"}
-#header #revnumber{text-transform:capitalize}
-#header #revnumber::after{content:"\00a0"}
-#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
-#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
-#toc>ul{margin-left:.125em}
-#toc ul.sectlevel0>li>a{font-style:italic}
-#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
-#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
-#toc li{line-height:1.3334;margin-top:.3334em}
-#toc a{text-decoration:none}
-#toc a:active{text-decoration:underline}
-#toctitle{color:#7a2518;font-size:1.2em}
-@media screen and (min-width:768px){#toctitle{font-size:1.375em}
-body.toc2{padding-left:15em;padding-right:0}
-#toc.toc2{margin-top:0!important;background-color:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
-#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
-#toc.toc2>ul{font-size:.9em;margin-bottom:0}
-#toc.toc2 ul ul{margin-left:0;padding-left:1em}
-#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
-body.toc2.toc-right{padding-left:0;padding-right:15em}
-body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
-@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
-#toc.toc2{width:20em}
-#toc.toc2 #toctitle{font-size:1.375em}
-#toc.toc2>ul{font-size:.95em}
-#toc.toc2 ul ul{padding-left:1.25em}
-body.toc2.toc-right{padding-left:0;padding-right:20em}}
-#content #toc{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
-#content #toc>:first-child{margin-top:0}
-#content #toc>:last-child{margin-bottom:0}
-#footer{max-width:100%;background-color:rgba(0,0,0,.8);padding:1.25em}
-#footer-text{color:rgba(255,255,255,.8);line-height:1.44}
-#content{margin-bottom:.625em}
-.sect1{padding-bottom:.625em}
-@media screen and (min-width:768px){#content{margin-bottom:1.25em}
-.sect1{padding-bottom:1.25em}}
-.sect1:last-child{padding-bottom:0}
-.sect1+.sect1{border-top:1px solid #e7e7e9}
-#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
-#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
-#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
-#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
-#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
-.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
-.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
-table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
-.paragraph.lead>p,#preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
-table.tableblock #preamble>.sectionbody>[class="paragraph"]:first-of-type p{font-size:inherit}
-.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
-.admonitionblock>table td.icon{text-align:center;width:80px}
-.admonitionblock>table td.icon img{max-width:none}
-.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
-.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6)}
-.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
-.exampleblock>.content{border-style:solid;border-width:1px;border-color:#e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;-webkit-border-radius:4px;border-radius:4px}
-.exampleblock>.content>:first-child{margin-top:0}
-.exampleblock>.content>:last-child{margin-bottom:0}
-.sidebarblock{border-style:solid;border-width:1px;border-color:#e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;-webkit-border-radius:4px;border-radius:4px}
-.sidebarblock>:first-child{margin-top:0}
-.sidebarblock>:last-child{margin-bottom:0}
-.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
-.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
-.literalblock pre,.listingblock pre:not(.highlight),.listingblock pre[class="highlight"],.listingblock pre[class^="highlight "],.listingblock pre.CodeRay,.listingblock pre.prettyprint{background:#f7f7f8}
-.sidebarblock .literalblock pre,.sidebarblock .listingblock pre:not(.highlight),.sidebarblock .listingblock pre[class="highlight"],.sidebarblock .listingblock pre[class^="highlight "],.sidebarblock .listingblock pre.CodeRay,.sidebarblock .listingblock pre.prettyprint{background:#f2f1f1}
-.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{-webkit-border-radius:4px;border-radius:4px;word-wrap:break-word;overflow-x:auto;padding:1em;font-size:.8125em}
-@media screen and (min-width:768px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:.90625em}}
-@media screen and (min-width:1280px){.literalblock pre,.literalblock pre[class],.listingblock pre,.listingblock pre[class]{font-size:1em}}
-.literalblock pre.nowrap,.literalblock pre.nowrap pre,.listingblock pre.nowrap,.listingblock pre.nowrap pre{white-space:pre;word-wrap:normal}
-.literalblock.output pre{color:#f7f7f8;background-color:rgba(0,0,0,.9)}
-.listingblock pre.highlightjs{padding:0}
-.listingblock pre.highlightjs>code{padding:1em;-webkit-border-radius:4px;border-radius:4px}
-.listingblock pre.prettyprint{border-width:0}
-.listingblock>.content{position:relative}
-.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:#999}
-.listingblock:hover code[data-lang]::before{display:block}
-.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:#999}
-.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
-table.pyhltable{border-collapse:separate;border:0;margin-bottom:0;background:none}
-table.pyhltable td{vertical-align:top;padding-top:0;padding-bottom:0;line-height:1.45}
-table.pyhltable td.code{padding-left:.75em;padding-right:0}
-pre.pygments .lineno,table.pyhltable td:not(.code){color:#999;padding-left:0;padding-right:.5em;border-right:1px solid #dddddf}
-pre.pygments .lineno{display:inline-block;margin-right:.25em}
-table.pyhltable .linenodiv{background:none!important;padding-right:0!important}
-.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
-.quoteblock>.title{margin-left:-1.5em;margin-bottom:.75em}
-.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
-.quoteblock blockquote{margin:0;padding:0;border:0}
-.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
-.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
-.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
-.verseblock{margin:0 1em 1.25em}
-.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
-.verseblock pre strong{font-weight:400}
-.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
-.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
-.quoteblock .attribution br,.verseblock .attribution br{display:none}
-.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
-.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
-.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
-.quoteblock.abstract{margin:0 1em 1.25em;display:block}
-.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
-.quoteblock.excerpt,.quoteblock .quoteblock{margin:0 0 1.25em;padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
-.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
-.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;text-align:left;margin-right:0}
-table.tableblock{max-width:100%;border-collapse:separate}
-p.tableblock:last-child{margin-bottom:0}
-td.tableblock>.content{margin-bottom:-1.25em}
-table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
-table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
-table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
-table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
-table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
-table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
-table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
-table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
-table.frame-all{border-width:1px}
-table.frame-sides{border-width:0 1px}
-table.frame-topbot,table.frame-ends{border-width:1px 0}
-table.stripes-all tr,table.stripes-odd tr:nth-of-type(odd){background:#f8f8f7}
-table.stripes-none tr,table.stripes-odd tr:nth-of-type(even){background:none}
-th.halign-left,td.halign-left{text-align:left}
-th.halign-right,td.halign-right{text-align:right}
-th.halign-center,td.halign-center{text-align:center}
-th.valign-top,td.valign-top{vertical-align:top}
-th.valign-bottom,td.valign-bottom{vertical-align:bottom}
-th.valign-middle,td.valign-middle{vertical-align:middle}
-table thead th,table tfoot th{font-weight:bold}
-tbody tr th{display:table-cell;line-height:1.6;background:#f7f8f7}
-tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
-p.tableblock>code:only-child{background:none;padding:0}
-p.tableblock{font-size:1em}
-td>div.verse{white-space:pre}
-ol{margin-left:1.75em}
-ul li ol{margin-left:1.5em}
-dl dd{margin-left:1.125em}
-dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
-ol>li p,ul>li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
-ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
-ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
-ul.unstyled,ol.unstyled{margin-left:0}
-ul.checklist{margin-left:.625em}
-ul.checklist li>p:first-child>.fa-square-o:first-child,ul.checklist li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
-ul.checklist li>p:first-child>input[type="checkbox"]:first-child{margin-right:.25em}
-ul.inline{display:-ms-flexbox;display:-webkit-box;display:flex;-ms-flex-flow:row wrap;-webkit-flex-flow:row wrap;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
-ul.inline>li{margin-left:1.25em}
-.unstyled dl dt{font-weight:400;font-style:normal}
-ol.arabic{list-style-type:decimal}
-ol.decimal{list-style-type:decimal-leading-zero}
-ol.loweralpha{list-style-type:lower-alpha}
-ol.upperalpha{list-style-type:upper-alpha}
-ol.lowerroman{list-style-type:lower-roman}
-ol.upperroman{list-style-type:upper-roman}
-ol.lowergreek{list-style-type:lower-greek}
-.hdlist>table,.colist>table{border:0;background:none}
-.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
-td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
-td.hdlist1{font-weight:bold;padding-bottom:1.25em}
-.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
-.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
-.colist td:not([class]):first-child img{max-width:none}
-.colist td:not([class]):last-child{padding:.25em 0}
-.thumb,.th{line-height:0;display:inline-block;border:solid 4px #fff;-webkit-box-shadow:0 0 0 1px #ddd;box-shadow:0 0 0 1px #ddd}
-.imageblock.left{margin:.25em .625em 1.25em 0}
-.imageblock.right{margin:.25em 0 1.25em .625em}
-.imageblock>.title{margin-bottom:0}
-.imageblock.thumb,.imageblock.th{border-width:6px}
-.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
-.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
-.image.left{margin-right:.625em}
-.image.right{margin-left:.625em}
-a.image{text-decoration:none;display:inline-block}
-a.image object{pointer-events:none}
-sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
-sup.footnote a,sup.footnoteref a{text-decoration:none}
-sup.footnote a:active,sup.footnoteref a:active{text-decoration:underline}
-#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
-#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
-#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
-#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
-#footnotes .footnote:last-of-type{margin-bottom:0}
-#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
-.gist .file-data>table{border:0;background:#fff;width:100%;margin-bottom:0}
-.gist .file-data>table td.line-data{width:99%}
-div.unbreakable{page-break-inside:avoid}
-.big{font-size:larger}
-.small{font-size:smaller}
-.underline{text-decoration:underline}
-.overline{text-decoration:overline}
-.line-through{text-decoration:line-through}
-.aqua{color:#00bfbf}
-.aqua-background{background-color:#00fafa}
-.black{color:#000}
-.black-background{background-color:#000}
-.blue{color:#0000bf}
-.blue-background{background-color:#0000fa}
-.fuchsia{color:#bf00bf}
-.fuchsia-background{background-color:#fa00fa}
-.gray{color:#606060}
-.gray-background{background-color:#7d7d7d}
-.green{color:#006000}
-.green-background{background-color:#007d00}
-.lime{color:#00bf00}
-.lime-background{background-color:#00fa00}
-.maroon{color:#600000}
-.maroon-background{background-color:#7d0000}
-.navy{color:#000060}
-.navy-background{background-color:#00007d}
-.olive{color:#606000}
-.olive-background{background-color:#7d7d00}
-.purple{color:#600060}
-.purple-background{background-color:#7d007d}
-.red{color:#bf0000}
-.red-background{background-color:#fa0000}
-.silver{color:#909090}
-.silver-background{background-color:#bcbcbc}
-.teal{color:#006060}
-.teal-background{background-color:#007d7d}
-.white{color:#bfbfbf}
-.white-background{background-color:#fafafa}
-.yellow{color:#bfbf00}
-.yellow-background{background-color:#fafa00}
-span.icon>.fa{cursor:default}
-a span.icon>.fa{cursor:inherit}
-.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
-.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
-.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
-.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
-.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
-.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
-.conum[data-value]{display:inline-block;color:#fff!important;background-color:rgba(0,0,0,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
-.conum[data-value] *{color:#fff!important}
-.conum[data-value]+b{display:none}
-.conum[data-value]::after{content:attr(data-value)}
-pre .conum[data-value]{position:relative;top:-.125em}
-b.conum *{color:inherit!important}
-.conum:not([data-value]):empty{display:none}
-dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
-h1,h2,p,td.content,span.alt{letter-spacing:-.01em}
-p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
-p,blockquote,dt,td.content,span.alt{font-size:1.0625rem}
-p{margin-bottom:1.25rem}
-.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
-.exampleblock>.content{background-color:#fffef7;border-color:#e0e0dc;-webkit-box-shadow:0 1px 4px #e0e0dc;box-shadow:0 1px 4px #e0e0dc}
-.print-only{display:none!important}
-@page{margin:1.25cm .75cm}
-@media print{*{-webkit-box-shadow:none!important;box-shadow:none!important;text-shadow:none!important}
-html{font-size:80%}
-a{color:inherit!important;text-decoration:underline!important}
-a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
-a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
-abbr[title]::after{content:" (" attr(title) ")"}
-pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
-thead{display:table-header-group}
-svg{max-width:100%}
-p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
-h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
-#toc,.sidebarblock,.exampleblock>.content{background:none!important}
-#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
-body.book #header{text-align:center}
-body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
-body.book #header .details{border:0!important;display:block;padding:0!important}
-body.book #header .details span:first-child{margin-left:0!important}
-body.book #header .details br{display:block}
-body.book #header .details br+span::before{content:none!important}
-body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
-body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
-.listingblock code[data-lang]::before{display:block}
-#footer{padding:0 .9375em}
-.hide-on-print{display:none!important}
-.print-only{display:block!important}
-.hide-for-print{display:none!important}
-.show-for-print{display:inherit!important}}
-@media print,amzn-kf8{#header>h1:first-child{margin-top:1.25rem}
-.sect1{padding:0!important}
-.sect1+.sect1{border:0}
-#footer{background:none}
-#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
-@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
-</style>
-<style>
-/* Stylesheet for CodeRay to match GitHub theme | MIT License | http://foundation.zurb.com */
-/*pre.CodeRay {background-color:#f7f7f8;}*/
-.CodeRay .line-numbers{border-right:1px solid #d8d8d8;padding:0 0.5em 0 .25em}
-.CodeRay span.line-numbers{display:inline-block;margin-right:.5em;color:rgba(0,0,0,.3)}
-.CodeRay .line-numbers strong{color:rgba(0,0,0,.4)}
-table.CodeRay{border-collapse:separate;border-spacing:0;margin-bottom:0;border:0;background:none}
-table.CodeRay td{vertical-align: top;line-height:1.45}
-table.CodeRay td.line-numbers{text-align:right}
-table.CodeRay td.line-numbers>pre{padding:0;color:rgba(0,0,0,.3)}
-table.CodeRay td.code{padding:0 0 0 .5em}
-table.CodeRay td.code>pre{padding:0}
-.CodeRay .debug{color:#fff !important;background:#000080 !important}
-.CodeRay .annotation{color:#007}
-.CodeRay .attribute-name{color:#000080}
-.CodeRay .attribute-value{color:#700}
-.CodeRay .binary{color:#509}
-.CodeRay .comment{color:#998;font-style:italic}
-.CodeRay .char{color:#04d}
-.CodeRay .char .content{color:#04d}
-.CodeRay .char .delimiter{color:#039}
-.CodeRay .class{color:#458;font-weight:bold}
-.CodeRay .complex{color:#a08}
-.CodeRay .constant,.CodeRay .predefined-constant{color:#008080}
-.CodeRay .color{color:#099}
-.CodeRay .class-variable{color:#369}
-.CodeRay .decorator{color:#b0b}
-.CodeRay .definition{color:#099}
-.CodeRay .delimiter{color:#000}
-.CodeRay .doc{color:#970}
-.CodeRay .doctype{color:#34b}
-.CodeRay .doc-string{color:#d42}
-.CodeRay .escape{color:#666}
-.CodeRay .entity{color:#800}
-.CodeRay .error{color:#808}
-.CodeRay .exception{color:inherit}
-.CodeRay .filename{color:#099}
-.CodeRay .function{color:#900;font-weight:bold}
-.CodeRay .global-variable{color:#008080}
-.CodeRay .hex{color:#058}
-.CodeRay .integer,.CodeRay .float{color:#099}
-.CodeRay .include{color:#555}
-.CodeRay .inline{color:#000}
-.CodeRay .inline .inline{background:#ccc}
-.CodeRay .inline .inline .inline{background:#bbb}
-.CodeRay .inline .inline-delimiter{color:#d14}
-.CodeRay .inline-delimiter{color:#d14}
-.CodeRay .important{color:#555;font-weight:bold}
-.CodeRay .interpreted{color:#b2b}
-.CodeRay .instance-variable{color:#008080}
-.CodeRay .label{color:#970}
-.CodeRay .local-variable{color:#963}
-.CodeRay .octal{color:#40e}
-.CodeRay .predefined{color:#369}
-.CodeRay .preprocessor{color:#579}
-.CodeRay .pseudo-class{color:#555}
-.CodeRay .directive{font-weight:bold}
-.CodeRay .type{font-weight:bold}
-.CodeRay .predefined-type{color:inherit}
-.CodeRay .reserved,.CodeRay .keyword {color:#000;font-weight:bold}
-.CodeRay .key{color:#808}
-.CodeRay .key .delimiter{color:#606}
-.CodeRay .key .char{color:#80f}
-.CodeRay .value{color:#088}
-.CodeRay .regexp .delimiter{color:#808}
-.CodeRay .regexp .content{color:#808}
-.CodeRay .regexp .modifier{color:#808}
-.CodeRay .regexp .char{color:#d14}
-.CodeRay .regexp .function{color:#404;font-weight:bold}
-.CodeRay .string{color:#d20}
-.CodeRay .string .string .string{background:#ffd0d0}
-.CodeRay .string .content{color:#d14}
-.CodeRay .string .char{color:#d14}
-.CodeRay .string .delimiter{color:#d14}
-.CodeRay .shell{color:#d14}
-.CodeRay .shell .delimiter{color:#d14}
-.CodeRay .symbol{color:#990073}
-.CodeRay .symbol .content{color:#a60}
-.CodeRay .symbol .delimiter{color:#630}
-.CodeRay .tag{color:#008080}
-.CodeRay .tag-special{color:#d70}
-.CodeRay .variable{color:#036}
-.CodeRay .insert{background:#afa}
-.CodeRay .delete{background:#faa}
-.CodeRay .change{color:#aaf;background:#007}
-.CodeRay .head{color:#f8f;background:#505}
-.CodeRay .insert .insert{color:#080}
-.CodeRay .delete .delete{color:#800}
-.CodeRay .change .change{color:#66f}
-.CodeRay .head .head{color:#f4f}
-</style>
-</head>
-<body class="article">
-<div id="header">
-<div id="toc" class="toc">
-<div id="toctitle">Table of Contents</div>
-<ul class="sectlevel1">
-<li><a href="#_accessing_more_io">1. Accessing More I/O</a>
-<ul class="sectlevel2">
-<li><a href="#_editing_bootuenv_txt_to_access_the_p8_header_on_the_black">1.1. Editing /boot/uEnv.txt to Access the P8 Header on the Black</a></li>
-<li><a href="#_accessing_gpio">1.2. Accessing gpio</a></li>
-<li><a href="#io_uio">1.3. Configuring for UIO Instead of RemoteProc</a></li>
-<li><a href="#_converting_pasm_assembly_code_to_clpru">1.4. Converting pasm Assembly Code to clpru</a></li>
-</ul>
-</li>
-</ul>
-</div>
-</div>
-<div id="content">
-<div class="paragraph">
-<p><a href="../index.html">Outline</a></p>
-</div>
-<div class="sect1">
-<h2 id="_accessing_more_io"><a class="link" href="#_accessing_more_io">1. Accessing More I/O</a></h2>
-<div class="sectionbody">
-<div class="paragraph">
-<p>So far the examples have shown how to access the GPIO pins on the BeagleBone Black’s
-<code>P9</code> header and through the <code>__R30</code> register. Below shows how more GPIO pins
-can be accessed.</p>
-</div>
-<div class="paragraph">
-<p>The following are resources used in this chapter.</p>
-</div>
-<div class="ulist">
-<div class="title">Resources</div>
-<ul>
-<li>
-<p><a href="https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP8HeaderTable.pdf">P8 Header Table</a></p>
-</li>
-<li>
-<p><a href="https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf">P9 Header Table</a></p>
-</li>
-<li>
-<p><a href="http://www.ti.com/lit/pdf/spruhz6l">AM572x Technical Reference Manual</a> (AI)</p>
-</li>
-<li>
-<p><a href="http://www.ti.com/lit/pdf/spruh73">AM335x Technical Reference Manual</a> (All others)</p>
-</li>
-<li>
-<p><a href="http://www.ti.com/lit/ug/spruhv6a/spruhv6a.pdf">PRU Assembly Language Tools</a></p>
-</li>
-</ul>
-</div>
-<div class="sect2">
-<h3 id="_editing_bootuenv_txt_to_access_the_p8_header_on_the_black"><a class="link" href="#_editing_bootuenv_txt_to_access_the_p8_header_on_the_black">1.1. Editing /boot/uEnv.txt to Access the P8 Header on the Black</a></h3>
-<div class="sect3">
-<h4 id="_problem"><a class="link" href="#_problem">Problem</a></h4>
-<div class="paragraph">
-<p>When I try to configure some pins on the <code>P8</code> header of the Black I get an error.</p>
-</div>
-<div class="listingblock">
-<div class="title">config-pin</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">bone$ <strong>config-pin P8_28 pruout</strong>
-ERROR: open() for /sys/devices/platform/ocp/ocp:P8_28_pinmux/state failed, No such file or directory</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_solution"><a class="link" href="#_solution">Solution</a></h4>
-<div class="paragraph">
-<p>On the images for the BeagleBone Black, the HDMI display driver is enabled by
-default and uses many of the <code>P8</code> pins. If you are not using
-HDMI video (or the HDI audio, or even the eMMC) you can disable it by editing
-<code>/boot/uEnv.txt</code></p>
-</div>
-<div class="paragraph">
-<p>Open <code>/boot/uEnv.txt</code> and scroll down aways until you see:</p>
-</div>
-<div class="listingblock">
-<div class="title">/boot/uEnv.txt</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">###Disable auto loading of virtual capes (emmc/video/wireless/adc)
-#disable_uboot_overlay_emmc=1
-disable_uboot_overlay_video=1
-#disable_uboot_overlay_audio=1</code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Uncomment the lines that correspond to the devices you want to disable and
-free up their pins.</p>
-</div>
-<div class="admonitionblock tip">
-<table>
-<tr>
-<td class="icon">
-<div class="title">Tip</div>
-</td>
-<td class="content">
-<div class="paragraph">
-<p><a href="https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP8HeaderTable.pdf">P8 Header Table</a>
-shows what pins are allocated for what.</p>
-</div>
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>Save the file and reboot. You now have access to the <code>P8</code> pins.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_accessing_gpio"><a class="link" href="#_accessing_gpio">1.2. Accessing gpio</a></h3>
-<div class="sect3">
-<h4 id="_problem_2"><a class="link" href="#_problem_2">Problem</a></h4>
-<div class="paragraph">
-<p>I’ve used up all the GPIO in <code>__R30</code>, where can I get more?</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_solution_2"><a class="link" href="#_solution_2">Solution</a></h4>
-<div class="paragraph">
-<p>So far we have focused on using PRU 0.
-<a href="../05blocks/blocks.html#blocks_mapping_bits">Mapping bit positions to pin names
-PRU</a> shows
-that PRU 0 can access ten GPIO pins on the BeagleBone Black. If you use
-PRU 1 you can get to an additional 14 pins (if they aren’t in use for other things.)</p>
-</div>
-<div class="paragraph">
-<p>What if you need even more GPIO pins? You can access <em>any</em> GPIO pin by going
-through the <strong>O</strong>pen-<strong>C</strong>ore <strong>P</strong>rotocol (OCP) port.</p>
-</div>
-<div class="paragraph">
-<div class="title">PRU Integration</div>
-<p><span class="image"><img src="figures/pruIntegration.png" alt="PRU Integration"></span></p>
-</div>
-<div class="paragraph">
-<p>The figure above shows we’ve been using the <em>Enhanced GPIO</em> interface when using
-<code>__R30</code>, but it also shows you can use the OCP. You get access to many more
-GPIO pins, but it’s a slower access.</p>
-</div>
-<div class="listingblock">
-<div class="title">gpio.pru0.c</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="c"><table class="CodeRay"><tr>
- <td class="line-numbers"><pre>1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-</pre></td>
- <td class="code"><pre><span class="comment">// This code accesses GPIO without using R30 and R31</span>
-<span class="preprocessor">#include</span> <span class="include"><stdint.h></span>
-<span class="preprocessor">#include</span> <span class="include"><pru_cfg.h></span>
-<span class="preprocessor">#include</span> <span class="include">"resource_table_empty.h"</span>
-<span class="preprocessor">#include</span> <span class="include">"prugpio.h"</span>
-
-<span class="preprocessor">#define</span> P9_11 (<span class="hex">0x1</span><<<span class="integer">30</span>) <span class="comment">// Bit position tied to P9_11 on Black</span>
-<span class="preprocessor">#define</span> P2_05 (<span class="hex">0x1</span><<<span class="integer">30</span>) <span class="comment">// Bit position tied to P2_05 on Pocket</span>
-
-<span class="directive">volatile</span> <span class="directive">register</span> uint32_t __R30;
-<span class="directive">volatile</span> <span class="directive">register</span> uint32_t __R31;
-
-<span class="directive">void</span> main(<span class="directive">void</span>)
-{
- uint32_t *gpio0 = (uint32_t *)GPIO0;
-
- <span class="keyword">while</span>(<span class="integer">1</span>) {
- gpio0[GPIO_SETDATAOUT] = P9_11;
- __delay_cycles(<span class="integer">100000000</span>);
- gpio0[GPIO_CLEARDATAOUT] = P9_11;
- __delay_cycles(<span class="integer">100000000</span>);
- }
-}</pre></td>
-</tr></table></code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>This code will toggle <code>P9_11</code> on and off. Here’s the setup file.</p>
-</div>
-<div class="listingblock">
-<div class="title">setup.sh</div>
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash"><table class="CodeRay"><tr>
- <td class="line-numbers"><pre>1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26
-27
-28
-</pre></td>
- <td class="code"><pre>#!/bin/bash
-
-export TARGET=gpio.pru0
-echo TARGET=$TARGET
-
-# Configure the PRU pins based on which Beagle is running
-machine=$(awk '{print $NF}' /proc/device-tree/model)
-echo -n $machine
-if [ $machine = "Black" ]; then
- echo " Found"
- pins="P9_11"
-elif [ $machine = "Blue" ]; then
- echo " Found"
- pins=""
-elif [ $machine = "PocketBeagle" ]; then
- echo " Found"
- pins="P2_05"
-else
- echo " Not Found"
- pins=""
-fi
-
-for pin in $pins
-do
- echo $pin
- config-pin $pin gpio
- config-pin -q $pin
-done</pre></td>
-</tr></table></code></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Notice in the code <code>config-pin</code> set <code>P9_11</code> to <code>gpio</code>, not <code>pruout</code>. This is because
-are are using the OCP interface to the pin, not the usual PRU interface.</p>
-</div>
-<div class="paragraph">
-<p>Set your exports and make.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre class="CodeRay highlight"><code data-lang="bash">bone$ <strong>source setup.sh</strong>
-TARGET=gpio.pru0
-...
-bone$ <strong>make</strong>
-/var/lib/cloud9/common/Makefile:29: MODEL=TI_AM335x_BeagleBone_Black,TARGET=gpio.pru0
-- Stopping PRU 0
-- copying firmware file /tmp/cloud9-examples/gpio.pru0.out to /lib/firmware/am335x-pru0-fw
-write_init_pins.sh
-- Starting PRU 0
-MODEL = TI_AM335x_BeagleBone_Black
-PROC = pru
-PRUN = 0
-PRU_DIR = /sys/class/remoteproc/remoteproc1</code></pre>
-</div>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_discussion"><a class="link" href="#_discussion">Discussion</a></h4>
-<div class="paragraph">
-<p>When you run the code you see <code>P9_11</code> toggling on and off. Let’s go through
-the code line-by-line to see what’s happening.</p>
-</div>
-<table class="tableblock frame-all grid-all stretch">
-<caption class="title">Table 1. gpio.pru0.c line-by-line</caption>
-<colgroup>
-<col style="width: 10%;">
-<col style="width: 90%;">
-</colgroup>
-<thead>
-<tr>
-<th class="tableblock halign-left valign-top">Line</th>
-<th class="tableblock halign-left valign-top">Explanation</th>
-</tr>
-</thead>
-<tbody>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">2-5</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Standard includes</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">The AM335x has four 32-bit GPIO ports. Lines 55-58 of <code>prugpio.h</code> define the addresses
-for each of the ports. You can find these in Table 2-2 page 180 of the
-<a href="https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf">AM335x Technical Reference Manual</a>.
-Look up <code>P9_11</code> in the <a href="https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf">P9 Header Table</a>.
-Under the <em>Mode7</em> column you see <code>gpio0[30]</code>. This means <code>P9_11</code> is bit 30
-on GPIO port 0. Therefore we will use <code>GPIO0</code> in this code.</p>
-<p class="tableblock">You can also run
-<code>gpioinfo</code> and look for P9_11.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Line 103 of <code>prugpio.h</code> defines the address offset from <code>GIO0</code> that will
-allow us to <em>clear</em>
-any (or all) bits in GPIO port 0. Other architectures require you to read a port,
-then change some bit, then write it out again, three steps. Here we can do the same by writing to one location, just one step.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Line 104 of <code>prugpio.h</code> is like above, but for <em>setting</em> bits.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">5</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Using this offset of line 105 of <code>prugpio.h</code> lets us just read the bits
-without changing them.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">7,8</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">This shifts <code>0x1</code> to the 30<sup>th</sup> bit position, which is the one corresponding
-to <code>P9_11</code>.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">15</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Here we initialize <code>gpio0</code> to point to the start of GPIO port 0’s control
-registers.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">18</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock"><code>gpio0[GPIO_SETDATAOUT]</code> refers to the <code>SETDATAOUT</code> register of port 0.
-Writing to this register turns on the bits where 1’s are written,
-but leaves alone the bits where 0’s are.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">19</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">Wait 100,000,000 cycles, which is 0.5 seconds.</p></td>
-</tr>
-<tr>
-<td class="tableblock halign-left valign-top"><p class="tableblock">20</p></td>
-<td class="tableblock halign-left valign-top"><p class="tableblock">This is line 18, but the output bit is set to 0 where 1’s are written.</p></td>
-</tr>
-</tbody>
-</table>
-<div class="sect4">
-<h5 id="_how_fast_can_it_go"><a class="link" href="#_how_fast_can_it_go">How fast can it go?</a></h5>
-<div class="paragraph">
-<p>This approach to GPIO goes through the slower OCP interface. If you set <code>__delay_cycles(0)</code> you can see how fast it is.</p>
-</div>
-<div class="paragraph">
-<div class="title">gpio.pru0.c with __delay_cycles(0)</div>
-<p><span class="image"><img src="figures/gpio0delay.png" alt="gpio.pru0.c with __delay_cycles(0)"></span></p>
-</div>
-<div class="paragraph">
-<p>The period is 80ns which is 12.MHz. That’s about one forth the speed of the
-<code>__R30</code> method, but still not bad.</p>
-</div>
-<div class="paragraph">
-<p>If you are using an oscilloscope, look closely and you’ll see the following.</p>
-</div>
-<div class="paragraph">
-<div class="title">PWM with jitter</div>
-<p><span class="image"><img src="figures/jitter.png" alt="PWM with jitter"></span></p>
-</div>
-<div class="paragraph">
-<p>The PRU is still as solid as before in it’s timing, but now it’s going through
-the OCP interface. This interface is shared with other parts of the system,
-therefore the sometimes the PRU must wait for the other parts to finish.
-When this happens the pulse width is a bit longer than usual thus adding
-jitter to the output.</p>
-</div>
-<div class="paragraph">
-<p>For many applications a few nanoseconds of jitter is unimportant and this
-GPIO interface can be used. If your application needs better timing,
-use the <code>__R30</code> interface.</p>
-</div>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="io_uio"><a class="link" href="#io_uio">1.3. Configuring for UIO Instead of RemoteProc</a></h3>
-<div class="sect3">
-<h4 id="_problem_3"><a class="link" href="#_problem_3">Problem</a></h4>
-<div class="paragraph">
-<p>You have some legacy PRU code that uses UIO instead of remoteproc and
-you want to switch to UIO.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_solution_3"><a class="link" href="#_solution_3">Solution</a></h4>
-<div class="paragraph">
-<p>Edit <code>/boot/uEnt.txt</code> and search for <code>uio</code>. I find</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>###pru_uio (4.4.x-ti, 4.9.x-ti, 4.14.x-ti & mainline/bone kernel)
-uboot_overlay_pru=/lib/firmware/AM335X-PRU-UIO-00A0.dtbo</pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Uncomment the <code>uboot</code> line. Look for other lines with
-<code>uboot_overlay_pru=</code> and be sure they are commented out.</p>
-</div>
-<div class="paragraph">
-<p>Reboot your Bone.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>bone$ <strong>sudo reboot</strong></pre>
-</div>
-</div>
-<div class="paragraph">
-<p>Check that UIO is running.</p>
-</div>
-<div class="listingblock">
-<div class="content">
-<pre>bone$ <strong>lsmod | grep uio</strong>
-uio_pruss 16384 0
-uio_pdrv_genirq 16384 0
-uio 20480 2 uio_pruss,uio_pdrv_genirq</pre>
-</div>
-</div>
-<div class="paragraph">
-<p>You are now ready to run the legacy PRU code.</p>
-</div>
-</div>
-</div>
-<div class="sect2">
-<h3 id="_converting_pasm_assembly_code_to_clpru"><a class="link" href="#_converting_pasm_assembly_code_to_clpru">1.4. Converting pasm Assembly Code to clpru</a></h3>
-<div class="sect3">
-<h4 id="_problem_4"><a class="link" href="#_problem_4">Problem</a></h4>
-<div class="paragraph">
-<p>You have some legacy assembly code written in pasm and it won’t assemble
-with clpru.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_solution_4"><a class="link" href="#_solution_4">Solution</a></h4>
-<div class="paragraph">
-<p>Generally there is a simple mapping from pasm to clpru.
-<a href="http://processors.wiki.ti.com/index.php/PRU_Assembly_Instructions#pasm_vs._clpru">pasm vs. clpru</a>
-notes what needs to be changed. I have a less complete version on my
-<a href="https://elinux.org/EBC_Exercise_30_PRU_porting_pasm_to_clpru">eLinux.org site</a>.</p>
-</div>
-</div>
-<div class="sect3">
-<h4 id="_discussion_2"><a class="link" href="#_discussion_2">Discussion</a></h4>
-<div class="paragraph">
-<p>The clpru assembly can be found in <a href="http://www.ti.com/lit/ug/spruhv6a/spruhv6a.pdf">PRU Assembly Language Tools</a>.</p>
-</div>
-</div>
-</div>
-</div>
-</div>
-</div>
-<div id="footer">
-<div id="footer-text">
-Last updated 2021-08-04 14:38:24 -0400
-</div>
-</div>
-</body>
-</html>
\ No newline at end of file
diff --git a/books/pru-cookbook/06io/io.rst b/books/pru-cookbook/06io/io.rst
index 3548d5e0a4330f10a7a06d4f94856bac5ba1a89c..2d019de052e72f85e56e46de66aabefa90d3393f 100644
--- a/books/pru-cookbook/06io/io.rst
+++ b/books/pru-cookbook/06io/io.rst
@@ -3,9 +3,8 @@
Accessing More I/O
####################
-So far the examples have shown how to access the GPIO pins on the BeagleBone Black's
-``P9`` header and through the ``pass:[__]R30`` register. Below shows how more GPIO pins
-can be accessed.
+So far the examples have shown how to access the GPIO pins on the BeagleBone Black's ``P9`` header and
+through the ``pass:[__]R30`` register. Below shows how more GPIO pins can be accessed.
The following are resources used in this chapter.
@@ -14,21 +13,18 @@ Resources
* `P8 Header Table <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP8HeaderTable.pdf>`_
* `P9 Header Table <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf>`_
-* `AM572x Technical Reference Manual<http://www.ti.com/lit/pdf/spruhz6l>`_ (AI)
+* `AM572x Technical Reference Manual <http://www.ti.com/lit/pdf/spruhz6l>`_ (AI)
* `AM335x Technical Reference Manual <http://www.ti.com/lit/pdf/spruh73>`_ (All others)
-* `PRU Assembly Language Tools<http://www.ti.com/lit/ug/spruhv6a/spruhv6a.pdf>`_
+* `PRU Assembly Language Tools <http://www.ti.com/lit/ug/spruhv6a/spruhv6a.pdf>`_
Editing /boot/uEnv.txt to Access the P8 Header on the Black
-============================================================
+************************************************************
Problem
--------
When I try to configure some pins on the `P8` header of the Black I get an error.
-config-pin
-~~~~~~~~~~~
-
.. code-block:: bash
:linenos:
@@ -36,7 +32,7 @@ config-pin
ERROR: open() for /sys/devices/platform/ocp/ocp:P8_28_pinmux/state failed, No such file or directory
Solution
---------
+---------
On the images for the BeagleBone Black, the HDMI display driver is enabled by default
and uses many of the ``P8`` pins. If you are not using HDMI video (or the HDI audio,
@@ -44,10 +40,8 @@ or even the eMMC) you can disable it by editing ``/boot/uEnv.txt``
Open ``/boot/uEnv.txt`` and scroll down aways until you see:
-/boot/uEnv.txt
-~~~~~~~~~~~~~~~~
-
.. code-block:: bash
+ :caption: /boot/uEnv.txt
:linenos:
###Disable auto loading of virtual capes (emmc/video/wireless/adc)
@@ -65,7 +59,7 @@ Uncomment the lines that correspond to the devices you want to disable and free
Save the file and reboot. You now have access to the ``P8`` pins.
Accessing gpio
-================
+****************
Problem
--------
@@ -73,36 +67,38 @@ Problem
I've used up all the GPIO in ``pass:[__]R30``, where can I get more?
Solution
---------
+---------
So far we have focused on using PRU 0.
-:ref:`../05blocks/blocks.html#blocks_mapping_bits,Mapping bit positions to pin names PRU` shows
+:ref:`blocks_mapping_bits` shows
that PRU 0 can access ten GPIO pins on the BeagleBone Black. If you use
PRU 1 you can get to an additional 14 pins (if they aren't in use for other things.)
What if you need even more GPIO pins? You can access **any** GPIO pin by going
-through the **O**pen-**C**ore **P**rotocol (OCP) port.
+through the **O**\ pen-\ **C**\ ore **P**\ rotocol (OCP) port.
-PRU Integration
-~~~~~~~~~~~~~~~~~
.. figure:: figures/pruIntegration.png
:align: center
:alt: PRU Integration
+ PRU Integration
+
The figure above shows we've been using the _Enhanced **GPIO** interface when using
``pass:[__]R30``, but it also shows you can use the OCP. You get access to many more
GPIO pins, but it's a slower access.
-gpio.pru0.c
-~~~~~~~~~~~~
+.. literalinclude:: code/gpio.pru0.c
+ :caption: gpio.pru0.c
+ :linenos:
:download:`gpio.pru0.c <code/gpio.pru0.c>`
This code will toggle ``P9_11`` on and off. Here's the setup file.
-setup.sh
-~~~~~~~~~
+.. literalinclude:: code/setup.sh
+ :caption: setup.sh
+ :linenos:
:download:`setup.sh <code/setup.sh>`
@@ -134,10 +130,8 @@ Discussion
When you run the code you see ``P9_11`` toggling on and off. Let's go through
the code line-by-line to see what's happening.
-gpio.pru0.c line-by-line
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. table::
+.. table:: gpio.pru0.c line-by-line
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+
|Line | Explanation |
@@ -146,8 +140,8 @@ gpio.pru0.c line-by-line
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+
|5 | The AM335x has four 32-bit GPIO ports. Lines 55-58 of `prugpio.h` define the addresses |
| | for each of the ports. You can find these in Table 2-2 page 180 of the |
- | | https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf[AM335x Technical Reference Manual]. |
- | | Look up `P9_11` in the https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf[P9 Header Table]. |
+ | | `AM335x TRM 180 <https://www.ti.com/lit/ug/spruh73p/spruh73p.pdf>`_. |
+ | | Look up `P9_11` in the `P9 header <https://github.com/derekmolloy/exploringBB/blob/master/chp06/docs/BeagleboneBlackP9HeaderTable.pdf>`_. |
| | Under the _Mode7_ column you see `gpio0[30]`. This means `P9_11` is bit 30 |
| | on GPIO port 0. Therefore we will use `GPIO0` in this code. You can also run ``gpioinfo`` and look for P9_11. |
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+
@@ -172,30 +166,28 @@ gpio.pru0.c line-by-line
+-------+-----------------------------------------------------------------------------------------------------------------------------------------------+
How fast can it go?
-~~~~~~~~~~~~~~~~~~~~
+--------------------
This approach to GPIO goes through the slower OCP interface. If you set
``pass:[__]delay_cycles(0)`` you can see how fast it is.
-gpio.pru0.c with pass:[__]delay_cycles(0)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/gpio0delay.png
:align: center
:alt: gpio.pru0.c with pass:[__]delay_cycles(0)
+ gpio.pru0.c with pass:[__]delay_cycles(0)
+
The period is 80ns which is 12.MHz. That's about one forth the speed of the
``pass:[__]R30`` method, but still not bad.
If you are using an oscilloscope, look closely and you'll see the following.
-PWM with jitter
-~~~~~~~~~~~~~~~~
-
.. figure:: figures/jitter.png
:align: center
:alt: PWM with jitter
+ PWM with jitter
+
The PRU is still as solid as before in it's timing, but now it's going through
the OCP interface. This interface is shared with other parts of the system,
therefore the sometimes the PRU must wait for the other parts to finish.
@@ -206,11 +198,10 @@ For many applications a few nanoseconds of jitter is unimportant and this
GPIO interface can be used. If your application needs better timing,
use the ``pass:[__]R30`` interface.
-
.. _io_uio:
Configuring for UIO Instead of RemoteProc
-========================================
+*******************************************
Problem
--------
@@ -249,7 +240,7 @@ Check that UIO is running.
You are now ready to run the legacy PRU code.
Converting pasm Assembly Code to clpru
-========================================
+***************************************
Problem
--------
@@ -257,7 +248,7 @@ Problem
You have some legacy assembly code written in pasm and it won't assemble with clpru.
Solution
---------
+---------
Generally there is a simple mapping from pasm to clpru.
`pasm vs. clpru <http://processors.wiki.ti.com/index.php/PRU_Assembly_Instructions#pasm_vs._clpru>`_
@@ -265,7 +256,7 @@ notes what needs to be changed. I have a less complete version on my
`eLinux.org site <https://elinux.org/EBC_Exercise_30_PRU_porting_pasm_to_clpru>`_.
Discussion
---------
+-----------
The clpru assembly can be found in
`PRU Assembly Language Tools <http://www.ti.com/lit/ug/spruhv6a/spruhv6a.pdf>`_.
diff --git a/books/pru-cookbook/07more/more.rst b/books/pru-cookbook/07more/more.rst
index ae3abcf84c1598a23f54a2a0ea044952809d38ce..4bae78b1e7ed12d2fffc840e510b5c82227df88b 100644
--- a/books/pru-cookbook/07more/more.rst
+++ b/books/pru-cookbook/07more/more.rst
@@ -22,15 +22,15 @@ Resources
* `PRU Assembly Instruction User Guide <http://www.ti.com/lit/ug/spruij2/spruij2.pdf>`_
Calling Assembly from C
--------------------------
+************************
Problem
-~~~~~~~~~
+--------
You have some C code and you want to call an assembly language routine from it.
Solution
-~~~~~~~~~
+---------
You need to do two things, write the assembler file and modify the ``Makefile``
to include it. For example, let's write our own ``my_delay_cycles`` routine in
@@ -42,28 +42,30 @@ constant. Our new ``delay_cycles`` can take a runtime delay value.
.. _more_delay-test:
-delay-test.pru0.c
-~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/delay-test.pru0.c
+ :caption: delay-test.pru0.c
+ :linenos:
-:download:`code/delay-test.pru0.c <code/delay-test.pru0.c>`
+:download:`delay-test.pru0.c <code/delay-test.pru0.c>`
:ref:`more_delay` is the assembly code.
.. _more_delay:
-delay.pru0.asm
-~~~~~~~~~~~~~~~
+.. literalinclude:: code/delay.pru0.asm
+ :caption: delay.pru0.asm
+ :linenos:
:download:`delay.pru0.asm <code/delay.pru0.asm>`
The ``Makefile`` has one addition that needs to be made to compile both :ref:`more_delay-test`
-and :ref:`more_delay`.
-If you look in the local ``Makefile`` you'll see:
+and :ref:`more_delay`. If you look in the local ``Makefile`` you'll see:
.. _more_makefile:
-Makefile
-~~~~~~~~~
+.. literalinclude:: code/Makefile
+ :caption: Makefile
+ :linenos:
:download:`Makefile <code/Makefile>`
@@ -102,23 +104,20 @@ The resulting output is shown in :ref:`more_my_delay_cycles`.
.. _more_my_delay_cycles:
-Output of my_delay_cycles()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
.. figure:: figures/my_delay_cycles.png
:align: center
:alt: Output of my_delay_cycles()
+ Output of my_delay_cycles()
+
Notice the on time is about 35ns and the off time is 30ns.
Discission
-~~~~~~~~~~~~
+-----------
There is much to explain here. Let's start with :ref:`more_delay`.
-Line-by-line of delay.pru0.asm
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. table::
+.. table:: Line-by-line of delay.pru0.asm
+-------+-------------------------------------------------------------------------------------------------------+
|Line | Explanation |
@@ -152,22 +151,23 @@ The extra instruction is the branch at the bottom of the ``while`` loop.
Returning a Value from Assembly
---------------------------------
+********************************
Problem
-~~~~~~~~~
+--------
Your assembly code needs to return a value.
Solution
-~~~~~~~~~
+--------
``R14`` is how the return value is passed back. :ref:`more_test2` shows the c code.
.. _more_test2:
-delay-test2.pru0.c
-~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/delay-test2.pru0.c
+ :caption: delay-test2.pru0.c
+ :linenos:
:download:`delay-test2.pru0.c <code/delay-test2.pru0.c>`
@@ -175,8 +175,9 @@ delay-test2.pru0.c
.. _more_delay2:
-delay2.pru0.asm
-~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/delay2.pru0.asm
+ :caption: delay2.pru0.asm
+ :linenos:
:download:`delay2.pru0.asm <code/delay2.pru0.asm>`
@@ -187,15 +188,15 @@ In this example, line 6 of :ref:`more_test2` `#defines` TEST and line 12 of
Using the Built-In Counter for Timing
----------------------------------------
+***************************************
Problem
-~~~~~~~~~
+--------
I want to count how many cycles my routine takes.
Solution
-~~~~~~~~~
+---------
Each PRU has a ``CYCLE`` register which counts the number of cycles since
the PRU was enabled. They also have a ``STALL`` register that counts how
@@ -204,23 +205,21 @@ many times the PRU stalled fetching an instruction.
.. _more_cycle:
-cycle.pru0.c - Code to count cycles.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/cycle.pru0.c
+ :caption: cycle.pru0.c - Code to count cycles.
+ :linenos:
-:download:`delay2.pru0.asm <code/cycle.pru0.c>`
+:download:`cycle.pru0.c <code/cycle.pru0.c>`
Discission
-~~~~~~~~~~~~
+------------
The code is mostly the same as other examples. ``cycle`` and ``stall`` end up in registers which
we can read using prudebug. :ref:`more_cycle_lines` is the Line-by-line.
.. _more_cycle_lines:
-Line-by-line for cycle.pru0.c
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Line-by-line for cycle.pru0.c
+-------+---------------------------------------------------------------------------------------+
|Line | Explanation |
@@ -244,20 +243,26 @@ You can see where ``cycle`` and ``stall`` are stored by looking into :ref:`more_
.. _more_cycle_list0:
-/tmp/cloud9-examples/cycle.pru0.lst Lines 113..119
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/cycle.pru0.lst
+ :caption: /tmp/cloud9-examples/cycle.pru0.lst Lines 113..119
+ :lines: 113-119
+ :lineno-start: 113
+ :linenos:
-:download:`cycle.pru0.lst lines=113..119 <code/cycle.pru0.lst>`
+:download:`cycle.pru0.lst <code/cycle.pru0.lst>`
Here the ``LDI32`` instruction loads the address ``0x22000`` into ``r0``. This is the offset to
the ``CTRL`` registers. Later in the file we see :ref:`more_cycle_list1`.
.. _more_cycle_list1:
-/tmp/cloud9-examples/cycle.pru0.lst Lines 146..152
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. literalinclude:: code/cycle.pru0.lst
+ :caption: /tmp/cloud9-examples/cycle.pru0.lst Lines 146..152
+ :lines: 146-152
+ :lineno-start: 146
+ :linenos:
-:download:`lines=146..152 <code/cycle.pru0.lst>`
+:download:`cycle.pru0.lst <code/cycle.pru0.lst>`
The first ``LBBO`` takes the contents of ``r0`` and adds the offset 12 to it and copies 4 bytes
@@ -298,23 +303,24 @@ If you switch the order of lines 30 and 31 you'll see ``cycle`` is 7 and ``stall
time needed to read ``stall`` and ``stall`` no longer includes the time to read ``cycle``.
Xout and Xin - Transfering Between PRUs
----------------------------------------
+*****************************************
Problem
-~~~~~~~~~
+--------
I need to transfer data between PRUs quickly.
Solution
-~~~~~~~~~
+---------
The ``pass:[__]xout()`` and ``pass:[__]xin()`` intrinsics are able to transfer up to 30 registers between PRU 0 and PRU 1 quickly.
:ref:`more_xout` shows how ``xout()`` running on PRU 0 transfers six registers to PRU 1.
.. _more_xout:
-xout.pru0.c
-~~~~~~~~~~~~
+.. literalinclude:: code/xout.pru0.c
+ :caption: xout.pru0.c
+ :linenos:
:download:`xout.pru0.c <code/xout.pru0.c>`
@@ -323,8 +329,9 @@ interupt to PRU 0 and waits for it to send the data.
.. _more_xin:
-xin.pru1.c
-~~~~~~~~~~~
+.. literalinclude:: code/xin.pru1.c
+ :caption: xin.pru1.c
+ :linenos:
:download:`xin.pru1.c <code/xin.pru1.c>`
@@ -373,15 +380,13 @@ Use ``prudebug`` to see registers R5-R10 are transfered from PRU 0 to PRU 1.
Discussion
-~~~~~~~~~
+-----------
:ref:`more_zout_lines` shows the line-by-line for ``xout.pru0.c``
.. _more_zout_lines:
-xout.pru0.c Line-by-line
-~~~~~~~~~~~~~~~~~~~~~~~~~
-.. table::
+.. table:: xout.pru0.c Line-by-line
+-------+---------------------------------------------------------------------------------------------------------+
|Line | Explanation |
@@ -415,9 +420,7 @@ xout.pru0.c Line-by-line
.. _more_xin_lines:
-xin.pru1.c Line-by-line
-~~~~~~~~~~~~~~~~~~~~~~~~
-.. table::
+.. table:: xin.pru1.c Line-by-line
+-------+-----------------------------------------------------------+
|Line | Explanation |
@@ -435,9 +438,10 @@ xin.pru1.c Line-by-line
If you really need speed, considering using ``pass:[__]xout()`` and ``pass:[__]xin()`` in assembly.
Copyright
-----------
+==========
-copyright.c
-~~~~~~~~~~~~~
+.. literalinclude:: code/copyright.c
+ :caption: copyright.c
+ :linenos:
:download:`copyright.c <code/copyright.c>`
diff --git a/books/pru-cookbook/08ai/ai.rst b/books/pru-cookbook/08ai/ai.rst
index db36f383f27b505f3f613a471bae81e0525db48e..ca50756249c475876c5b6b6da33358eb63a8f63c 100644
--- a/books/pru-cookbook/08ai/ai.rst
+++ b/books/pru-cookbook/08ai/ai.rst
@@ -18,7 +18,7 @@ Resources
* `BeagleBone AI PRU pins <https://docs.google.com/spreadsheets/d/1dFSBVem86vAUD7MLXvqdS-N0Efi8_g_O1iTqzql8DAo/edit#gid=0>`_
Moving from two to four PRUs
-=============================
+*****************************
Problem
--------
@@ -37,21 +37,18 @@ Things to consider when moving to the AI are:
Knowing which pins to use impacts the PRU you'll use.
Discission
---------
+-----------
The various System Reference Manuals (SRM's) list which pins go to the PRUs.
Here the tables are combined into one to make it easier to see what goes where.
.. _aimapping_bits:
-Mapping bit positions to pin names
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. table::
+.. table:: Mapping bit positions to pin names
+---+---+---------+-----------+-----------+-------------+
|PRU|Bit|Black pin|AI PRU1 pin|AI PRU2 pin|Pocket pin |
- |0 |0 |P9_31 | |P8_44 |P1.36 |
+ |0 |0 |P9_31 | |P8_44 |P1.36 |
+---+---+---------+-----------+-----------+-------------+
|0 |1 |P9_29 | |P8_41 |P1.33 |
+---+---+---------+-----------+-----------+-------------+
@@ -67,31 +64,31 @@ Mapping bit positions to pin names
+---+---+---------+-----------+-----------+-------------+
|0 |7 |P9_25 | |P8_36/P8_6 |P1.29 |
+---+---+---------+-----------+-----------+-------------+
- |0 |8 | | |P8_34/P8_23| |
+ |0 |8 | | |P8_34/P8_23| |
+---+---+---------+-----------+-----------+-------------+
- |0 |9 | | |P8_35/P8_22| |
+ |0 |9 | | |P8_35/P8_22| |
+---+---+---------+-----------+-----------+-------------+
- |0 |19 | | |P8_33/P8_3 | |
+ |0 |19 | | |P8_33/P8_3 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |11 | | |P8_31/P8_4 | |
+ |0 |11 | | |P8_31/P8_4 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |12 | | |P8_32 | |
+ |0 |12 | | |P8_32 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |13 | | |P8_45 | |
+ |0 |13 | | |P8_45 | |
+---+---+---------+-----------+-----------+-------------+
|0 |14 |P8_12(out) P8_16(in)||P9_11 |P2.24 |
+---+---+---------+-----------+-----------+-------------+
|0 |15 |P8_11(out) P8_15(in)||P8_17/P9_13|P2.33 |
+---+---+---------+-----------+-----------+-------------+
- |0 |16 |P9_41(in) P9_26(in)| |P8_27 | |
+ |0 |16 |P9_41(in) P9_26(in)| |P8_27 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |17 | |P9_26 |P8_28 | |
+ |0 |17 | |P9_26 |P8_28 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |18 | | |P8_29 | |
+ |0 |18 | | |P8_29 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |19 | | |P8_30 | |
+ |0 |19 | | |P8_30 | |
+---+---+---------+-----------+-----------+-------------+
- |0 |20 | | |P8_46/P8_8 | |
+ |0 |20 | | |P8_46/P8_8 | |
+---+---+---------+-----------+-----------+-------------+
| | | | | | |
+---+---+---------+-----------+-----------+-------------+
@@ -127,15 +124,15 @@ Mapping bit positions to pin names
+---+---+---------+-----------+-----------+-------------+
|1 |15 | |*P9_16* |P8_10 |P1.30 |
+---+---+---------+-----------+-----------+-------------+
- |1 |16 |P9_26(in)|*P8_15* |P8_7 | |
+ |1 |16 |P9_26(in)|*P8_15* |P8_7 | |
+---+---+---------+-----------+-----------+-------------+
- |1 |17 | |*P8_26* |P8_27 | |
+ |1 |17 | |*P8_26* |P8_27 | |
+---+---+---------+-----------+-----------+-------------+
- |1 |18 | |*P8_16* |P8_45 | |
+ |1 |18 | |*P8_16* |P8_45 | |
+---+---+---------+-----------+-----------+-------------+
- |1 |19 | | |P8_46 | |
+ |1 |19 | | |P8_46 | |
+---+---+---------+-----------+-----------+-------------+
- |1 |19 | | |P8_43 | |
+ |1 |19 | | |P8_43 | |
+---+---+---------+-----------+-----------+-------------+
The pins in *bold* are already configured as pru pins. See :ref:`ai_config` to
@@ -145,7 +142,7 @@ configure pins.
.. _ai_config:
Seeing how pins are configured
-===============================
+*******************************
Problem
--------
@@ -231,7 +228,7 @@ Five are input pins and four are out.
.. _ai_device_tree:
Configuring pins on the AI via device trees
-============================================
+********************************************
Problem
--------
@@ -274,6 +271,7 @@ We see that when ``P9_31a`` is set to ``MODE13`` it will be a PRU **out** pin.
Next, find which kernel you are running.
.. code-block:: bash
+
bone$ uname -a
Linux ai 4.14.108-ti-r131 #1buster SMP PREEMPT Tue Mar 24 19:18:36 UTC 2020 armv7l GNU/Linux
@@ -335,7 +333,7 @@ There it is. `P9_31` is now a PRU output pin on PRU1_0, bit 3.
.. _ai_using_pru_pins:
Using the PRU pins
-====================
+*********************
Problem
--------
@@ -350,7 +348,7 @@ that it appears at ``pr2_pru1_gpo10``, which means pru2_1 accesses it using
bit 10 of register ``R30``.
Discission
---------
+-----------
It's easy to modify the pwm example from :ref:`blocks_pwm` to use this pin.
First copy the example you want to modify to ``pwm1.pru2_1.c``. The ``pru2_1`` in
@@ -359,8 +357,9 @@ the adapted code.
.. _ai_pwm1:
-pwm1.pru2_1.c
-~~~~~~~~~~~~~~
+.. literalinclude:: code/pwm1.pru2_1.c
+ :caption: pwm1.pru2_1.c
+ :linenos:
:download:`pwm1.pru2_1.c <code/pwm1.pru2_1.c>`
diff --git a/conf.py b/conf.py
index 6e713339ee35f7a9acea5fdc0049f4e17ed15957..5a04178d00bc40614379d589726dfd08cab98efa 100644
--- a/conf.py
+++ b/conf.py
@@ -71,7 +71,7 @@ with open(BBDOCS_BASE / "VERSION") as f:
)
if not m:
- sys.stderr.write("Warning: Could not extract kernel version\n")
+ sys.stderr.write("Warning: Could not extract docs version\n")
version = "Unknown"
else:
major, minor, patch, extra = m.groups(1)
@@ -81,11 +81,29 @@ with open(BBDOCS_BASE / "VERSION") as f:
release = version
-is_release = tags.has("release") # pylint: disable=undefined-variable
-reference_prefix = ""
-if tags.has("publish"): # pylint: disable=undefined-variable
- reference_prefix = f"/{version}" if is_release else "/latest"
-docs_title = "Docs / {}".format(version if is_release else "Latest")
+pages_url = ""
+pages_slug = ""
+docs_url = ""
+
+# parse pages details from 'PAGES' file
+with open(BBDOCS_BASE / "PAGES") as f:
+ m = re.match(
+ (
+ r"^PAGES_URL\s*=\s*(\S+)$\n"
+ + r"^PAGES_SLUG\s*=\s*(\S+)$\n"
+ ),
+ f.read(),
+ re.MULTILINE,
+ )
+
+ if not m:
+ sys.stderr.write("Warning: Could not extract pages information\n")
+ else:
+ url, slug = m.groups(1)
+ slug = "latest" if slug == "main" else slug
+ pages_url = url
+ pages_slug = slug
+ docs_url = "/".join((url, slug))
html_context = {
"display_gitlab": True,
@@ -95,9 +113,16 @@ html_context = {
"gitlab_version": "main",
"conf_py_path": "/",
"show_license": True,
- "docs_title": docs_title,
- "is_release": is_release,
- "current_version": version
+ "pages_url": pages_url,
+ "pages_slug": pages_slug,
+ "docs_url": docs_url,
+ "current_version": version,
+ "versions": ("latest", "0.0", "0.1"),
+ "reference_links": {
+ "About": "https://beagleboard.org/about",
+ "Donate": "https://beagleboard.org/donate/",
+ "FAQ": "https://beagleboard.org/Support/FAQ"
+ }
}
# -- Options for LaTeX output ---------------------------------------------
@@ -123,9 +148,6 @@ latex_documents = [
("index-tex", "beagleboard-docs.tex", "BeagleBoard Docs", author, "manual"),
]
-vcs_link_version = f"v{version}" if is_release else "main"
-vcs_link_base_url = f"https://git.beagleboard.org/docs/docs.beagleboard.io/blob/{vcs_link_version}"
-
#language = 'en'
#locales_dir = ['locale/']
#gettext_compact = True
diff --git a/gitlab-build.sh b/gitlab-build.sh
index c7f39c080cb0fc3912111e89e9211a29320f194e..550a1bbc37822c041680705825c4bc0bd9db2996 100755
--- a/gitlab-build.sh
+++ b/gitlab-build.sh
@@ -2,6 +2,11 @@
env
+cat << EOF > PAGES
+PAGES_URL = $CI_PAGES_URL
+PAGES_SLUG = $CI_COMMIT_BRANCH
+EOF
+
if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then
rm -rf public
@@ -28,14 +33,13 @@ sphinx-build -M latexpdf . public/$CI_COMMIT_BRANCH/
mv public/$CI_COMMIT_BRANCH/latex/beagleboard-docs.pdf public/$CI_COMMIT_BRANCH/
rm -rf public/$CI_COMMIT_BRANCH/latex
-elif [ "$CI_COMMIT_TAG" != "" ]; then
+# elif [ "$CI_COMMIT_TAG" != "" ]; then
-export GIT_BRANCH=$(git branch -a --contains tags/$CI_COMMIT_TAG | grep origin | sed 's/.*origin\///')
-sphinx-build -b html . public/$GIT_BRANCH/
-sphinx-build -M latexpdf . public/$GIT_BRANCH/
-mv public/$GIT_BRANCH/latex/beagleboard-docs.pdf public/$GIT_BRANCH/beagleboard-docs-$CI_COMMIT_TAG.pdf
-ln -s public/$GIT_BRANCH/latex/beagleboard-docs-$CI_COMMIT_TAG.pdf public/$GIT_BRANCH/beagleboard-docs.pdf
-rm -rf public/$GIT_BRANCH/latex
+# export GIT_BRANCH=$(git branch -a --contains tags/$CI_COMMIT_TAG | grep origin | sed 's/.*origin\///')
+# sphinx-build -b html . public/$GIT_BRANCH/
+# sphinx-build -M latexpdf . public/$GIT_BRANCH/
+# mv public/$GIT_BRANCH/latex/beagleboard-docs.pdf public/$GIT_BRANCH/beagleboard-docs-$CI_COMMIT_TAG.pdf
+# ln -s public/$GIT_BRANCH/latex/beagleboard-docs-$CI_COMMIT_TAG.pdf public/$GIT_BRANCH/beagleboard-docs.pdf
+# rm -rf public/$GIT_BRANCH/latex
fi
-