diff --git a/_static/css/custom.css b/_static/css/custom.css
index 20417d54c45cf2b4a39e671926d756cede5fa5bc..0a0f69e9c8948bdd8b3647b3fe30ebf32a4282ca 100644
--- a/_static/css/custom.css
+++ b/_static/css/custom.css
@@ -64,4 +64,8 @@
* fixing larger font size for paragraphs in the kconfig tables */
.wy-table-responsive td p {
font-size: 100%;
-}
\ No newline at end of file
+}
+
+span.strike {
+ text-decoration: line-through;
+}
diff --git a/_templates/layout.html b/_templates/layout.html
index cd42441bc49212ded469a6ef1fdcf1bbb93118e5..c6be8a80aa01d3e3f9e8dc92bbf8196334d69bf8 100644
--- a/_templates/layout.html
+++ b/_templates/layout.html
@@ -7,9 +7,9 @@
</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.
+ This is the latest (main) BeagleBoard documentation.
+ If you are looking for stable releases, use the
+ drop-down menu on the bottom-left and select the desired version.
</div>
{% endif %}
{{ super() }}
diff --git a/boards/beagleboard/index.rst b/boards/beagleboard/index.rst
index beb56cd177881343655724e91d1d6a12736c7867..bcd643cdd5ff07b70062b767a6079b57ce7ee37a 100644
--- a/boards/beagleboard/index.rst
+++ b/boards/beagleboard/index.rst
@@ -1,3 +1,5 @@
+.. _beagleboard-boards-home:
+
BeagleBoard (all)
###################
diff --git a/boards/beaglebone/index.rst b/boards/beaglebone/index.rst
index cd47c0d1e1ec7a5daad761d4004a1f45d727bd68..a63ca8133ae5c95d6c93b96efc795f41ba904ff4 100644
--- a/boards/beaglebone/index.rst
+++ b/boards/beaglebone/index.rst
@@ -1,4 +1,4 @@
-.. _beaglebone-blue-home::
+.. _beaglebone-all-home:
BeagleBone (all)
###################
@@ -22,8 +22,8 @@ included both here and in the downloadable beagleboard-docs.pdf linked on the bo
of your screen.
* `BeagleBone (original) <https://git.beagleboard.org/beagleboard/beaglebone/-/blob/master/BeagleBone_SRM_A6_0_1.pdf>`__
-* `BeagleBone Black </boards/beaglebone/black/index.html>`__
-* `BeagleBone Blue </boards/beaglebone/blue/index.html>`__
-* `BeagleBone AI-64 </boards/beaglebone/ai-64/index.html>`__
-* `BeagleBone AI </boards/beaglebone/ai/index.html>`__
+* :ref:`beagleboneblack-home`
+* :ref:`beaglebone-blue-home`
+* :ref:`bbai64-home`
+* :ref:`beaglebone-ai-home`
diff --git a/boards/beagleconnect/freedom/index.rst b/boards/beagleconnect/freedom/index.rst
index bd602d22cc1b1c7062bd7619a4fd3e01ef96b425..48115ae38a21cd42f60d09c5fe55572fad95e52a 100644
--- a/boards/beagleconnect/freedom/index.rst
+++ b/boards/beagleconnect/freedom/index.rst
@@ -29,7 +29,7 @@ devices within the first year after the initial release.
BeagleConnectâ„¢ Freedom
**********************
-BeagleConnectâ„¢ Freedom is based on the `TI CC1352 <https://www.ti.com/product/CC1352R>`_
+BeagleConnectâ„¢ Freedom is based on the `TI CC1352 <https://www.ti.com/product/CC1352P7>`_
and is the first available BeagleConnectâ„¢ solution. It implements:
* BeagleConnectâ„¢ gateway device function for Sub-GHz 802.15.4 long-range
@@ -125,9 +125,9 @@ Long-range, low-power wireless
==============================
BeagleConnectâ„¢ Freedom wireless hardware is built around a
-`TI CC1352 <http://www.ti.com/product/CC1352R>`_ multiprotocol and multi-band
-Sub-1 GHz and 2.4-GHz wireless microcontroller (MCU). CC1352R includes a 48-MHz
-Arm® Cortex®-M4F processor, 352KB Flash, 256KB ROM, 8KB Cache SRAM, 80KB of
+`TI CC1352 <http://www.ti.com/product/CC1352P7>`_ multiprotocol and multi-band
+Sub-1 GHz and 2.4-GHz wireless microcontroller (MCU). CC1352P7 includes a 48-MHz
+Arm® Cortex®-M4F processor, 704KB Flash, 256KB ROM, 8KB Cache SRAM, 144KB of
ultra-low leakage SRAM, and `Over-the-Air <https://en.wikipedia.org/wiki/Over-the-air_programming>`_
upgrades (OTA).
@@ -160,12 +160,12 @@ Each BeagleBoard.org BeagleConnectâ„¢ solution will be:
Getting Started
***************
-* `Typical usage with a Linux host </boards/beagleconnect/freedom/usage.html>`__
-* `Programming with Zephyr </boards/beagleconnect/freedom/zephyr.html>`__
+* :ref:`Typical BeagleConnect Freedom usage with a Linux host <beagleconnect-usage>`
+* :ref:`Programming BeagleConnect Freedom with Zephyr <beagleconnect-zephyr>`
.. toctree::
:maxdepth: 1
:hidden:
- usage.rst
- zephyr.rst
+ /boards/beagleconnect/freedom/usage.rst
+ /boards/beagleconnect/freedom/zephyr.rst
diff --git a/boards/beagleconnect/freedom/usage.rst b/boards/beagleconnect/freedom/usage.rst
index b55d5dd5d24f539d5d0bf5e0d504d48ef47b065d..862e89741edf6889ba77c2e9f3a30194f14665ce 100644
--- a/boards/beagleconnect/freedom/usage.rst
+++ b/boards/beagleconnect/freedom/usage.rst
@@ -1,4 +1,4 @@
-.. _beagleconnect-Usage:
+.. _beagleconnect-usage:
BeagleConnect Freedom Usage
###########################
diff --git a/boards/beagleconnect/freedom/zephyr.rst b/boards/beagleconnect/freedom/zephyr.rst
index 2836c00a84e7a8da6cb462094e4aec267cdd7a4c..f08d7e4a08da9af999cf54271f5dd8dfc134e928 100644
--- a/boards/beagleconnect/freedom/zephyr.rst
+++ b/boards/beagleconnect/freedom/zephyr.rst
@@ -1,4 +1,4 @@
-.. _beagleconnect-connectivity:
+.. _beagleconnect-zephyr:
BeagleConnect Freedom & Zephyr
###############################
diff --git a/boards/beagleconnect/index.rst b/boards/beagleconnect/index.rst
index 7c2ee09ff5320ed1faf9e08f41800123b7206896..8172f05328e2a4f9d6ef916603b7016028a0e928 100644
--- a/boards/beagleconnect/index.rst
+++ b/boards/beagleconnect/index.rst
@@ -38,6 +38,12 @@ BeagleConnectâ„¢ technology solves:
* The need to produce high-volume custom hardware cost-optimized for your
requirements.
+.. toctree::
+ :maxdepth: 2
+
+ /boards/beagleconnect/technology/index.rst
+ /boards/beagleconnect/technology/story.rst
+
BeagleConnect Experience
*************************
@@ -88,18 +94,6 @@ For home automaters, integration into WebThings…
:alt: BeagleConnect
-BeagleConnect Technology
-************************
-
-Learn about the technology behind BeagleConnect.
-
-.. toctree::
- :maxdepth: 2
-
- /boards/beagleconnect/technology/index.rst
- /boards/beagleconnect/technology/story.rst
-
-
BeagleConnect Boards
********************
diff --git a/boards/beagleconnect/technology/index.rst b/boards/beagleconnect/technology/index.rst
index 3f24588dad933ecb6e172342fdddbce3bc985130..06196ee5de47d7ac2ca3931c5483f821c1bd70dd 100644
--- a/boards/beagleconnect/technology/index.rst
+++ b/boards/beagleconnect/technology/index.rst
@@ -1,3 +1,6 @@
+.. role:: strike
+ :class: strike
+
.. _beagleconnect-overview:
BeagleConnect Technology
@@ -15,12 +18,8 @@ architecture.
:height: 400
:alt: BeagleConnect
-BeagleConnectâ„¢ Greybus Stack
-****************************
-
-Work in progress
-================
-
+BeagleConnectâ„¢ is built using `Greybus <https://kernel-recipes.org/en/2015/talks/an-introduction-to-greybus/>`__
+code in the Linux kernel originally designed for mobile phones.
To understand a bit more about how the BeagleConnectâ„¢ Greybus stack is being
built, this section helps describe the development currently in progress and
the principles of operation.
@@ -65,16 +64,18 @@ Software architecture
TODO items
----------
-* Linux kernel driver
+* :strike:`Linux kernel driver` (wpanusb and bcfserial still need to be upstreamed)
* Provisioning
-* Firmware for host CC13x
+* :strike:`Firmware for host CC13x`
+
+* :strike:`Firmware for device CC13x`
-* Firmware for device CC13x
+* Unify firmware for host/device CC13x
-* Click Board drivers and device tree formatted metadata for 100 or so Click
- Boards
+* :strike:`Click Board drivers and device tree formatted metadata for 100 or so Click
+ Boards`
* Click Board plug-ins for node-red for the same 100 or so Click Boards
@@ -110,7 +111,7 @@ User experience concerns
provisioning is completed
BeagleConnectâ„¢ Greybus demo using BeagleConnectâ„¢ Freedom
-========================================================
+########################################################
BeagleConnectâ„¢ Freedom runs a subGHz IEEE 802.15.4 network. This BeagleConnectâ„¢
Greybus demo shows how to interact with GPIO, I2C and mikroBUS add-on boards
remotely connected over a BeagleConnectâ„¢ Freedom.
diff --git a/boards/beagleconnect/technology/story.rst b/boards/beagleconnect/technology/story.rst
index 4a907c0600a83a63a08e36ac7a340a49ce32da6c..a4f77d55a55dac6f8647c90e56d2cd3e19e12026 100644
--- a/boards/beagleconnect/technology/story.rst
+++ b/boards/beagleconnect/technology/story.rst
@@ -1,4 +1,4 @@
-.. _beagleconnect-home:
+.. _beagleconnect-story:
BeagleConnectâ„¢ Story
*********************
diff --git a/boards/capes/index.rst b/boards/capes/index.rst
index d2fba272cabd2f7650d8ea51e8d2eb0dbad58bc5..e675e038ebc7e095fafc012b2fe2e6776875e4f7 100644
--- a/boards/capes/index.rst
+++ b/boards/capes/index.rst
@@ -1,17 +1,38 @@
+.. _capes:
+
Capes
#####
.. note::
This page is under development.
-Capes are add-on boards for BeagleBone or PocketBeagle families of boards.
+Capes are add-on boards for BeagleBone or PocketBeagle families of boards. Using a Cape add-on board, you can easily add
+sensors, communication peripherals, and more.
+
+Please visit `BeagleBoard.org - Cape <https://beagleboard.org/capes>`_ for the list of currently available Cape add-on boards.
+
+In the BeagleBone board family, there are many variants, such as :ref:`beagleboneblack-home`, :ref:`beaglebone-ai-home`,
+:ref:`bbai64-home` and compatibles such as `SeeedStudio BeagleBone Green <https://beagleboard.org/green>`_,
+`SeeedStudio BeagleBone Green Wireless <https://beagleboard.org/green-wireless>`_, `SeeedStudio BeagleBone Green Gateway
+<https://wiki.seeedstudio.com/BeagleBone-Green-Gateway/>`_ and more.
+
+The :ref:`beaglebone-cape-interface-spec` enables a common set of device tree overlays and software to be utilized
+on each of these different BeagleBone boards.
+
+Each hardware has different internal pin assignments
+and the number of peripherals in the SoC, but the device tree overlay absorbs these differences.
+
+The user of the Cape add-on boards are essentially able to use it
+across the corresponding Boards without changing any code at all.
-* Learn about our compatibility layer on: `BeagleBone Cape Interface Specification </boards/capes/cape-interface-spec.html>`__
+Find the instructions below on using each cape:
+* :ref:`bone-cape-relay`
.. toctree::
:maxdepth: 2
:hidden:
/boards/capes/cape-interface-spec
+ /boards/capes/relay
diff --git a/boards/capes/relay.rst b/boards/capes/relay.rst
new file mode 100644
index 0000000000000000000000000000000000000000..fe9b9b6a9b1426c32190c6ad242db8352699e39c
--- /dev/null
+++ b/boards/capes/relay.rst
@@ -0,0 +1,61 @@
+.. _bone-cape-relay:
+
+BeagleBoard.org BeagleBone Relay Cape
+#####################################
+
+Relay Cape, as the name suggests, is a simple Cape with a relay on it.
+It contains four relays, each of which can be operated independently from the BeagleBone.
+
+.. image:: images/BeagleBoneRelayCapeA2-400x274.png
+ :align: center
+
+* `Order page <https://beagleboard.org/capes#relay>`_
+* `Schematic <https://git.beagleboard.org/beagleboard/capes/-/tree/master/beaglebone/Relay>`_
+
+.. note::
+ The following describes how to use the device tree overlay under development.
+ The description may not be suitable for those using older firmware.
+
+Installation
+************
+
+No special configuration is required. When you plug Cape into your BeagleBoard,
+it is automatically recognized by the Cape Universal function.
+
+You can check to see if Relay Cape is recognized with the following command.
+
+.. code-block::
+
+ ls /proc/device-tree/chosen/overlay
+
+A list of currently loaded device tree overlays is displayed here.
+If you see `BBORG_RELAY-00A2.kernel` in this list, it has been loaded correctly.
+
+If it is not loaded correctly, you can also load it directly
+by adding the following to the U-Boot options
+(which can be reflected by changing /boot/uEnv.txt).
+
+.. code-block::
+
+ uboot_overlay_addr0=BBORG_RELAY-00A2.dtbo
+
+
+Usage
+******
+
+.. code-block::
+
+ ls /sys/class/leds
+
+The directory "relay*" exists in the following directory.
+The LEDs can be controlled by modifying the files in this directory.
+
+.. code-block::
+
+ echo 1 > relay1/brightness
+
+This allows you to adjust the brightness;
+entering 1 for brightness turns it ON, and entering 0 for OFF.
+
+The four relays can be changed individually
+by changing the number after "relay.
diff --git a/boards/index.rst b/boards/index.rst
index b465904763b0ef357b22943f581e5fce178e9965..519d98e15e842634334989616ca0b7e6e3abae9b 100644
--- a/boards/index.rst
+++ b/boards/index.rst
@@ -1,21 +1,23 @@
+.. _boards:
+
Boards
######
-`BeagleBone <beaglebone>`__ is a family of ARM-based, Linux-capable boards intended to be
+:ref:`BeagleBone <beaglebone-all-home>` is a family of ARM-based, Linux-capable boards intended to be
bare-bones, with a balance of features to enable rapid prototyping and provide a solid
reference for building end products.
-`PocketBeagle <pocketbeagle>`__ boards are ultra-tiny ARM-based, Linux-capable boards intended to be
+:ref:`pocketbeagle-home` boards are ultra-tiny ARM-based, Linux-capable boards intended to be
very low cost, with minimal features suitable for beginners and attractive to professionals
looking for a more minimal starting point.
-`BeagleBone and PocketBeagle Capes <capes>`__ are add-on boards for BeagleBone and PocketBeagle boards.
+BeagleBone and PocketBeagle :ref:`capes` are add-on boards for BeagleBone and PocketBeagle boards.
-`BeagleConnect <beagleconnect>`__ boards are ARM microcontroller-based, Zephyr-capable boards meant
+:ref:`beagleconnect-home` boards are ARM microcontroller-based, Zephyr-capable boards meant
to act as ultra low cost smart peripherals to their Linux-capable counterparts, with connectivity
options that enable almost endless sensing and actuation expansion.
-`BeagleBoard <beagleboard>`__ is a family of ARM-based, Linux-capable boards where this project
+:ref:`BeagleBoard <beagleboard-boards-home>` is a family of ARM-based, Linux-capable boards where this project
started.
.. toctree::
diff --git a/books/beaglebone-cookbook/02sensors/sensors.rst b/books/beaglebone-cookbook/02sensors/sensors.rst
index 9ddb94d79b28ffc5a82756319499fce41621233a..6f15d0adf0c28d3db2271194a7b51c1b3a786cdc 100644
--- a/books/beaglebone-cookbook/02sensors/sensors.rst
+++ b/books/beaglebone-cookbook/02sensors/sensors.rst
@@ -648,7 +648,7 @@ Solution
The TMP101 sensor is a common digital temperature
sensor that uses a standard |I2C|-based serial protocol.
-.. |I2C| replace:: I\ :sub:`2`\ C
+.. |I2C| replace:: I\ :sup:`2`\ C
To make this recipe, you will need:
diff --git a/books/beaglebone-cookbook/03displays/displays.rst b/books/beaglebone-cookbook/03displays/displays.rst
index 2ce70cef7bde9e53e13515f09e774a652aaab068..3abec72fb8617a9342206634bbd2ab4061737c1f 100644
--- a/books/beaglebone-cookbook/03displays/displays.rst
+++ b/books/beaglebone-cookbook/03displays/displays.rst
@@ -315,7 +315,7 @@ The LED matrix is a 5 V device, but you can drive it from 3.3 V. Wire, as shown
:ref:`sensors_i2c_temp` shows how to use *i2cdetect* to discover the address of an |I2C| device.
-.. |I2C| replace:: I\ :sub:`2`\ C
+.. |I2C| replace:: I\ :sup:`2`\ C
Run the *i2cdetect -y -r 2* command to discover the address of the display on |I2C| bus 2, as shown in :ref:`displays_i2cdetect`.
diff --git a/books/beaglebone-cookbook/09capes/capes.rst b/books/beaglebone-cookbook/09capes/capes.rst
index d4ce5f730b1de2750db0c02ac53fcb7bea1018a5..0e38696e0c2efdd75ac20a7afbf84e98bdd9f2a2 100644
--- a/books/beaglebone-cookbook/09capes/capes.rst
+++ b/books/beaglebone-cookbook/09capes/capes.rst
@@ -31,6 +31,8 @@ You want to display the Bone's desktop on a portable LCD.
Solution
--------
+.. note:: #TODO# The 4D Systems LCD capes would make a better example. CircuitCo is out of business.
+
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.
@@ -83,7 +85,7 @@ You want to use a small LCD to display things other than the desktop.
Solution
---------
-The `MiniDisplay <http://bit.ly/1xd0r8>`p_ is a 128 x 128 full-color LCD cape that just fits on the
+The `MiniDisplay <http://bit.ly/1xd0r8p>`_ 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:
@@ -120,7 +122,7 @@ Attach to the Bone and apply power. Then run the following commands:
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
+.. code-block:: shell-session
bone$ export SLOTS=/sys/devices/bone_capemgr.*/slots
bone$ echo BB-SPIDEV0 > $SLOTS
@@ -128,53 +130,54 @@ The `manufacturer's website <http://bit.ly/1xd0r8p>`_ suggests enabling SPI0 by
Hmmm, something isn't working here. Here's how to see what happened:
-.. code-block:: bash
+.. callout::
+
+ .. code-block:: shell-session
- 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
- [ 625.334769] bone_capemgr.9: slot #11: 'Override Board Name,00A0,Override \
- Manuf,BB-SPIDEV0'
- [ 625.335026] bone_capemgr.9: slot #11: \Requesting part number/version based \
- 'BB-SPIDEV0-00A0.dtbo
- [ 625.335076] bone_capemgr.9: slot #11: Requesting firmware \
- 'BB-SPIDEV0-00A0.dtbo' \
- for board-name 'Override Board Name', version '00A0'
- [ 625.335144] bone_capemgr.9: slot #11: dtbo 'BB-SPIDEV0-00A0.dtbo' loaded; \
- converting to live tree
- [ 625.341842] bone_capemgr.9: slot #11: BB-SPIDEV0 conflict P9.21 \
- (#10:bspwm_P9_21_b) <a class="co" id="capemgr_conflict_co" href="#capemgr_conflict" ><img src="callouts/1.png" alt="1"/></a>
- [ 625.351296] bone_capemgr.9: slot #11: Failed verification
+ 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
+ [ 625.334769] bone_capemgr.9: slot #11: 'Override Board Name,00A0,Override \
+ Manuf,BB-SPIDEV0'
+ [ 625.335026] bone_capemgr.9: slot #11: \Requesting part number/version based \
+ 'BB-SPIDEV0-00A0.dtbo
+ [ 625.335076] bone_capemgr.9: slot #11: Requesting firmware \
+ 'BB-SPIDEV0-00A0.dtbo' \
+ for board-name 'Override Board Name', version '00A0'
+ [ 625.335144] bone_capemgr.9: slot #11: dtbo 'BB-SPIDEV0-00A0.dtbo' loaded; \
+ converting to live tree
+ [ 625.341842] bone_capemgr.9: slot #11: BB-SPIDEV0 conflict P9.21 \
+ (#10:bspwm_P9_21_b) # <1>
+ [ 625.351296] bone_capemgr.9: slot #11: Failed verification
+
+ .. annotations::
+
+ <1> Shows there is a conflict for pin <code>P9_21</code>: it's already configured for pulse width modulation (PWM).
+Here's how to see what's already configured:
-.. <dl class="calloutlist">
-.. <dt><a class="co" id="capemgr_conflict" href="#capemgr_conflict_co"><img src="callouts/1.png" alt="1"/></a></dt>
-.. <dd>Shows there is a conflict for pin <code>P9_21</code>: it's already configured for pulse width modulation (PWM).</dd>
-.. </dl>
-Here's how to see what's already configured:
+.. callout::
-.. code-block:: bash
+ .. code-block:: shell-session
- bone$ cat $SLOTS
- 0: 54:PF---
- 1: 55:PF---
- 2: 56:PF---
- 3: 57:PF---
- 4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
- 5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI
- 7: ff:P-O-L Override Board Name,00A0,Override Manuf,bspm_P9_42_27
- 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
- 10: ff:P-O-L Override Board Name,00A0,Override Manuf,bspwm_P9_21_b <a class="co" id="capemgr_load_co" href="#capemgr_load"><img src="callouts/1.png" alt="1"/></a>
+ bone$ cat $SLOTS
+ 0: 54:PF---
+ 1: 55:PF---
+ 2: 56:PF---
+ 3: 57:PF---
+ 4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
+ 5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI
+ 7: ff:P-O-L Override Board Name,00A0,Override Manuf,bspm_P9_42_27
+ 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
+ 10: ff:P-O-L Override Board Name,00A0,Override Manuf,bspwm_P9_21_b # <1>
+ .. annotations::
-.. <dl class="calloutlist">
-.. <dt><a id="capemgr_load" href="#capemgr_load_co"><img src="callouts/1.png" alt="1"/></a></dt>
-.. <dd>You can see the eMMC, HDMI, and three PWMs are already using some of the pins. Slot 10 shows <code>P9_21</code> is in use by a PWM.</dd>
-.. </dl>
+ <1> You can see the eMMC, HDMI, and three PWMs are already using some of the pins. Slot 10 shows <code>P9_21</code> is in use by a PWM.
You can unconfigure it by using the following commands:
@@ -257,6 +260,8 @@ LCD Backside
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/>`_.
+.. note:: #TODO# One of the 4D Systems LCD capes would make a better example for an LCD cape. The CircuitCo cape is no longer available.
+
.. figure:: figures/LCD7back.png
:align: center
:alt:
@@ -264,6 +269,8 @@ LCD Backside
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.
+.. note:: #TODO# Bela would make a better example for an audio cape. The CircuitCo cape is no longer available.
+
.. _Audio_cape_pins_fig:
Audio cape pins
@@ -292,7 +299,7 @@ In most cases, the same pin should never be used on two different capes, though
- I2C2_SCL and I2C2_SDA
- |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.
-.. |I2C| replace:: I\ :sub:`2`\ C
+.. |I2C| replace:: I\ :sup:`2`\ C
.. _capes_soldering:
@@ -425,147 +432,146 @@ the test status with the code in :ref:`capes_quickBot_motor_test_code`.
Testing the quickBot motors interface (quickBot_motor_test.js)
==============================================================
-.. code-block:: bash
+.. callout::
+
+ .. code-block:: javascript
+
+ #!/usr/bin/env node
+ var b = require('bonescript');
+ var M1_SPEED = 'P9_16'; // <1>
+ var M1_FORWARD = 'P8_15';
+ var M1_BACKWARD = 'P8_13';
+ var M2_SPEED = 'P9_14';
+ var M2_FORWARD = 'P8_9';
+ var M2_BACKWARD = 'P8_11';
+ var freq = 50; // <2>
+ var fast = 0.95;
+ var slow = 0.7;
+ var state = 0; // <3>
+
+ b.pinMode(M1_FORWARD, b.OUTPUT); // <4>
+ b.pinMode(M1_BACKWARD, b.OUTPUT);
+ b.pinMode(M2_FORWARD, b.OUTPUT);
+ b.pinMode(M2_BACKWARD, b.OUTPUT);
+ b.analogWrite(M1_SPEED, 0, freq); // <5>
+ b.analogWrite(M2_SPEED, 0, freq);
+
+ updateMotors(); // <6>
+
+ function updateMotors() {
+ //console.log("Setting state = " + state); // <7>
+ updateLEDs(state);
+ switch(state) { // <3>
+ case 0:
+ default:
+ M1_set(0); // <8>
+ M2_set(0);
+ state = 1; // <3>
+ break;
+ case 1:
+ M1_set(slow);
+ M2_set(slow);
+ state = 2;
+ break;
+ case 2:
+ M1_set(slow);
+ M2_set(-slow);
+ state = 3;
+ break;
+ case 3:
+ M1_set(-slow);
+ M2_set(slow);
+ state = 4;
+ break;
+ case 4:
+ M1_set(fast);
+ M2_set(fast);
+ state = 0;
+ break;
+ }
+ setTimeout(updateMotors, 2000); // <3>
+ }
- #!/usr/bin/env node
- var b = require('bonescript');
- var M1_SPEED = 'P9_16'; <a class="co" id="co_hello_CO1-1_unique" href="#callout_hello_CO1-1_unique"><img src="callouts/1.png" alt="1"/></a>
- var M1_FORWARD = 'P8_15';
- var M1_BACKWARD = 'P8_13';
- var M2_SPEED = 'P9_14';
- var M2_FORWARD = 'P8_9';
- var M2_BACKWARD = 'P8_11';
- var freq = 50; <a class="co" id="co_hello_CO1-2_unique" href="#callout_hello_CO1-2_unique"><img src="callouts/2.png" alt="2"/></a>
- var fast = 0.95;
- var slow = 0.7;
- var state = 0; <a class="co" id="co_hello_CO1-3_unique" href="#callout_hello_CO1-3_unique"><img src="callouts/3.png" alt="3"/></a>
-
- b.pinMode(M1_FORWARD, b.OUTPUT); <a class="co" id="co_hello_CO1-4_unique" href="#callout_hello_CO1-4_unique"><img src="callouts/4.png" alt="4"/></a>
- b.pinMode(M1_BACKWARD, b.OUTPUT);
- b.pinMode(M2_FORWARD, b.OUTPUT);
- b.pinMode(M2_BACKWARD, b.OUTPUT);
- b.analogWrite(M1_SPEED, 0, freq); <a class="co" id="co_hello_CO1-5_unique" href="#callout_hello_CO1-5_unique"><img src="callouts/5.png" alt="5"/></a>
- b.analogWrite(M2_SPEED, 0, freq);
-
- updateMotors(); <a class="co" id="co_hello_CO1-6_unique" href="#callout_hello_CO1-6_unique"><img src="callouts/6.png" alt="6"/></a>
-
- function updateMotors() { <img src="callouts/6.png" alt="6"/>
- //console.log("Setting state = " + state); <a class="co" id="co_hello_CO1-7_unique" href="#callout_hello_CO1-7_unique"><img src="callouts/7.png" alt="7"/></a>
- updateLEDs(state); <img src="callouts/7.png" alt="7"/>
- switch(state) { <img src="callouts/3.png" alt="3"/>
+ function updateLEDs(state) { // <7>
+ switch(state) {
case 0:
- default:
- M1_set(0); <a class="co" id="co_hello_CO1-8_unique" href="#callout_hello_CO1-8_unique"><img src="callouts/8.png" alt="8"/></a>
- M2_set(0);
- state = 1; <img src="callouts/3.png" alt="3"/>
+ b.digitalWrite("USR0", b.LOW);
+ b.digitalWrite("USR1", b.LOW);
+ b.digitalWrite("USR2", b.LOW);
+ b.digitalWrite("USR3", b.LOW);
break;
case 1:
- M1_set(slow);
- M2_set(slow);
- state = 2;
+ b.digitalWrite("USR0", b.HIGH);
+ b.digitalWrite("USR1", b.LOW);
+ b.digitalWrite("USR2", b.LOW);
+ b.digitalWrite("USR3", b.LOW);
break;
case 2:
- M1_set(slow);
- M2_set(-slow);
- state = 3;
+ b.digitalWrite("USR0", b.LOW);
+ b.digitalWrite("USR1", b.HIGH);
+ b.digitalWrite("USR2", b.LOW);
+ b.digitalWrite("USR3", b.LOW);
break;
case 3:
- M1_set(-slow);
- M2_set(slow);
- state = 4;
+ b.digitalWrite("USR0", b.LOW);
+ b.digitalWrite("USR1", b.LOW);
+ b.digitalWrite("USR2", b.HIGH);
+ b.digitalWrite("USR3", b.LOW);
break;
case 4:
- M1_set(fast);
- M2_set(fast);
- state = 0;
+ b.digitalWrite("USR0", b.LOW);
+ b.digitalWrite("USR1", b.LOW);
+ b.digitalWrite("USR2", b.LOW);
+ b.digitalWrite("USR3", b.HIGH);
break;
+ }
}
- setTimeout(updateMotors, 2000); <img src="callouts/3.png" alt="3"/>
- }
-
- function updateLEDs(state) { <img src="callouts/7.png" alt="7"/>
- switch(state) {
- case 0:
- b.digitalWrite("USR0", b.LOW);
- b.digitalWrite("USR1", b.LOW);
- b.digitalWrite("USR2", b.LOW);
- b.digitalWrite("USR3", b.LOW);
- break;
- case 1:
- b.digitalWrite("USR0", b.HIGH);
- b.digitalWrite("USR1", b.LOW);
- b.digitalWrite("USR2", b.LOW);
- b.digitalWrite("USR3", b.LOW);
- break;
- case 2:
- b.digitalWrite("USR0", b.LOW);
- b.digitalWrite("USR1", b.HIGH);
- b.digitalWrite("USR2", b.LOW);
- b.digitalWrite("USR3", b.LOW);
- break;
- case 3:
- b.digitalWrite("USR0", b.LOW);
- b.digitalWrite("USR1", b.LOW);
- b.digitalWrite("USR2", b.HIGH);
- b.digitalWrite("USR3", b.LOW);
- break;
- case 4:
- b.digitalWrite("USR0", b.LOW);
- b.digitalWrite("USR1", b.LOW);
- b.digitalWrite("USR2", b.LOW);
- b.digitalWrite("USR3", b.HIGH);
- break;
- }
- }
-
- function M1_set(speed) { <img src="callouts/8.png" alt="8"/>
- speed = (speed > 1) ? 1 : speed; <a class="co" id="co_hello_CO1-9_unique" href="#callout_hello_CO1-9_unique"><img src="callouts/9.png" alt="9"/></a>
- speed = (speed < -1) ? -1 : speed;
- b.digitalWrite(M1_FORWARD, b.LOW);
- b.digitalWrite(M1_BACKWARD, b.LOW);
- if(speed > 0) {
- b.digitalWrite(M1_FORWARD, b.HIGH);
- } else if(speed < 0) {
- b.digitalWrite(M1_BACKWARD, b.HIGH);
- }
- b.analogWrite(M1_SPEED, Math.abs(speed), freq); <a class="co" id="co_hello_CO1-10_unique" href="#callout_hello_CO1-10_unique"><img src="callouts/10.png" alt="10"/></a>
- }
-
- function M2_set(speed) {
- speed = (speed > 1) ? 1 : speed;
- speed = (speed < -1) ? -1 : speed;
- b.digitalWrite(M2_FORWARD, b.LOW);
- b.digitalWrite(M2_BACKWARD, b.LOW);
- if(speed > 0) {
- b.digitalWrite(M2_FORWARD, b.HIGH);
- } else if(speed < 0) {
- b.digitalWrite(M2_BACKWARD, b.HIGH);
+
+ function M1_set(speed) { <img src="callouts/8.png" alt="8"/>
+ speed = (speed > 1) ? 1 : speed; // <9>
+ speed = (speed < -1) ? -1 : speed;
+ b.digitalWrite(M1_FORWARD, b.LOW);
+ b.digitalWrite(M1_BACKWARD, b.LOW);
+ if(speed > 0) {
+ b.digitalWrite(M1_FORWARD, b.HIGH);
+ } else if(speed < 0) {
+ b.digitalWrite(M1_BACKWARD, b.HIGH);
+ }
+ b.analogWrite(M1_SPEED, Math.abs(speed), freq); // <10>
}
- b.analogWrite(M2_SPEED, Math.abs(speed), freq);
+ function M2_set(speed) {
+ speed = (speed > 1) ? 1 : speed;
+ speed = (speed < -1) ? -1 : speed;
+ b.digitalWrite(M2_FORWARD, b.LOW);
+ b.digitalWrite(M2_BACKWARD, b.LOW);
+ if(speed > 0) {
+ b.digitalWrite(M2_FORWARD, b.HIGH);
+ } else if(speed < 0) {
+ b.digitalWrite(M2_BACKWARD, b.HIGH);
+ }
+ b.analogWrite(M2_SPEED, Math.abs(speed), freq);
-.. <dl class="calloutlist">
-.. <dt><a class="co" id="callout_hello_CO1-1_unique" href="#co_hello_CO1-1_unique"><img src="callouts/1.png" alt="1"/></a></dt>
-.. <dd><p>Define each pin as a variable. This makes it easy to change to another pin if you decide that is necessary.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-2_unique" href="#co_hello_CO1-2_unique"><img src="callouts/2.png" alt="2"/></a></dt>
-.. <dd><p>Make other simple parameters variables. Again, this makes it easy to update them. When creating this test, I found that the PWM frequency to drive the motors needed to be relatively low to get over the kickback shown in <a data-type="xref" href="#quickBot_motor_kickback"/>. I also found that I needed to get up to about 70 percent duty cycle for my circuit to reliably start the motors turning.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-3_unique" href="#co_hello_CO1-3_unique"><img src="callouts/3.png" alt="3"/></a></dt>
-.. <dd><p>Use a simple variable such as <code>state</code> to keep track of the test phase. This is used in a <code>switch</code> statement to jump to the code to configure for that test phase and updated after configuring for the current phase in order to select the next phase. Note that the next phase isn’t entered until after a two-second delay, as specified in the call to <code>setTimeout()</code>.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-4_unique" href="#co_hello_CO1-4_unique"><img src="callouts/4.png" alt="4"/></a></dt>
-.. <dd><p>Perform the initial setup of all the pins.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-5_unique" href="#co_hello_CO1-5_unique"><img src="callouts/5.png" alt="5"/></a></dt>
-.. <dd><p>The first time a PWM pin is used, it is configured with the update frequency. It is important to set this just once to the right frequency, because other PWM channels might use the same PWM controller, and attempts to reset the PWM frequency might fail. The <code>pinMode()</code> function doesn’t have an argument for providing the update frequency, so use the <code>analogWrite()</code> function, instead. You can review using the PWM in <a data-type="xref" href="#motors_servo"/>.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-6_unique" href="#co_hello_CO1-6_unique"><img src="callouts/6.png" alt="6"/></a></dt>
-.. <dd><p><code>updateMotors()</code> is the test function for the motors and is defined after all the setup and initialization code. The code calls this function every two seconds using the <code>setTimeout()</code> JavaScript function. The first call is used to prime the loop.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-7_unique" href="#co_hello_CO1-7_unique"><img src="callouts/7.png" alt="7"/></a></dt>
-.. <dd><p>The call to <code>console.log()</code> was initially here to observe the state transitions in the debug console, but it was replaced with the <code>updateLEDs()</code> call. Using the <code>USER</code> LEDs makes it possible to note the state transitions without having visibility of the debug console. <code>updateLEDs()</code> is defined later.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-8_unique" href="#co_hello_CO1-8_unique"><img src="callouts/8.png" alt="8"/></a></dt>
-.. <dd><p>The <code>M1_set()</code> and <code>M2_set()</code> functions are defined near the bottom and do the work of configuring the motor drivers into a particular state. They take a single argument of <code>speed</code>, as defined between <code>-1</code> (maximum reverse), <code>0</code> (stop), and <code>1</code> (maximum forward).</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-9_unique" href="#co_hello_CO1-9_unique"><img src="callouts/9.png" alt="9"/></a></dt>
-.. <dd><p>Perform simple bounds checking to ensure that speed values are between <code>-1</code> and <code>1</code>.</p></dd>
-.. <dt><a class="co" id="callout_hello_CO1-10_unique" href="#co_hello_CO1-10_unique"><img src="callouts/10.png" alt="10"/></a></dt>
-.. <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>
+
+ <1> Define each pin as a variable. This makes it easy to change to another pin if you decide that is necessary.
+
+ <2> Make other simple parameters variables. Again, this makes it easy to update them. When creating this test, I found that the PWM frequency to drive the motors needed to be relatively low to get over the kickback shown in :ref:`quickBot_motor_kickback`. I also found that I needed to get up to about 70 percent duty cycle for my circuit to reliably start the motors turning.
+
+ <3> Use a simple variable such as `state` to keep track of the test phase. This is used in a `switch` statement to jump to the code to configure for that test phase and updated after configuring for the current phase in order to select the next phase. Note that the next phase isn’t entered until after a two-second delay, as specified in the call to `setTimeout()`.
+
+ <4> Perform the initial setup of all the pins.
+
+ <5> The first time a PWM pin is used, it is configured with the update frequency. It is important to set this just once to the right frequency, because other PWM channels might use the same PWM controller, and attempts to reset the PWM frequency might fail. The <code>pinMode()</code> function doesn’t have an argument for providing the update frequency, so use the <code>analogWrite()</code> function, instead. You can review using the PWM in :ref:`motors_servo`.
+
+ <6> `updateMotors()` is the test function for the motors and is defined after all the setup and initialization code. The code calls this function every two seconds using the `setTimeout()` JavaScript function. The first call is used to prime the loop.
+
+ <7> The call to `console.log()` was initially here to observe the state transitions in the debug console, but it was replaced with the `updateLEDs()` call. Using the `USER` LEDs makes it possible to note the state transitions without having visibility of the debug console. `updateLEDs()` is defined later.
+
+ <8> The `M1_set()` and `M2_set()` functions are defined near the bottom and do the work of configuring the motor drivers into a particular state. They take a single argument of `speed`, as defined between `-1` (maximum reverse), `0` (stop), and `1` (maximum forward).
+
+ <9> Perform simple bounds checking to ensure that speed values are between `-1` and `1`.
+
+ <10> The `analogWrite()` call uses the absolute value of `speed`, making any negative numbers a positive magnitude.
.. _quickBot_motor_kickback:
@@ -667,7 +673,7 @@ Outline SVG for BeagleBone cape (beaglebone_cape_boardoutline.svg)
.. </dl>
.. ++++
-The measurements are taken from the `BeagleBone Black System Reference Manual <http://bit.ly/1C5rSa8>`_, as shown in :ref:`capes_dimensions_fig`.
+The measurements are taken from the :ref:`beagleboneblack-mechanical` section of the :ref:`BeagleBone Black System Reference Manual <beagleboneblack-home>`, as shown in :ref:`capes_dimensions_fig`.
.. _capes_dimensions_fig:
@@ -1227,15 +1233,6 @@ There's no real substitute for getting to know your contract manufacturer, its c
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
-
-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
-service. CircuitCo would be an excellent choice for you to consider to perform your contract
-manufacturing, but it doesn't offer an online quote service at this point, so it isn't as easy
-to include details on how to engage with it in this book.
-
+.. note::
+ Don't confuse CircuitHub and CircuitCo. CircuitCo is closed.
diff --git a/books/index.rst b/books/index.rst
index 1cf8a938c3c882893ede9788f121becfe756a4e1..4640aed024bb3d01e4e17a197c4c7c53acb6be1e 100644
--- a/books/index.rst
+++ b/books/index.rst
@@ -1,3 +1,5 @@
+.. _books-home:
+
Books
*****
diff --git a/books/pru-cookbook/01case/case.rst b/books/pru-cookbook/01case/case.rst
index 5f5cbd4427e75a72d89f3c8fc7c38beff29ad000..27b035e7b26567643cd455398c632543aefb8d3a 100644
--- a/books/pru-cookbook/01case/case.rst
+++ b/books/pru-cookbook/01case/case.rst
@@ -35,7 +35,7 @@ Here we present:
.. TODO Switch from LEDscape to FPP
-* `Robotics Control Library <http://strawsondesign.com/docs/roboticscape/>`_
+* `Robotics Control Library <https://beagleboard.org/librobotcontrol>`_
* `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>`_
@@ -77,7 +77,7 @@ in :ref:`case_blue`.
Blue balancing
-The `Robotics Control Library <http://strawsondesign.com/docs/roboticscape/>`_ is a
+The `Robotics Control Library <https://beagleboard.org/librobotcontrol>`_ 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
real-time hardware of the Bone by adding eight addional servo channels and one
diff --git a/books/pru-cookbook/05blocks/blocks.rst b/books/pru-cookbook/05blocks/blocks.rst
index 1b62a966b494ee426a8889a35a6dc55f7a4723ce..f675235cf1ead5bf16c306fb0cd0d1c87e19acc6 100644
--- a/books/pru-cookbook/05blocks/blocks.rst
+++ b/books/pru-cookbook/05blocks/blocks.rst
@@ -7,14 +7,15 @@ Here are some examples that use the basic PRU building blocks.
The following are resources used in this chapter.
-Resources
-~~~~~~~~~~
-
-* `PRU Optimizing C/C++ Compiler, v2.2, User's Guide <http://www.ti.com/lit/ug/spruhv7b/spruhv7b.pdf>`_
-* `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)
-* `Exploring BeagleBone by Derek Molloy <http://exploringbeaglebone.com/>`_
-* `WS2812 Data Sheet <https://cdn-shop.adafruit.com/datasheets/WS2812.pdf>`_
+.. note::
+
+ *Resources*
+
+ * `PRU Optimizing C/C++ Compiler, v2.2, User's Guide <http://www.ti.com/lit/ug/spruhv7b/spruhv7b.pdf>`_
+ * `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)
+ * `Exploring BeagleBone by Derek Molloy <http://exploringbeaglebone.com/>`_
+ * `WS2812 Data Sheet <https://cdn-shop.adafruit.com/datasheets/WS2812.pdf>`_
.. _memory_allocation:
diff --git a/books/pru-cookbook/06io/io.rst b/books/pru-cookbook/06io/io.rst
index 2d019de052e72f85e56e46de66aabefa90d3393f..80f20a5398e1a92a1e3877d5bc5489136bb06b62 100644
--- a/books/pru-cookbook/06io/io.rst
+++ b/books/pru-cookbook/06io/io.rst
@@ -8,14 +8,15 @@ through the ``pass:[__]R30`` register. Below shows how more GPIO pins can be ac
The following are resources used in this chapter.
-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)
-* `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>`_
+.. note::
+
+ *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)
+ * `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>`_
Editing /boot/uEnv.txt to Access the P8 Header on the Black
************************************************************
diff --git a/books/pru-cookbook/07more/more.rst b/books/pru-cookbook/07more/more.rst
index 4bae78b1e7ed12d2fffc840e510b5c82227df88b..f70501a89114ba2cc339e882ae638fa806035618 100644
--- a/books/pru-cookbook/07more/more.rst
+++ b/books/pru-cookbook/07more/more.rst
@@ -14,12 +14,13 @@ C. Detailing on how to program in assembly are beyond the scope of this text.
The following are resources used in this chapter.
-Resources
-~~~~~~~~~~
+.. note::
-* `PRU Optimizing C/C++ Compiler, v2.2, User's Guide <http://www.ti.com/lit/ug/spruhv7b/spruhv7b.pdf>`_
-* `PRU Assembly Language Tools User's Guide <http://www.ti.com/lit/ug/spruhv6b/spruhv6b.pdf>`_
-* `PRU Assembly Instruction User Guide <http://www.ti.com/lit/ug/spruij2/spruij2.pdf>`_
+ *Resources*
+
+ * `PRU Optimizing C/C++ Compiler, v2.2, User's Guide <http://www.ti.com/lit/ug/spruhv7b/spruhv7b.pdf>`_
+ * `PRU Assembly Language Tools User's Guide <http://www.ti.com/lit/ug/spruhv6b/spruhv6b.pdf>`_
+ * `PRU Assembly Instruction User Guide <http://www.ti.com/lit/ug/spruij2/spruij2.pdf>`_
Calling Assembly from C
************************
diff --git a/books/pru-cookbook/08ai/ai.rst b/books/pru-cookbook/08ai/ai.rst
index ca50756249c475876c5b6b6da33358eb63a8f63c..d2e055c07bbeb80cc9334210f4db78e3503c589e 100644
--- a/books/pru-cookbook/08ai/ai.rst
+++ b/books/pru-cookbook/08ai/ai.rst
@@ -11,11 +11,12 @@ four PRUs.
The following are resources used in this chapter.
-Resources
-~~~~~~~~~~~
+.. note::
-* `AM572x Technical Reference Manual <http://www.ti.com/lit/pdf/spruhz6l>`_ (AI)
-* `BeagleBone AI PRU pins <https://docs.google.com/spreadsheets/d/1dFSBVem86vAUD7MLXvqdS-N0Efi8_g_O1iTqzql8DAo/edit#gid=0>`_
+ *Resources*
+
+ * `AM572x Technical Reference Manual <http://www.ti.com/lit/pdf/spruhz6l>`_ (AI)
+ * `BeagleBone AI PRU pins <https://docs.google.com/spreadsheets/d/1dFSBVem86vAUD7MLXvqdS-N0Efi8_g_O1iTqzql8DAo/edit#gid=0>`_
Moving from two to four PRUs
*****************************
diff --git a/books/pru-cookbook/projects.rst b/books/pru-cookbook/projects.rst
index 39263b91e03c611604c1e60d416f92e1db44e1b3..60a2482b22bcb7942b2a6a9cf66657b4077436c1 100644
--- a/books/pru-cookbook/projects.rst
+++ b/books/pru-cookbook/projects.rst
@@ -7,9 +7,6 @@ Users of TI processors with PRU-ICSS have created application for many different
A list of a few are shared below. For additional support resources, software and
documentation visit the PRU-ICSS wiki.
-PRU projects
-~~~~~~~~~~~~~~
-
.. dropdown:: **LEDscape**
:open:
@@ -158,7 +155,7 @@ PRU projects
**Type:** Code Library Reference
**References:**
- * http://processors.wiki.ti.com/index.php/Soft-UART_Implementation_on_AM335X_PRU_-_Software_Users_Guide
+ * https://software-dl.ti.com/processor-sdk-linux/esd/docs/latest/linux/Foundational_Components/PRU-ICSS/Linux_Drivers/pru-sw-uart.html
.. dropdown:: **Deviant LCD**
:open:
@@ -308,4 +305,4 @@ PRU projects
**Type:** Code Library
**References:**
- * https://github.com/deepakkarki/pruspeak
\ No newline at end of file
+ * https://github.com/deepakkarki/pruspeak
diff --git a/conf.py b/conf.py
index 5a04178d00bc40614379d589726dfd08cab98efa..448c97127e30c0ffb2a3feb944c7ac35f439710b 100644
--- a/conf.py
+++ b/conf.py
@@ -120,8 +120,8 @@ html_context = {
"versions": ("latest", "0.0", "0.1"),
"reference_links": {
"About": "https://beagleboard.org/about",
- "Donate": "https://beagleboard.org/donate/",
- "FAQ": "https://beagleboard.org/Support/FAQ"
+ "Donate": "https://beagleboard.org/donate",
+ "FAQ": "https://forum.beagleboard.org/c/faq"
}
}
diff --git a/index.rst b/index.rst
index 5bf6fc53764f1cd503cdacb8ce1354548d0837db..872f7eeab8507d68ace7e2a40605360893120e66 100644
--- a/index.rst
+++ b/index.rst
@@ -17,10 +17,10 @@ Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/d
Introduction
************
-Get started by `engaging the BealgeBoard.org developer community </intro/>`__.
+Get started engaging the BeagleBoard.org developer community by reading our :ref:`introduction` page.
-* Read about how to: `get started and get help </intro/support>`__
-* Learn how to: `contribute to the project </intro/contribution>`__
+* Read about how to get started and get help on our :ref:`support` page.
+* Learn how to contribute to the project on our :ref:`contribution` page.
.. toctree::
:maxdepth: 2
@@ -42,9 +42,9 @@ design, including the
`materials <https://git.beagleboard.org/explore/projects/topics/boards>`__ to modify the designs
from source using appropriate design tools.
-* Check out our most popular board at: `BeagleBone Black </boards/beaglebone/black>`__
-* Check out our latest board at: `BeagleBone AI-64 </boards/beaglebone/ai-64>`__
-* Find all of our on: `our boards page </boards/index>`__
+* Check out our most popular board at: :ref:`beagleboneblack-home`
+* Check out our latest board at: :ref:`bbai64-home`
+* Find all of our on: :ref:`boards`
.. grid:: 1 1 1 2
:margin: 4 4 0 0
@@ -183,6 +183,8 @@ Capes
movement, sensing, power management and communication
.. grid-item-card::
+ :link: bone-cape-relay
+ :link-type: ref
**BeagleBone® Relay Cape**
^^^
@@ -308,8 +310,8 @@ Capes
Projects
********
-A number of software projects, like `SimpPRU </projects/simppru/index>`__ exist to help Beagle
-developers. Some developers choose to host documentation for their projects `here </projects/index>`__.
+A number of software projects, like :ref:`simppru_home` exist to help Beagle
+developers. Some developers choose to host documentation for their :ref:`projects-home` .
.. toctree::
:maxdepth: 1
@@ -317,16 +319,15 @@ developers. Some developers choose to host documentation for their projects `her
:caption: Projects
/projects/simppru/index
- /boards/beagleconnect/technology/index
+ /boards/beagleconnect/index
Books
*****
-This project hosts a
-`collection of open-source books written to help Beagle developers </books/index>`__.
+This project hosts a collection of open-source :ref:`books-home` books written to help Beagle developers.
-* Find a great introduction to BeagleBone at: `BeagleBone Cookbook </books/beaglebone-cookbook>`__
-* Learn one of the most amazing Beagle features at: `PRU Cookbook </books/pru-cookbook>`__
+* Find a great introduction to BeagleBone at: :ref:`bone-cook-book-home`
+* Learn one of the most amazing Beagle features at: :ref:`pru-cookbook-home`
.. toctree::
:maxdepth: 1
diff --git a/intro/contribution/index.rst b/intro/contribution/index.rst
index bd4ecc99215c52822287dc2aaa54f98d682feb10..642543c080e3a042a88223f17e1cce84cbb73ca7 100644
--- a/intro/contribution/index.rst
+++ b/intro/contribution/index.rst
@@ -1,4 +1,4 @@
-.. _beagleboard-contributoin:
+.. _contribution:
Contribution
###############
@@ -9,6 +9,9 @@ Contribution
.. important::
First off, thanks for taking the time to think about contributing!
+.. note::
+ For donations, see `BeagleBoard.org - Donate <https://beagleboard.org/donate>`__.
+
The BeagleBoard.org Foundation maintains source for many open source projects.
Example projects suitable for first contributions:
@@ -23,10 +26,10 @@ to propose changes to this document in a pull request.
Code of Conduct
***************
-This project and everyone participating in it is governed by the same code of conduct.
+This project and everyone participating are governed by the same code of conduct.
.. note::
- Check out https://forum.beagleboard.org/faq as a starting place to unify our code of conduct.
+ Check out https://forum.beagleboard.org/faq as a starting place for our code of conduct.
By participating, you are expected to
uphold this code. Please report unacceptable behavior to
@@ -35,22 +38,42 @@ contact one of our administrators or moderators on https://forum.beagleboard.org
Frequently Asked Questions
**************************
-* `Frequently asked questions contribution category on the BeagleBoard.org Forum <https://forum.beagleboard.org/c/faq/19>`__
+Please refer to the technical and contribution frequently asked questions pages before posting any of your own questions. Please
+feel encouraged to ask follow-up questions if any of the answers are not clear enough.
+
+* `Frequently asked questions contribution category on the BeagleBoard.org Forum <https://forum.beagleboard.org/c/faq>`__
What should I know before I get started?
****************************************
+The more you know about Linux and contributing to upstream projects, the better, but this knowledge isn't strictly required. Simply
+reading about contributing to Linux and upstream projects can help build your vocabulary in a meaningful way to help out. Learn about
+the skills required for Linux contributions in the :ref:`beagleboard-linux-upstream` section.
+
+The most useful thing to know is how to ask smart questions. Read about this in the :ref:`intro-getting-support` section. If you ask
+smart questions on the issue trackers and forum, you'll be doing a lot to help us improve the designs and documentation.
+
+.. toctree::
+ :maxdepth: 1
+ :hidden:
+
+ /intro/contribution/linux-upstream
+
How can I contribute?
*********************
+The most obvious way to contribute is using the `git.beagleboard.org Gitlab server <https://git.beagleboard.org>`_ to report
+bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware
+designs and documentation.
+
Reporting bugs
===============
Suggesting enhancements
=======================
-Submitting pull requests
-========================
+Submitting merge requests
+=========================
Style and usage guidelines
**************************
diff --git a/intro/contribution/linux-upstream.rst b/intro/contribution/linux-upstream.rst
new file mode 100644
index 0000000000000000000000000000000000000000..267f4698dacfca7e3ebc9c4cf186aea372d56fd5
--- /dev/null
+++ b/intro/contribution/linux-upstream.rst
@@ -0,0 +1,187 @@
+.. _beagleboard-linux-upstream:
+
+Upstream Kernel Contributions
+#############################
+
+.. note::
+ For detailed information on Kernel Developmement checkout the official
+ `kernel.org <https://www.kernel.org/doc/html/latest/>`_
+ kernel docs.
+
+For a person or company who wishes to submit a change to the Linux kernel,
+the process can sometimes be daunting if you’re not familiar with “the system.â€
+This text is a collection of suggestions which can help you get started and greatly increase the chances
+of your change being accepted.
+
+.. note:: This version is an unofficial draft and is subject to change.
+
+Pre-requisites
+***************
+
+The following are the skills that are needed before you actually start to contribute to the linux kernel:
+
+ - :ref:`linux-upstream-more-git`
+ - :ref:`linux-upstream-c-programming`
+ - :ref:`linux-upstream-cross-arch`
+ - :ref:`linux-upstream-embedded-busses`
+ - :ref:`linux-upstream-drivers`
+ - :ref:`linux-upstream-device-trees`
+
+For more guidance, check out the :ref:`linux-upstream-additional-resources`.
+
+.. _linux-upstream-more-git:
+
+More Git!
+*********
+
+It is highly recommended that you go through :ref:`beagleboard-git-usage` before starting
+to read and follow these guidelines. You will need to have a proper git setup on your
+computer inorder to effectively follow these steps.
+
+Creating your first patch
+=========================
+
+When you first enter the world of Linux Kernel development from a background in
+contributing over gitlab or github, the terminologies slightly change.
+
+Your Pull Requests (PRs) now become Patches or Patch Series. You no longer just
+go to some website and click on a "Create Pull Request" button. Whatever code/changes you
+want to add will have to be sent as patches via emails.
+
+As an example, let's consider a commit to add the git section to these docs.
+I stage these changes first using ``git add -p``.
+
+.. code-block::
+
+ diff --git a/contribution/contribute.rst b/contribution/contribute.rst
+ index def100b..0af08c5 100644
+ --- a/contribution/contribute.rst
+ +++ b/contribution/contribute.rst
+
+Then, commit the above changes.
+
+**Note:** Don't forget to make your commit message descriptive of the feature
+you are adding or the work that you have done in that commit. The commit
+has to be self explanatory in itself. Link any references if you have used
+and paste any logs to prove your code works or if there is a fix.
+
+.. code-block::
+
+ git commit -vs
+
+ [linux-contrib 3bc0821] contribute.rst: Add git section
+ 1 file changed, 27 insertions(+), 1 deletion(-)
+
+Now, let's say we want to send this new feature to upstream kernel. You then have to create
+a patch file using the following command:
+
+.. code-block::
+
+ git format-patch -1 HEAD
+
+ 0001-contribute.rst-Add-git-section.patch
+
+This will generate one file that is generally referred to as the patch file.
+This is what you will now be sending upstream inorder to get your patch merged.
+But wait, there are a few more things we need to setup for sending a patch via e-mail.
+That is, ofcourse your email!
+
+For configuring your email ID for sending patches refer to this excellent stackoverflow thread,
+`configure git-send-email
+<https://stackoverflow.com/questions/68238912/how-to-configure-and-use-git-send-email-to-work-with-gmail-to-email-patches-to>`_.
+
+Finally, after you have configured you email properly, you can send out a patch using:
+
+.. code-block::
+
+ git send-email 0001-contribute.rst-Add-git-section.patch
+
+replacing ofcourse the above patchfile name with whatever was your own patch.
+This command will then ask you ``To whom should the emails be sent (if anyone)?``
+Here, you have to write the email address of the list you want to send out the patch to.
+
+``git send-email`` also has command line options like ``--to`` and ``--cc`` that you can also use
+to add more email addresses of whoever you want to keep in CC. Generally it is a good idea to keep yourself
+in CC.
+
+.. _linux-upstream-c-programming:
+
+C-Programming
+*************
+
+It is highly recommended that you have proficiency in C-Programming, because well the kernel is mostly
+written in C! For starters, you can go through Dennis Ritchie's C Programming book to understand
+the language and also solve the excercises given there for getting hands on.
+
+.. _linux-upstream-cross-arch:
+
+Cross-arch Development
+**********************
+
+While working with the kernel, you'll most likely not be compiling it on the machine
+that you intend to actually boot it on.
+For example if you are compiling the Kernel for BeageBone Black it's probably not ideal
+for you to actually clone the entire kernel on BBB and then compile it there.
+What you'd do instead is pick a much powerful machine like a Desktop PC or laptop and
+then use cross arch compilers like the arm-gcc for instance to compile the kernel for your
+target device.
+
+.. _linux-upstream-embedded-busses:
+
+Basics of embedded busses (I2C, UART, SPI, etc.)
+************************************************
+
+In the world of embedded, you often need to communicate with peripherals over very low level protocols.
+To name a few, I2C, UART, SPI, etc. are all serial protocols used to communicate with a variety of devices and
+peripherals.
+
+It's recommended to understand atleast the basics of each of the protocol so you know what's actually going
+on when you write for instance an I2C or SPI driver to communicate with let's say a sensor.
+
+.. _linux-upstream-drivers:
+
+Device Drivers in Embedded Systems
+**********************************
+
+I used the term "Drivers" in the above section, but what does it really mean?
+
+**Why "device" drivers?**
+
+TODO
+
+**Why do we need drivers?**
+
+TODO
+
+**What do drivers look like?**
+
+TODO
+
+.. _linux-upstream-device-trees:
+
+Device Trees
+************
+
+We just learned about drivers, and it's time that once you have written a driver in the kernel,
+you obviously want it to work! So how do we really tell the kernel which drivers to load?
+How do we, at boot time, instruct which devices are present on the board you are booting on?
+
+The kernel does not contain the description of the hardware,
+it is located in a separate binary: the device tree blob.
+
+**What is a Device Tree?**
+
+A device tree is used to describe system hardware. A boot program loads a device tree into a
+client program’s memory and passes a pointer to the device tree to the client.
+
+A device tree is a tree data structure with nodes that describe
+the physical devices in a system.
+
+.. _linux-upstream-additional-resources:
+
+Additional Resources
+********************
+
+1. `Device Trees for Dummies PDF <https://elinux.org/images/f/f9/Petazzoni-device-tree-dummies_0.pdf>`_
+2. `What are Device Drivers <https://tldp.org/LDP/tlk/dd/drivers.html>`_
+3. `Submitting your patches upstream <https://www.kernel.org/doc/html/v4.17/process/submitting-patches.html>`_
diff --git a/intro/index.rst b/intro/index.rst
index 939be4969e719e04a05f8b2176aaceb1f0f241c6..22fbdbc77802da87f94fcaa1e63460a6700d0d50 100644
--- a/intro/index.rst
+++ b/intro/index.rst
@@ -1,15 +1,17 @@
+.. _introduction:
+
Introduction
#############
Welcome to the BeagleBoard documentation project. If you are looking for help with your Beagle
open-hardware development platform, you've found the right place!
-Please check out our `Support Page <support>`__ to find out how to get started, resolve issues,
+Please check out our :ref:`support` page` to find out how to get started, resolve issues,
and engage the developer community.
Don't forget that this is an open-source project! Your contributions are welcome. Learn about how
to contribute to the BeagleBoard documentation project and any of the many open-source Beagle
-projects on-going on our `Contribution Page <contribution>`__.
+projects on-going on our :ref:`contribution` page.
.. toctree::
:maxdepth: 2
diff --git a/intro/support/index.rst b/intro/support/index.rst
index 40ec9248384513ffdc8a0c4cdc89c9882bfc78f7..992650418c922e3951f072df7bd3f4a6d3af3bf9 100644
--- a/intro/support/index.rst
+++ b/intro/support/index.rst
@@ -10,13 +10,14 @@ Getting started
The starting experience for all Beagles has been made to be as
consistent as is possible. For any of the Beagle Linux-based open
-hardware computers, visit our `getting started guide <getting-started>`__.
+hardware computers, visit :ref:`beagleboard-getting-started`.
.. toctree::
:maxdepth: 2
/intro/support/getting-started
+.. _intro-getting-support:
Getting support
***************
@@ -36,16 +37,16 @@ there.
Be sure to ask `smart questions <http://www.catb.org/~esr/faqs/smart-questions.html>`__
that provide the following:
-* What am I trying to accomplish?
-* What did find when researching how to accomplish it?
-* What are the detailed results of what I tried?
-* How did these results differ from what I expected?
-* What would I consider to be a success?
+* What are you trying to accomplish?
+* What did you find when researching how to accomplish it?
+* What are the detailed results of what you tried?
+* How did these results differ from what you expected?
+* What would you consider to be a success?
-.. note::
+.. important::
Remember that community developers are volunteering their expertise. If you
- want paid support, there are options for that. Respect developers time and
- expertise and they might be happy to share with you.
+ want paid support, there are :ref:`consulting-resources` options for that. Respect
+ developers time and expertise and they might be happy to share with you.
Diagnostic tools
================
@@ -53,9 +54,6 @@ Diagnostic tools
Best to be prepared with good diagnostic information to aide with
support.
-.. todo::
- Need a reference to how to run `beagle-version`.
-
.. note::
#TODO#: Need a reference to how to run `beagle-version`.
@@ -75,6 +73,8 @@ of the entire community.
- `Mailing List <https://forum.beagleboard.org>`__
- `Live Chat <https://beagleboard.org/chat>`__
+.. _consulting-resources:
+
Consulting and other resources
==============================
@@ -109,7 +109,7 @@ Understanding Your Beagle
Working with Cape Add-on Boards
*******************************
-- `Cape Documentation </boards/capes/>`__
-- `BeagleBone Cape Interface Specification </boards/capes/cape-interface-spec.html>`__
+- :ref:`capes`
+- :ref:`beaglebone-cape-interface-spec`
diff --git a/projects/index.rst b/projects/index.rst
index 78b5def7b3e4b558d70d830a8aeedfbb790fd212..4e5831752be7493d393f92f4f930548d57c3b057 100644
--- a/projects/index.rst
+++ b/projects/index.rst
@@ -1,3 +1,5 @@
+.. _projects-home:
+
Projects
********
@@ -7,4 +9,4 @@ This is a collection of reasonably well-supported projects useful to Beagle deve
:maxdepth: 1
/projects/simppru/index.rst
- /boards/beagleconnect/technology/index.rst
+ /boards/beagleconnect/index.rst