diff --git a/_static/css/custom.css b/_static/css/custom.css
index 48998e5c8745a4470bb8c100febca28dd13c810b..22957e5ab52b61f3c3a16cefd06d2d62ef144fde 100644
--- a/_static/css/custom.css
+++ b/_static/css/custom.css
@@ -76,4 +76,8 @@ span.strike {
.bd-main .bd-content .bd-article-container {
max-width: 100%; /* default is 60em */
+}
+
+figure a.headerlink {
+ position: static;
}
\ No newline at end of file
diff --git a/_templates/404.html b/_templates/404.html
new file mode 100644
index 0000000000000000000000000000000000000000..9a9f9eac8bdc7b8e69cc0db3d423022e1c073688
--- /dev/null
+++ b/_templates/404.html
@@ -0,0 +1,15 @@
+{% extends "pydata_sphinx_theme/layout.html" %}
+
+{% set title = "Page Not Found (404)" %}
+
+{% block title %}{{ title }}{% endblock %}
+
+{% block docs_body %}
+<div class="document">
+ <h1>{{ title }}</h1>
+ <p>Oops! The page you're looking for does not exist.</p>
+ <p>You can return to the <a href="{{ pathto(master_doc) }}">home page</a>.</p>
+ <p>If you believe this is a broken link, please <a data-bs-toggle="modal" data-bs-target="#feedbackModal" href="#" onclick="getFeedbackButtonhref(this)">let us know</a>.</p>
+</div>
+{{ super() }}
+{% endblock %}
diff --git a/_templates/feedback.html b/_templates/feedback.html
index 9b7e61b031baa117b78fa2b8bbce9a61a31bf1b3..a0265c87c7e49b6ec2516f873dd9bc26a6a63f79 100644
--- a/_templates/feedback.html
+++ b/_templates/feedback.html
@@ -1,41 +1,52 @@
<a role="button" data-bs-toggle="modal" data-bs-target="#feedbackModal" href="#" onclick="getFeedbackButtonhref(this)">
- <i class="fa-solid fa-arrows-rotate"></i> Provide Feedback
+ <i class="fa-regular fa-message"></i> Provide Feedback
</a>
<div class="modal fade" id="feedbackModal" aria-labelledby="feedbackModalLabel" aria-hidden="true">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
- <div class="modal-header">
- <h5 class="modal-title m-0 text-dark" id="feedbackModalLabel">Feedback</h5>
- <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
- </div>
- <div class="modal-body text-center">
- <div class="btn-group mb-3" role="group" aria-label="Basic radio toggle button group" id="feedbackType" onChange="feedbackHandler()">
- <input type="radio" class="btn-check" name="feedbackType" id="btnradio1" autocomplete="off" value="Issue">
- <label class="btn btn-outline-dark shadow-none" for="btnradio1"><i class="fa-solid fa-triangle-exclamation"></i> Issue</label>
-
- <input type="radio" class="btn-check" name="feedbackType" id="btnradio2" autocomplete="off" value="Feedback" checked>
- <label class="btn btn-outline-dark shadow-none" for="btnradio2"><i class="fa-solid fa-arrows-rotate"></i> Feedback</label>
-
- <input type="radio" class="btn-check" name="feedbackType" id="btnradio3" autocomplete="off" value="Idea">
- <label class="btn btn-outline-dark shadow-none" for="btnradio3"><i class="fa-solid fa-lightbulb"></i> Idea</label>
+ <div class="modal-header">
+ <h5 class="modal-title m-0 text-dark" id="feedbackModalLabel">Feedback</h5>
+ <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
- <div class="mb-3">
- <input type="title" class="form-control bg-light text-dark" id="feedbackModalTitle" placeholder="Title" onChange="feedbackHandler()">
+ <div class="modal-body text-center">
+ <div class="btn-group mb-3" role="group" aria-label="Basic radio toggle button group" id="feedbackType"
+ onChange="feedbackHandler()">
+ <input type="radio" class="btn-check" name="feedbackType" id="btnradio1" autocomplete="off"
+ value="Issue">
+ <label class="btn btn-outline-dark shadow-none" for="btnradio1"><i
+ class="fa-solid fa-triangle-exclamation"></i> Issue</label>
+
+ <input type="radio" class="btn-check" name="feedbackType" id="btnradio2" autocomplete="off"
+ value="Feedback" checked>
+ <label class="btn btn-outline-dark shadow-none" for="btnradio2"><i
+ class="fa-regular fa-message"></i> Feedback</label>
+
+ <input type="radio" class="btn-check" name="feedbackType" id="btnradio3" autocomplete="off"
+ value="Idea">
+ <label class="btn btn-outline-dark shadow-none" for="btnradio3"><i
+ class="fa-solid fa-lightbulb"></i> Idea</label>
+ </div>
+ <div class="mb-3">
+ <input type="title" class="form-control bg-light text-dark" id="feedbackModalTitle"
+ placeholder="Title" onChange="feedbackHandler()">
+ </div>
+ <div class="mb-3">
+ <textarea class="form-control bg-light text-dark" id="feedbackModalDescription" minlength="13"
+ rows="3" placeholder="Description" onChange="feedbackHandler()"></textarea>
+ </div>
</div>
- <div class="mb-3">
- <textarea class="form-control bg-light text-dark" id="feedbackModalDescription" minlength="13" rows="3" placeholder="Description" onChange="feedbackHandler()"></textarea>
+ <div class="modal-footer">
+ <button type="button" class="btn btn-secondary" data-bs-dismiss="modal" onclick="feedbackClear()">Clear
+ & Close</button>
+ <span id="generateLinkButtonTooltip" data-bs-placement="bottom" data-bs-toggle="tooltip">
+ <a href="javascript:void(0);" id="feedbacklink" type="button"
+ class="btn btn-primary disabled text-light">
+ <i class="fa-solid fa-up-right-from-square"></i> Generate OpenBeagle Issue
+ </a>
+ </span>
</div>
</div>
- <div class="modal-footer">
- <button type="button" class="btn btn-secondary" data-bs-dismiss="modal" onclick="feedbackClear()">Clear & Close</button>
- <span id="generateLinkButtonTooltip" data-bs-placement="bottom" data-bs-toggle="tooltip">
- <a href="javascript:void(0);" id="feedbacklink" type="button" class="btn btn-primary disabled text-light">
- <i class="fa-solid fa-up-right-from-square"></i> Generate OpenBeagle Issue
- </a>
- </span>
- </div>
- </div>
</div>
</div>
@@ -52,20 +63,20 @@
var title = document.getElementById("feedbackModalTitle")
var description = document.getElementById("feedbackModalDescription")
var generatedFromLink = ""
-
- title.placeholder = "Title (minimum "+titleMinLength+" characters)"
- description.placeholder = "Description (minimum "+descriptionMinLength+" characters)"
+
+ title.placeholder = "Title (minimum " + titleMinLength + " characters)"
+ description.placeholder = "Description (minimum " + descriptionMinLength + " characters)"
function feedbackHandler() {
var type = document.querySelector('input[name="feedbackType"]:checked').value
-
+
if (!gitlab_project.match(/^[a-zA-Z]+:\/\//)) {
gitlab_project = 'https://' + gitlab_project;
}
- if(title.value.length >= titleMinLength && description.value.length >= descriptionMinLength) {
- link.target="_blank"
+ if (title.value.length >= titleMinLength && description.value.length >= descriptionMinLength) {
+ link.target = "_blank"
link.classList.remove("disabled");
generateLinkButtonTooltip.title = "You must be logged in to OpenBeagle.org to generate an Issue!"
link.href = gitlab_project + "/-/issues/new?issue[title]=" + type + ": " + title.value + "&issue[description]=" + description.value + "%0A%0AGenerated from: " + generatedFromLink.replace('#', '%23')
@@ -74,7 +85,7 @@
generateLinkButtonTooltip.title = "Add proper title and description to activate the link!"
}
}
-
+
function feedbackClear() {
title.value = ""
description.value = ""
@@ -82,13 +93,63 @@
link.classList.add("disabled");
}
- var headerlinks = document.getElementsByClassName("headerlink")
- for(let i=0; i<headerlinks.length; i++){
- headerlinks[i].innerHTML = '<i class="fa-solid fa-arrows-rotate"></i>'
- headerlinks[i].title = "Provide Feedback"
- headerlinks[i].setAttribute("data-bs-toggle","modal")
- headerlinks[i].setAttribute("data-bs-target","#feedbackModal")
- headerlinks[i].setAttribute("onclick","getFeedbackButtonhref(this)")
+ document.addEventListener('DOMContentLoaded', function () {
+ const headerlinks = document.getElementsByClassName("headerlink");
+
+ for (let i = 0; i < headerlinks.length; i++) {
+ if (headerlinks[i].classList.contains('headerlink-feedback')) {
+ continue;
+ }
+
+ headerlinks[i].innerHTML = `<i class="fa-solid fa-link"></i>`;
+ headerlinks[i].addEventListener('click', function (event) {
+ event.preventDefault();
+ const link = this.href;
+ if (navigator.clipboard && navigator.clipboard.writeText) {
+ navigator.clipboard.writeText(link).then(() => {
+ console.log("Link copied to clipboard:", link);
+ this.innerHTML = `<i class="fa-regular fa-square-check"></i>`;
+ setTimeout(() => {
+ this.innerHTML = `<i class="fa-solid fa-link"></i>`;
+ }, 1000);
+ }).catch(err => {
+ console.error("Failed to copy:", err);
+ });
+ } else {
+ fallbackCopyText(link, this);
+ }
+ });
+
+ const feedbackLink = headerlinks[i].cloneNode(true);
+
+ feedbackLink.classList.add('headerlink-feedback');
+ feedbackLink.innerHTML = '<i class="fa-regular fa-message"></i>';
+ feedbackLink.title = "Provide Feedback";
+ feedbackLink.setAttribute("data-bs-toggle", "modal");
+ feedbackLink.setAttribute("data-bs-target", "#feedbackModal");
+ feedbackLink.setAttribute("onclick", "getFeedbackButtonhref(this)");
+
+ if (headerlinks[i].parentNode) {
+ headerlinks[i].parentNode.insertBefore(feedbackLink, headerlinks[i].nextSibling || null);
+ }
+ }
+ });
+
+ function fallbackCopyText(text, element) {
+ const textarea = document.createElement("textarea");
+ textarea.value = text;
+ document.body.appendChild(textarea);
+ textarea.select();
+ try {
+ document.execCommand("copy");
+ element.innerHTML = `<i class="fa-regular fa-square-check"></i>`;
+ setTimeout(() => {
+ element.innerHTML = `<i class="fa-solid fa-link"></i>`;
+ }, 1000);
+ } catch (err) {
+ console.error("Fallback: Failed to copy:", err);
+ }
+ document.body.removeChild(textarea);
}
function getFeedbackButtonhref(clickedFeedbackLink) {
diff --git a/_templates/mission.html b/_templates/mission.html
index ca8af27ddfbf80e33d2a44acb368ec8b7f3baf19..d43bad347a1f729eb9b06983748440a0fe887a5d 100644
--- a/_templates/mission.html
+++ b/_templates/mission.html
@@ -1,48 +1,55 @@
<div class="card bg-light mt-4 text-center">
- <div class="card-header bg-primary text-light fw-bold">
+ <div class="card-header bg-primary text-light fw-bold" data-bs-toggle="collapse" href="#collapseWhy" role="button" aria-expanded="false" aria-controls="collapseWhy">
Why are we doing this?
</div>
- <div class="card-body">
- <p class="card-text text-dark">
- We believe in making computers open again to democratize technology and empower individuals and organizations to explore, experiment, and create without the constraints of proprietary systems.
- </p>
+ <div id="collapseWhy" class="collapse">
+ <div class="card-body">
+ <p class="card-text text-dark">
+ We believe in making computers open again to democratize technology and empower individuals and organizations to explore, experiment, and create without the constraints of proprietary systems.
+ </p>
+ </div>
</div>
</div>
<div class="card bg-light mt-4 text-center">
- <div class="card-header bg-warning text-dark fw-bold">
+ <div class="card-header bg-warning text-dark fw-bold" data-bs-toggle="collapse" href="#collapseWhat" role="button" aria-expanded="false" aria-controls="collapseWhat">
What are we doing?
</div>
- <div class="card-body">
- <p class="card-text text-dark">
- We design versatile and affordable single-board computers to provide developers, hobbyists, and educators with a platform for prototyping, experimentation, and production of embedded systems. Our comprehensive documentation, tutorials, and vibrant online community support users in their projects and foster knowledge sharing.
- </p>
+ <div id="collapseWhat" class="collapse">
+ <div class="card-body">
+ <p class="card-text text-dark">
+ We design versatile and affordable single-board computers to provide developers, hobbyists, and educators with a platform for prototyping, experimentation, and production of embedded systems. Our comprehensive documentation, tutorials, and vibrant online community support users in their projects and foster knowledge sharing.
+ </p>
+ </div>
</div>
</div>
<div class="card bg-light mt-4 text-center">
- <div class="card-header bg-success text-light fw-bold">
+ <div class="card-header bg-success text-light fw-bold" data-bs-toggle="collapse" href="#collapseHow" role="button" aria-expanded="false" aria-controls="collapseHow">
How are we doing it?
</div>
- <div class="card-body">
- <p class="card-text text-dark">
- Through open-source hardware designs, diverse software support, and active community engagement, we enable users to customize, innovate, and collaborate effortlessly in embedded computing.
- </p>
+ <div id="collapseHow" class="collapse">
+ <div class="card-body">
+ <p class="card-text text-dark">
+ Through open-source hardware designs, diverse software support, and active community engagement, we enable users to customize, innovate, and collaborate effortlessly in embedded computing.
+ </p>
+ </div>
</div>
</div>
<div class="card bg-light mt-4 text-center">
- <div class="card-header bg-dark text-light fw-bold">
+ <div class="card-header bg-dark text-light fw-bold" data-bs-toggle="collapse" href="#collapseSupport" role="button" aria-expanded="false" aria-controls="collapseSupport">
Support us <i class="fa-solid fa-hand-holding-dollar"></i>
</div>
- <div class="card-body">
- <p class="card-text text-dark">
- The BeagleBoard.org Foundation is a Michigan, USA-based 501(c)(3) non-profit corporation existing to provide education in and collaboration around the design and use of open-source software and hardware in embedded computing.
- </p>
- </div>
- <div class="card-footer d-grid gap-2">
- <!-- <a href="https://paypal.me/beagleboard" class="btn btn-primary text-light"><i class="fa-brands fa-paypal"></i> Support via Paypal</a> -->
- <a href="https://patreon.com/beagleboard" class="btn btn-danger text-light"><i class="fa-brands fa-patreon"></i> Become a Patreon</a>
- <a href="https://github.com/sponsors/beagleboard" class="btn btn-dark text-light"><i class="fa-brands fa-github"></i> Sponsor on GitHub</a>
+ <div id="collapseSupport" class="collapse">
+ <div class="card-body">
+ <p class="card-text text-dark">
+ The BeagleBoard.org Foundation is a Michigan, USA-based 501(c)(3) non-profit corporation existing to provide education in and collaboration around the design and use of open-source software and hardware in embedded computing.
+ </p>
+ </div>
+ <div class="card-footer d-grid gap-2">
+ <a href="https://patreon.com/beagleboard" class="btn btn-danger text-light"><i class="fa-brands fa-patreon"></i> Become a Patreon</a>
+ <a href="https://github.com/sponsors/beagleboard" class="btn btn-dark text-light"><i class="fa-brands fa-github"></i> Sponsor on GitHub</a>
+ </div>
</div>
</div>
diff --git a/_templates/oshw.html b/_templates/oshw.html
index a601739b3d5ec62083f0b46d7938e009a7306c01..001897f5292ac81ef64c34b4032a998689cfa781 100644
--- a/_templates/oshw.html
+++ b/_templates/oshw.html
@@ -1,20 +1,20 @@
{% for board, path, oshw_id in oshw_details %}
- {% if path+'/' in pagename %}
- <div class="card bg-light mt-4 text-center">
- <div class="card-header">
+{% if path+'/' in pagename %}
+<div class="card bg-light mt-4 text-center">
+ <div class="card-header">
{{board}}
- </div>
- <div class="card-body">
+ </div>
+ <div class="card-body">
<p class="card-text text-dark">
<a href="https://certification.oshwa.org/{{ oshw_id|lower }}.html" target="_blank">
- {% if docs_url %}
- <img src="{{docs_url}}/_static/images/oshw/{{board}}_{{oshw_id}}.svg" alt="{{board}} OSHW mark"/>
- {% else %}
- <img src="../../../../_static/images/oshw/{{board}}_{{oshw_id}}.svg" alt="{{board}} OSHW mark"/>
- {% endif %}
+ {% if docs_url %}
+ <img src="{{docs_url}}/_static/images/oshw/{{board}}_{{oshw_id}}.svg" alt="{{board}} OSHW mark" />
+ {% else %}
+ <img src="../../../../_static/images/oshw/{{board}}_{{oshw_id}}.svg" alt="{{board}} OSHW mark" />
+ {% endif %}
</a>
</p>
- </div>
</div>
- {% endif %}
+</div>
+{% endif %}
{% endfor%}
\ No newline at end of file
diff --git a/_templates/versions.html b/_templates/versions.html
deleted file mode 100644
index aeb38d9b0647fb7fd406436a5614cabe677b9030..0000000000000000000000000000000000000000
--- a/_templates/versions.html
+++ /dev/null
@@ -1,26 +0,0 @@
-{# Add rst-badge after rst-versions for small badge style. #}
- <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: {{ pages_slug }}
- <span class="fa fa-caret-down"></span>
- </span>
- <div class="rst-other-versions">
- <dl>
- <dt>{{ _('Document Release Versions') }}</dt>
- {% for version_slug in versions %}
- <dd><a href="{{pages_url}}/{{version_slug}}">{{ version_slug }}</a></dd>
- {% endfor %}
- </dl>
- <dl>
- <dt>{{ _('Downloads') }}</dt>
- <dd><a href="{{docs_url}}/beagleboard-docs.pdf">PDF</a></dd>
- </dl>
- <dl>
- <dt>{{ _('BeagleBoard.org Links') }}</dt>
- <dd>
- <a href="https://git.beagleboard.org/docs/docs.beagleboard.io/">Docs Source</a>
- </dd>
- </dl>
- </div>
- </div>
diff --git a/boards/beagley/ai/02-quick-start.rst b/boards/beagley/ai/02-quick-start.rst
index ae7e00d77c51f08ef07b12f69a8c7d9586efdd33..2672c2442d8cd75022e1f35011fe1f905fa491f8 100644
--- a/boards/beagley/ai/02-quick-start.rst
+++ b/boards/beagley/ai/02-quick-start.rst
@@ -321,7 +321,7 @@ Headless connection
If you want to run your BeagleY-AI in headless mode, you need `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_
or similar serial (USB to UART) adapter. Connect your UART debug probe to BeagleY-AI as shown in the image below. After making the connection you can use command
-line utility like ``tio`` on Linux of Putty on any operating system. Check :ref:`beagley-ai-uart-connection` for more information.
+line utility like ``tio`` on Linux or Putty on any operating system. Check :ref:`beagley-ai-uart-connection` for more information.
.. figure:: images/uart/rpi-debug-probe-connection.*
:align: center
diff --git a/books/beaglebone-cookbook/01basics/basics.rst b/books/beaglebone-cookbook/01basics/basics.rst
index 5f8c39b84fef154cf40963d9b735d5f6b786b771..b6fd0beaae38a6a73fec50237469812f19e04a8b 100644
--- a/books/beaglebone-cookbook/01basics/basics.rst
+++ b/books/beaglebone-cookbook/01basics/basics.rst
@@ -20,12 +20,7 @@ There are many different BeagleBoards. How do you pick which one to use?
Solution
---------
-.. todo
-
-Current list of boards: https://git.beagleboard.org/explore/projects/topics/boards
-
-Discussion
------------
+Check out the current list of boards: :ref:`boards`
.. _basics_out_of_the_box:
@@ -40,6 +35,11 @@ You just got your Bone, and you want to know what to do with it.
Solution
---------
+Many of the Beagles (:ref:`beagley-all-home`, :ref:`beagleplay-home`,
+:ref:`bbai64-home`, :ref:`bbai-home`, :ref:`beaglev-ahead-home` and
+:ref:`beaglev-fire-home`)
+have their own detailed **Quick start** guide. Here we present
+general instructions that work for all Beagles.
Fortunately, you have all you need to get running: your Bone and a USB cable.
Plug the USB cable into your host computer (Mac, Windows, or Linux) and plug the
mini-USB connector side into the USB connector near the Ethernet connector on
@@ -86,7 +86,7 @@ Wait a minute and try the URL again.
Visual Studio Code
Here, you'll find *Visual Studio Code*, a web-based integrated development environment (IDE)
-that lets you edit and run code on your Bone! See :ref: `basics_vsc` for more details.
+that lets you edit and run code on your Bone! See :ref:`basics_vsc` for more details.
.. WARNING::
Make sure you turn off your Bone properly.
@@ -132,19 +132,23 @@ following the instructions in :ref:`basics_out_of_the_box` to log into the Bone.
.. code-block:: bash
bone$ cat /etc/dogtag
- BeagleBoard.org Debian Bullseye IoT Image 2023-06-03
+ BeagleBoard.org Debian Bookworm Minimal Image 2024-09-11
-I'm running the 2023-06-03 version.
+I'm running the **2024-09-11** version.
-Running the Python and JavaScript Examples
-===========================================
+Running the Python Examples
+===========================
Problem
--------
-You'd like to learn Python or JavaScript interact with the Bone to
+You'd like to learn Python to interact with the Bone to
perform physical computing tasks without first learning Linux.
+.. note::
+
+ There are many JavaScript examples too, but they may not be as up to date as the Python examples.
+
Solution
---------
@@ -154,6 +158,10 @@ http://192.168.7.2:3000 using Google Chrome or Firefox (as shown in
column, click on *examples*, then *BeagleBone* and then *Black*.
Several sample scripts will appear. Go and explore them.
+.. todo
+ examples are no longer on the board.
+
+
.. tip::
Explore the various demonstrations of Python and JavaScript. These are what come with the Bone.
@@ -307,44 +315,56 @@ You want to find out the latest version of Debian that is available for your Bon
Solution
************
-On your host computer, open a browser and go to https://forum.beagleboard.org/tag/latest-images
-This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
+.. tab-set::
-.. todo
- Update for 2023-06-03
+ .. tab-item:: bb-imager
-.. _basics_deb1:
+ The easiest way to see what the current images are and update your SD card
+ is to use **bb-imager**. :ref:`beagley-ai-bb-imager` gives details on how to us it.
-.. figure:: figures/deb1.png
- :align: center
- :alt: Latest Debian images
+ .. tab-item:: forum
- Latest Debian images
+ Another way to see the available images is to visit the beagleboard forum.
-At the time of writing, we are using the *Bullseye* image.
-Click on its link. Scrolling up you'll find :ref:`basics_deb2`.
-There are three types of snapshots, Minimal, IoT and Xfce Desktop.
-IoT is the one we are running.
+ On your host computer, open a browser and go to https://forum.beagleboard.org/tag/latest-images
+ This shows you a list of dates of the most recent Debian images (:ref:`basics_deb1`).
-.. _basics_deb2:
+ .. todo::
-.. figure:: figures/deb2.png
- :align: center
- :alt: Latest Debian images
+ Update for 2023-06-03
+
+ .. _basics_deb1:
+
+ .. figure:: figures/deb1.png
+ :align: center
+ :alt: Latest Debian images
+
+ Latest Debian images
+
+ At the time of writing, we are using the *Bullseye* image.
+ Click on its link. Scrolling up you'll find :ref:`basics_deb2`.
+ There are three types of snapshots, Minimal, IoT and Xfce Desktop.
+ IoT is the one we are running.
+
+ .. _basics_deb2:
+
+ .. figure:: figures/deb2.png
+ :align: center
+ :alt: Latest Debian images
- Latest Debian images
+ Latest Debian images
-These are the images you want to use if you are flashing a Rev C BeagleBone Black
-onboard flash, or flashing a 4 GB or bigger miscroSD card. The image beginning
-with *am335x-debian-11.3-iot-* is used for the non-AI boards. The one beginning
-with *am57xx-debian-* is for programming the Beagle AI's.
+ These are the images you want to use if you are flashing a Rev C BeagleBone Black
+ onboard flash, or flashing a 4 GB or bigger miscroSD card. The image beginning
+ with *am335x-debian-11.3-iot-* is used for the non-AI boards. The one beginning
+ with *am57xx-debian-* is for programming the Beagle AI's.
-.. note::
- The onboard flash is often called the *eMMC* memory. We just call it *onboard flash*, but you'll
- often see *eMMC* appearing in filenames of images used to update the onboard flash.
+ .. note::
+ The onboard flash is often called the *eMMC* memory. We just call it *onboard flash*, but you'll
+ often see *eMMC* appearing in filenames of images used to update the onboard flash.
-Click the image you want to use and it will download.
-The images are some 500M, so it might take a while.
+ Click the image you want to use and it will download.
+ The images are some 500M, so it might take a while.
.. _basics_install_os:
@@ -423,7 +443,8 @@ Problem
--------
You've modified the state of your Bone
-in a way that you'd like to preserve or share.
+in a way that you'd like to preserve or share. Note, this doesn't apply to boards that
+don't have onboard flash (PocketBeagle and BeagleY-AI).
Solution
---------
@@ -462,6 +483,8 @@ Problem
--------
You want to copy the microSD card to the onboard flash.
+Note, this doesn't apply to boards that
+don't have onboard flash (PocketBeagle and BeagleY-AI).
Solution
--------
diff --git a/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png b/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png
new file mode 100644
index 0000000000000000000000000000000000000000..45a560d3c9d67afa2974845a2fcc589f39bc9a50
Binary files /dev/null and b/books/beaglebone-cookbook/02sensors/figures/beagleY-ai-front.png differ
diff --git a/books/beaglebone-cookbook/02sensors/figures/pinout.png b/books/beaglebone-cookbook/02sensors/figures/pinout.png
new file mode 100644
index 0000000000000000000000000000000000000000..162a67743f499849b69519143d9d0621951d825d
Binary files /dev/null and b/books/beaglebone-cookbook/02sensors/figures/pinout.png differ
diff --git a/books/beaglebone-cookbook/02sensors/sensors.rst b/books/beaglebone-cookbook/02sensors/sensors.rst
index 71087c50cb762fb035453afe7925d5e77ca17feb..c0d195b6d0e668a0dd3039fa41a3d70c6081ec5d 100644
--- a/books/beaglebone-cookbook/02sensors/sensors.rst
+++ b/books/beaglebone-cookbook/02sensors/sensors.rst
@@ -7,6 +7,12 @@ Sensors
.. |ohm| replace:: Ω
.. |deg| replace:: °
+.. note::
+
+ Although the examples given here are originally for the BeagleBone Black, many will also
+ work on the other Beagles too. See the `tabs` for details on running the examples
+ on other boards.
+
In this chapter, you will learn how to sense the physical world with BeagleBone Black.
Various types of electronic sensors, such as cameras and microphones, can be connected
to the Bone using one or more interfaces provided by the standard USB 2.0 host port,
@@ -17,25 +23,42 @@ as shown in :ref:`sensors_host_port`.
All the examples in the book assume you have cloned the Cookbook
repository on git.beagleboard.org. Go here :ref:`basics_repo` for instructions.
-.. _sensors_host_port:
-.. figure:: figures/black_hardware_details.*
- :align: center
- :alt: USB Host Port
+.. tab-set::
- The USB 2.0 host port
+ .. tab-item:: BeagleBone Black
-The two 46-pin cape headers (called *P8* and *P9*) along the long
-edges of the board (:ref:`sensors_P8P9_fig`) provide connections for
-cape add-on boards, digital and analog sensors, and more.
+ .. _sensors_host_port:
-.. _sensors_P8P9_fig:
+ .. figure:: figures/black_hardware_details.*
+ :align: center
+ :alt: USB Host Port
-.. figure:: figures/P8P9_bb.png
- :align: center
- :alt: Cape Headers P8 and P9
+ The USB 2.0 host port
+
+ The two 46-pin cape headers (called *P8* and *P9*) along the long
+ edges of the board (:ref:`sensors_P8P9_fig`) provide connections for
+ cape add-on boards, digital and analog sensors, and more.
+
+ .. _sensors_P8P9_fig:
+
+ .. figure:: figures/P8P9_bb.png
+ :align: center
+ :alt: Cape Headers P8 and P9
+
+ Cape Headers P8 and P9
+
+ .. tab-item:: BeagleY-AI
- Cape Headers P8 and P9
+ .. figure:: figures/beagleY-ai-front.png
+ :align: center
+ :alt: BeagleY-AI Front View
+
+ BeagleY-AI Front View
+
+ The 40-pin hat header along the long
+ edge of the board provides connections for
+ hat add-on boards, digital and analog sensors, and more.
The simplest kind of sensor provides a single digital status, such as off or on,
and can be handled by an *input mode* of one of the Bone's 65 general-purpose input/output
@@ -59,15 +82,43 @@ You want to acquire and attach a sensor and need to understand your basic option
Solution
--------
-:ref:`sensors_cape_headers` shows many of the possibilities for connecting a sensor.
+.. tab-set::
-.. _sensors_cape_headers:
+ .. tab-item:: BeagleBones
+
+ :ref:`sensors_cape_headers` shows many of the possibilities for connecting a sensor.
-.. figure:: figures/cape-headers.*
- :align: center
- :alt: Sensor Connection Modes
-
- Some of the many sensor connection options on the Bone
+ .. _sensors_cape_headers:
+
+ .. figure:: figures/cape-headers.*
+ :align: center
+ :alt: Sensor Connection Modes
+
+ Some of the many sensor connection options on the Bone.
+
+ .. tab-item:: BeagleY-AI
+
+ :ref:`sensors_hat_headers` shows many of the possibilities for connecting a sensor.
+
+ You will see pins referenced in several ways. While this is confusing at first, in reality,
+ we can pick our favorite way and stick to it.
+
+ The two main ways of referring to GPIOs is **by their number**, so GPIO2, GPIO3, GPIO4 etc.
+ as seen in the diagram below. This corresponds
+ to the SoC naming convention. For broad compatibility, BeagleY-AI re-uses the Broadcom GPIO numbering scheme used by RaspberryPi.
+
+ The second (and arguably easier) way we will use for this tutorial is to use the **actual pin header number** (shown in dark grey). So, for the rest of the tutorial, if we refer to **hat-08-gpio** we mean the **8th pin of the GPIO header**. Which, if you referenced
+ the image below, can see refers to **GPIO14 (UART TXD)**
+
+ .. _sensors_hat_headers:
+
+ .. figure:: figures/pinout.png
+ :align: center
+ :alt: BeagleY-AI pinout
+
+ BeagleY-AI pinout
+
+ Go to https://pinout.beagleboard.io/ to see an interactive version of the figure.
Choosing the simplest solution available enables you to move on quickly to
addressing other system aspects. By exploring each connection type, you can
@@ -127,13 +178,14 @@ By default, it takes you to your home directory. Notice that the prompt has chan
.. code-block:: bash
debian@beaglebone:beaglebone-cookbook/code/02sensors$ ./pushbutton.py
- data= 0
- data= 0
- data= 1
- data= 1
+ data = 0
+ data = 0
+ data = 1
+ data = 1
^C
This process will work for any script in this book.
+(See the following sections for instructions on how to wire the pushbutton.)
.. _sensors_pushbutton:
@@ -169,6 +221,11 @@ or both on the Bone, as shown in :ref:`js_pushbutton_fig`.
The code below reads GPIO port *P9_42*, which is attached to the pushbutton.
+.. note::
+
+ If you are using a BeagleY-AI, wire the button to **GPIO23** which is **hat-16**.
+ This also appears at **gpiochip0** and line **7**.
+
.. tab-set::
.. tab-item:: Python
@@ -230,7 +287,9 @@ You have a sensor attached to the P8 or P9 header and need to know which gpio pi
Solution
---------
-The *gpioinfo* command displays information about all the P8 and P9 header pins. To see the info for just one pin, use *grep*.
+The *gpioinfo* command displays information about all the P8 and P9 header pins.
+(Or the HAT header pins if you are on the BeagleY-AI.)
+To see the info for just one pin, use *grep*.
.. code-block:: bash
@@ -241,7 +300,17 @@ The *gpioinfo* command displays information about all the P8 and P9 header pins.
gpiochip2 - 32 lines:
gpiochip3 - 32 lines:
-This shows P9_42 is on chip 0 and pin 7. To find the gpio number multiply
+Or, if on the BeagleY-AI.
+
+.. code-block:: bash
+
+ bone$ gpioinfo | grep -e chip -e GPIO23
+ gpiochip0 - 24 lines:
+ line 7: "GPIO23" unused input active-high
+ gpiochip1 - 87 lines:
+ gpiochip2 - 73 lines:
+
+This shows P9_42 (GPIO32) is on chip 0 and pin 7. To find the gpio number multiply
the chip number by 32 and add it to the pin number. This gives 0*32+7=7.
For P9_26 you get:
@@ -270,6 +339,10 @@ and you want to read their value with the Bone.
Solution
--------
+.. note::
+
+ The BeagleY-AI doesn't have ADC's, so you can skip this section.
+
Use the Bone's analog-to-digital converters (ADCs) and a resistor
divider circuit to detect the resistance in the sensor.
@@ -366,6 +439,10 @@ which outputs a voltage in proportion to the distance.
Solution
--------
+.. note::
+
+ The BeagleY-AI doesn't have ADC's, so you can skip this section.
+
To make this recipe, you will need:
* Breadboard and jumper wires.
@@ -474,6 +551,10 @@ Accurately Reading the Position of a Motor or Dial
Problem
--------
+.. todo::
+
+ Update for BeagleY-AI
+
You have a motor or dial and want to detect rotation using a rotary encoder.
Solution
@@ -684,28 +765,54 @@ To make this recipe, you will need:
* Two 4.7 |kohm| resistors.
* TMP101 temperature sensor.
-Wire the TMP101, as shown in :ref:`sensors_i2cTemp_fig`.
+.. tab-set::
-.. _sensors_i2cTemp_fig:
+ .. tab-item:: BeagleBone
-.. figure:: figures/i2cTemp_bb.png
- :align: center
- :alt: |I2C| Temp
+ Wire the TMP101, as shown in :ref:`sensors_i2cTemp_fig`.
- Wiring an |I2C| TMP101 temperature sensor
+ .. _sensors_i2cTemp_fig:
-There are two |I2C| buses brought out to the headers.
-:ref:`sensors_cape_headers_i2c`
-shows that you have wired your device to |I2C| bus *2*.
+ .. figure:: figures/i2cTemp_bb.png
+ :align: center
+ :alt: |I2C| Temp
-.. _sensors_cape_headers_i2c:
+ Wiring an |I2C| TMP101 temperature sensor
-.. figure:: figures/cape-headers-i2c.png
- :align: center
- :alt: Table of |I2C| outputs
+ There are two |I2C| buses brought out to the headers.
+ :ref:`sensors_cape_headers_i2c`
+ shows that you have wired your device to |I2C| bus *2*.
+
+ .. _sensors_cape_headers_i2c:
+
+ .. figure:: figures/cape-headers-i2c.png
+ :align: center
+ :alt: Table of |I2C| outputs
+
+ Table of |I2C| outputs
+
+ .. tab-item:: BeagleY-AI
- Table of |I2C| outputs
+ Running the following on the BeagleY-AI shows it has five i2c buses.
+ .. code-block:: shell-session
+
+ bone$ ls /sys/bus/i2c/devices/
+ 2-0030 2-0050 2-0068 4-004c i2c-1 i2c-2 i2c-3 i2c-4 i2c-5
+
+ But running https://pinout.beagleboard.io/ show only buses 1 and 4 are exposed on the HAT header.
+ Here we'll use bus 2 whose clock appears on `hat-03` and data on `hat-05`.
+
+ Wire your **tmp101** as shown in the table.
+
+ ======== === ======
+ Function hat tmp101
+ ======== === ======
+ Ground 09 2
+ 3.3V 01 5
+ data 03 6
+ clock 05 1
+ ======== === ======
Once the |I2C| device is wired up, you can use a couple handy |I2C|
tools to test the device. Because these are Linux command-line tools,
@@ -716,13 +823,18 @@ the value. It returns the temperature in hexadecimal and degrees C.
In this example, 0x18 = 24{deg}C, which is 75.2{deg}F. (Hmmm, the office is a bit warm today.)
Try warming up the TMP101 with your finger and running *i2cget* again.
-.. todo:: fix deg
+.. todo::
+
+ fix deg
.. _js_i2cTools:
|I2C| tools
============
+One way to see what devices are on a given |I2C| bus is to use `i2cdetect`.
+Here is bus 2 on the BeagleBone.
+
.. code-block:: bash
bone$ i2cdetect -y -r 2
@@ -739,6 +851,23 @@ Try warming up the TMP101 with your finger and running *i2cget* again.
bone$ i2cget -y 2 0x49
0x18
+Here is bus 1 on the BeagleY-AI.
+
+.. code-block:: bash
+
+ bone$ i2cdetect -y -r 1
+ 0 1 2 3 4 5 6 7 8 9 a b c d e f
+ 00: -- -- -- -- -- -- -- -- -- -- -- -- --
+ 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 40: -- -- -- -- -- -- -- -- -- 49 -- -- -- -- -- --
+ 50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 70: -- -- -- -- -- -- -- --
+
+ bone$ i2cget -y 1 0x49
+ 0x18
Reading the temperature via the kernel driver
==============================================
@@ -747,6 +876,10 @@ The cleanest way to read the temperature from at TMP101 sensor is to use the ker
Assuming the TMP101 is on bus 2 (the last digit is the bus number)
+.. note::
+
+ Switch bus 2 to bus 1 if you are using the BeagleY-AI.
+
.. _js_i2cKernel:
|I2C| TMP101 via Kernel
@@ -773,8 +906,13 @@ Assuming the TMP101 is at address 0x49
.. code-block:: bash
- bone$ echo tmp101 0x49 > new_device
+ bone$ echo tmp101 0x49 > new_device
+
+.. note::
+ If this returns `new_device: Permission denied`, you will need to run the following first.
+
+ bone$ sudo chown debian:gpio *
This tells the kernel you have a TMP101 sensor at address 0x49. Check the log to be sure.
@@ -854,8 +992,7 @@ using the kernel driver. First you need to install the i2c module.
.. code-block:: bash
- bone$ pip install smbus
-
+ bone$ sudo apt install python3-smbus
.. _js_i2ctmp101_code:
@@ -881,12 +1018,7 @@ You want to measure a temperature using a Dallas Semiconductor DS18B20 temperatu
Solution
---------
-.. I need to double-check how we provide attribution for recipes, but we'll need to have
-.. something more than "From" followed by a link. For now, we should at least do
-.. something like what I've changed it to. --BS
-
-.. --may A bigger question is, when do we need attribution?
-.. I pull bits and pieces from everywhere and try to keep good records of sources.
+.. todo:: Update for BeagleY-AI
The DS18B20 is an interesting temperature sensor that uses Dallas
Semiconductor's 1-wire interface. The data communication requires only
@@ -1124,7 +1256,13 @@ such as the one shown in :ref:`usb_audio_dongle`.
A USB audio dongle
Drivers for the `Advanced Linux Sound Architecture <http://bit.ly/1MrAJUR>`_ (ALSA)
-are already installed on the Bone. You can list the recording and playing devices on
+may already installed on the Bone. If not, run the following:
+
+.. code-block:: bash
+
+ bone$ sudo apt install alsa-utils
+
+You can list the recording and playing devices on
your Bone by using *aplay* and *arecord*, as shown in :ref:`sensors_alsa`. BeagleBone Black
has audio-out on the HDMI interface. It's listed as *card 0* in
:ref:`sensors_alsa`. *card 1* is my USB audio adapter's audio out.
diff --git a/books/beaglebone-cookbook/04motors/figures/pwm.png b/books/beaglebone-cookbook/04motors/figures/pwm.png
new file mode 100644
index 0000000000000000000000000000000000000000..7d6fc18af74584d453e4f80beafda365e732ddcb
Binary files /dev/null and b/books/beaglebone-cookbook/04motors/figures/pwm.png differ
diff --git a/books/beaglebone-cookbook/04motors/motors.rst b/books/beaglebone-cookbook/04motors/motors.rst
index e9f85273699a4743d6056a9da85d657785416634..09d2b58e92249cd82957be7633754defeab6620e 100644
--- a/books/beaglebone-cookbook/04motors/motors.rst
+++ b/books/beaglebone-cookbook/04motors/motors.rst
@@ -83,13 +83,7 @@ Wire up your servo, as shown in :ref:`motors_servoMotor`.
Driving a servo motor with the 3.3 V power supply
The code for controlling the servo motor is in ``servoMotor.py``, shown
-in :ref:`py_servoMotor_code`. You need to configure the pin for PWM.
-
-.. code-block:: bash
-
- bone$ cd ~/beaglebone-cookbook-code/04motors
- bone$ config-pin P9_16 pwm
- bone$ ./servoMotor.py
+in :ref:`py_servoMotor_code`.
.. tab-set::
@@ -115,6 +109,85 @@ in :ref:`py_servoMotor_code`. You need to configure the pin for PWM.
:download:`servoMotor.js <../code/04motors/servoMotor.js>`
+You need to configure the pin for PWM.
+
+.. tab-set::
+
+ .. tab-item:: BeagleBone
+
+ .. code-block:: bash
+
+ bone$ cd ~/beaglebone-cookbook-code/04motors
+ bone$ config-pin P9_16 pwm
+ bone$ ./servoMotor.py
+
+ .. tab-item:: BeagleY-AI
+
+ Configuring the PWM on the BeagleY-AI takes a little more effort than on the Bone.
+ First select which PWM you want to use. https://pinout.beagleboard.io/pinout/pwm
+ shows you have many to choose from.
+
+ .. figure:: figures/pwm.png
+ :align: center
+ :alt: BeagleY-AI PWMs
+
+ BeagleY-AI PWMs
+
+ Let's use **PWM0** on **GPIO12**. Note this is Hat pin 32 as shown in the figure (**hat-32**).
+ The instructions at :ref:`beagley-ai-using-pwm` give details on how to configure the PWM pin. A shorter version is given here.
+
+ To enable any of the PWM Pins, we have to modify the file: ``/boot/firmware/extlinux/extlinux.conf``. We can check the available list of Device Tree Overlays using the command:
+
+ .. code:: console
+
+ debian@BeagleBone:~$ ls /boot/firmware/overlays/ | grep "beagley-ai-pwm"
+ k3-am67a-beagley-ai-pwm-ecap0-gpio12.dtbo
+ k3-am67a-beagley-ai-pwm-ecap1-gpio16.dtbo
+ k3-am67a-beagley-ai-pwm-ecap1-gpio21.dtbo
+ ...
+
+ Add the line shown below to ``/boot/firmware/extlinux/extlinux.conf`` to load the gpio12 pwm device tree overlay:
+
+ .. code:: bash
+
+ fdtoverlays /overlays/k3-am67a-beagley-ai-pwm-epwm0-ecap0-gpio12.dtbo
+
+ Your ``/boot/firmware/extlinux/extlinux.conf`` file should look something like:
+
+ .. code:: bash
+
+ label microSD (default)
+ kernel /Image
+ append console=ttyS2,115200n8 root=/dev/mmcblk1p3 ro rootfstype=ext4 resume=/dev/mmcblk1p2 rootwait net.ifnames=0 quiet
+ fdtdir /
+ fdt /ti/k3-am67a-beagley-ai.dtb
+ fdtoverlays /overlays/k3-am67a-beagley-ai-pwm-ecap0-gpio12.dtbo
+ initrd /initrd.img
+
+ Now reboot you BeagleY-AI to load the overlay:
+
+ .. code:: console
+
+ beagle$ sudo reboot
+
+ To configure HAT pin32 (GPIO12) PWM symlink pin using ``beagle-pwm-export`` execute the command below,
+
+ .. code:: console
+
+ beagle$ sudo beagle-pwm-export --pin hat-32
+
+ We've changed the PWM pin that's being used so we need to modfiy ``servoMotor.py``.
+ Around line 16 you will see:
+
+ PWMPATH='/dev/bone/pwm/'+pwm+'/'+channel
+
+ Change it to:
+
+ PWMPATH='/dev/hat/pwm/GPIO12'
+
+ Now run your code:
+
+ beagle$ ./servoMotor.py
Running the code causes the motor to move back and forth, progressing to successive
positions between the two extremes. You will need to press ^C (Ctrl-C) to stop the script.
diff --git a/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg b/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..b747916a0b2ffe41b4acbca003ba40390b2e5214
Binary files /dev/null and b/books/beaglebone-cookbook/05tips/figures/jst-fdti.jpg differ
diff --git a/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg b/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..6a40e2d116c5d628e6d1a4a42ecc558d64db6cae
Binary files /dev/null and b/books/beaglebone-cookbook/05tips/figures/jst-sh-3-pin.jpg differ
diff --git a/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg b/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..e8b1ae61c7123527927b32018f058ae47487709d
Binary files /dev/null and b/books/beaglebone-cookbook/05tips/figures/rpi-debug-probe-connection.jpg differ
diff --git a/books/beaglebone-cookbook/05tips/tips.rst b/books/beaglebone-cookbook/05tips/tips.rst
index 30c4d831a7f25d6266815bd5c64293bc3feb01f6..8da817b52d31b4edd85eb988037fc6743157d762 100644
--- a/books/beaglebone-cookbook/05tips/tips.rst
+++ b/books/beaglebone-cookbook/05tips/tips.rst
@@ -153,7 +153,7 @@ Solution
However, the Bone has Secure Shell (SSH) enabled right out of the box, so you can easily
connect by using the following command to log in as user *debian*, (note the *$* at the end of the prompt):
-.. code-block:: bash
+.. code-block:: shell-session
host$ ssh debian@192.168.7.2
Warning: Permanently added '192.168.7.2' (ED25519) to the list of known hosts.
@@ -180,7 +180,7 @@ Default password
*debian* has the default password *temppwd*. It's best to change the password:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ password
Changing password for debian.
@@ -203,7 +203,7 @@ Solution
The contents of the files `/etc/motd`, `/etc/issue` and `/etc/issue.net` are displayed
everytime you long it. You can prevent them from being displayed by moving them elsewhere.
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo mv /etc/motd /etc/motd.orig
bone$ sudo mv /etc/issue /etc/issue.orig
@@ -234,7 +234,7 @@ shows a way that works even if you don't have a network working over USB, but it
First, check to ensure that the serial port is there. On the host computer, run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
host$ ls -ls /dev/ttyACM0
0 crw-rw---- 1 root dialout 166, 0 Jun 19 11:47 /dev/ttyACM0
@@ -244,14 +244,14 @@ First, check to ensure that the serial port is there. On the host computer, run
The letters *crw-rw----* show that you can't access it as a normal user. However, you can
access it if you are part of *dialout* group. See if you are in the *dialout* group:
-.. code-block:: bash
+.. code-block:: shell-session
host$ groups
yoder adm tty uucp dialout cdrom sudo dip plugdev lpadmin sambashare
Looks like I'm already in the group, but if you aren't, just add yourself to the group:
-.. code-block:: bash
+.. code-block:: shell-session
host$ sudo adduser $USER dialout
@@ -259,7 +259,7 @@ Looks like I'm already in the group, but if you aren't, just add yourself to the
You have to run *adduser* only once. Your host computer will remember the next
time you boot up. Now, install and run the *screen* command:
-.. code-block:: bash
+.. code-block:: shell-session
host$ sudo apt install screen
host$ screen /dev/ttyACM0 115200
@@ -316,6 +316,7 @@ To make this recipe, you will need:
Look for a small triangle at the end of the FTDI cable (:ref:`tips_FTDIconnector_fig`).
It's often connected to the black wire.
+
.. _tips_FTDIconnector_fig:
.. figure:: figures/FTDIconnector.jpg
@@ -323,25 +324,63 @@ It's often connected to the black wire.
:alt: FTDI Connector
FTDI connector
+
+.. tab-set::
-Next, look for the FTDI pins of the Bone (labeled *J1* on the Bone), shown in
-:ref:`tips_black_hardware_details_fig`. They are next to the P9 header
-and begin near pin 20. There is a white dot near P9_20.
+ .. tab-item:: BeagleBone
-.. _tips_black_hardware_details_fig:
-.. figure:: figures/FTDIPins.png
- :align: center
- :alt: Serial Debug Pins
+ Next, look for the FTDI pins of the Bone (labeled *J1* on the Bone), shown in
+ :ref:`tips_black_hardware_details_fig`. They are next to the P9 header
+ and begin near pin 20. There is a white dot near P9_20.
+
+ .. _tips_black_hardware_details_fig:
+
+ .. figure:: figures/FTDIPins.png
+ :align: center
+ :alt: Serial Debug Pins
+
+ FTDI pins for the FTDI connector
+
+ Plug the FTDI connector into the FTDI pins, being sure to connect
+ the ``triangle`` pin on the connector to the ``white dot`` pin of the *FTDI* connector.
+
+ .. tab-item:: BeagleY-AI FTDI Cable
+
+ When using the BeagleY-AI, if you already have an FTDI cable,
+ all you'll need is a JST SH Compatible 1mm Pitch 3 Pin to Male Headers Cable
+ (https://www.adafruit.com/product/5755).
+
+ .. figure:: figures/jst-sh-3-pin.jpg
+ :align: center
+ :alt: JST SH to 3 Pin Male
- FTDI pins for the FTDI connector
+ JST SH Compatible 1mm Pitch 3 Pin to Male Headers Cable
+
+ Attach the JST cable to the FTDI cable as shown below.
-Plug the FTDI connector into the FTDI pins, being sure to connect
-the ``triangle`` pin on the connector to the ``white dot`` pin of the *FTDI* connector.
+ .. figure:: figures/jst-fdti.jpg
+ :align: center
+ :alt: JST to FDTI connection
+
+ JST to FDTI connection
+
+ .. tab-item:: BeagleY-AI Debug Probe
+
+ If you don't have an FTDI cable, you can use a
+ `Raspberry Pi Debug Probe <https://www.raspberrypi.com/documentation/microcontrollers/debug-probe.html>`_
+ or similar serial (USB to UART) adapter. Connect your UART debug probe to BeagleY-AI as shown in the image below. After making the connection you can use command
+ line utility like ``tio`` on Linux or Putty on any operating system. Check :ref:`beagley-ai-headless` for more information.
+
+ .. figure:: figures/rpi-debug-probe-connection.*
+ :align: center
+ :alt: Connecting Raspberry Pi debug probe to BeagleY-AI
+
+ Connecting Raspberry Pi debug probe to BeagleY-AI
Now, run the following commands on your host computer:
-.. code-block:: bash
+.. code-block:: shell-session
host$ ls -ls /dev/ttyUSB0
0 crw-rw---- 1 root dialout 188, 0 Jun 19 12:43 /dev/ttyUSB0
@@ -374,7 +413,7 @@ Solution
Log in to your Bone and enter the following command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ cat /etc/dogtag
BeagleBoard.org Debian Bullseye IoT Image 2023-06-03
@@ -399,7 +438,7 @@ Install and run a Virtual Network Computing (VNC) server:
.. todo
Check this with desktop installed
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt update
bone$ sudo apt install tightvncserver
@@ -473,7 +512,7 @@ Click Connect to start graphical access to your Bone, as shown in :ref:`tips_vnc
.. todo
This isn't working as of 8-June-2023
-.. code-block:: bash
+.. code-block:: shell-session
bone$ bone$ sudo apt install bbb.io-xfce4-desktop
bone$ sdo cp /etc/bbb.io/templates/fbdev.xorg.conf /etc/X11/xorg.conf
@@ -585,7 +624,7 @@ Solution
The Bone comes with a number of editors. The simplest to learn is *nano*.
Just enter the following command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ nano file
@@ -642,7 +681,7 @@ it will automatically assign an IP address to the Bone.
To find the IP address, open a terminal window and run the *ip* command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ ip a
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
@@ -748,7 +787,7 @@ First, plug in the WiFi adapter and the 5 V external power supply and reboot.
Then run *lsusb* to ensure that your Bone found the adapter:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ lsusb
Bus 001 Device 002: ID 0bda:8176 Realtek Semiconductor Corp. RTL8188CUS 802.11n
@@ -768,7 +807,7 @@ Then run *lsusb* to ensure that your Bone found the adapter:
Next, run *networkctl* to find your adapter's name. Mine is
called *wlan0*, but you might see other names, such as *ra0*.
-.. code-block:: bash
+.. code-block:: shell-session
bone$ networkctl
IDX LINK TYPE OPERATIONAL SETUP
@@ -786,7 +825,7 @@ called *wlan0*, but you might see other names, such as *ra0*.
If no name appears, try *ip a*:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ ip a
...
@@ -809,7 +848,7 @@ If no name appears, try *ip a*:
Next edit the configuration file */etc/wpa_supplicant/wpa_supplicant-wlan0.conf*.
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo nano /etc/wpa_supplicant/wpa_supplicant-wlan0.conf
@@ -830,7 +869,7 @@ In the file you'll see:
Change the *ssid* and *psk* entries for your network. Save your file, then run:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo systemctl restart systemd-networkd
bone$ ip a
@@ -888,7 +927,7 @@ file called ``ipMasquerade.sh`` on your host computer.
Then, on your host, run the following commands:
-.. code-block:: bash
+.. code-block:: shell-session
host$ chmod +x ipMasquerade.sh
host$ ./ipMasquerade.sh eth0
@@ -911,7 +950,7 @@ in :ref:`tips_setDNS` to ``setDNS.sh`` on your host computer.
Then, on your host, run the following commands:
-.. code-block:: bash
+.. code-block:: shell-session
host$ chmod +x setDNS.sh
host$ ./setDNS.sh
@@ -940,7 +979,7 @@ Web servers typically listen to port *80*. First, look up the IP address of your
.. todo::
switch to ip address
-.. code-block:: bash
+.. code-block:: shell-session
host$ ip a
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
@@ -967,7 +1006,7 @@ Then run the following, using your host's IP address:
.. todo::
check this iptables, convert to ufw
-.. code-block:: bash
+.. code-block:: shell-session
host$ sudo iptables -t nat -A PREROUTING -p tcp -s 0/0 \
-d 172.31.43.210 --dport 1080 -j DNAT --to 192.168.7.2:80
@@ -997,7 +1036,7 @@ I'll summarize the initial setup here.
First install and check the status:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt update
bone$ sudo apt install ufw
@@ -1007,7 +1046,7 @@ First install and check the status:
Now turn off everything coming in and leave on all outgoing.
Note, this won't take effect until *ufw* is enabled.
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo ufw default deny incoming
bone$ sudo ufw default allow outgoing
@@ -1015,14 +1054,14 @@ Note, this won't take effect until *ufw* is enabled.
Don't enable yet, make sure *ssh* still has access
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo ufw allow 22
Just to be sure, you can install *nmap* on your host computer to see what ports are currently open.
-.. code-block:: bash
+.. code-block:: shell-session
host$ sudo apt update
host$ sudo apt install nmap
@@ -1041,7 +1080,7 @@ Just to be sure, you can install *nmap* on your host computer to see what ports
Currently there are three ports visible: 22, 80 and 3000 (visual studio code).
Now turn on the firewall and see what happens.
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
@@ -1062,7 +1101,7 @@ Only port 22 (ssh) is accessible now.
The firewall will remain on, even after a reboot. Disable it now if you don't want it on.
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo ufw disable
Firewall stopped and disabled on system startup
@@ -1089,7 +1128,7 @@ Solution
The easiest way to install more software is to use **apt**:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt update
bone$ sudo apt install "name of software"
@@ -1102,7 +1141,7 @@ The second command fetches the software and installs it and all packages it depe
How do you find out what software you can install? Try running this:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ apt-cache pkgnames | sort > /tmp/list
bone$ wc /tmp/list
@@ -1118,7 +1157,7 @@ list, one page at a time. Press the space bar to go to the next page. Press **q*
Suppose that you would like to install an online dictionary (*dict*). Just run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt install dict
@@ -1141,7 +1180,7 @@ Solution
*apt* has a *remove* option, so you can run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt remove dict
Reading package lists... Done
@@ -1167,9 +1206,33 @@ You want to move files between the onboard flash and the microSD card.
Solution
---------
+First, make sure your Beagle has eMMC. Run ``lsblk``.
+
+.. code-block:: shell-session
+
+ beagle:~$ lsblk
+ NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
+ mmcblk1 179:0 0 3.6G 0 disk
+ └─mmcblk1p1 179:1 0 3.6G 0 part
+ mmcblk1boot0 179:256 0 2M 1 disk
+ mmcblk1boot1 179:512 0 2M 1 disk
+ mmcblk0 179:768 0 7.4G 0 disk
+ └─mmcblk0p1 179:769 0 7.4G 0 part /
+
+If the results show ``mmcblk0`` and ``mmcblk1`` like above, you have eMMC and can do the
+rest of this recipe. If your results are like below, you don't have eMMC.
+
+.. code-block:: shell-session
+
+ beagle:~$ lsblk
+ NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS
+ mmcblk1 179:0 0 7.5G 0 disk
+ ├─mmcblk1p1 179:1 0 256M 0 part /boot/firmware
+ └─mmcblk1p2 179:2 0 7.3G 0 part /
+
If you booted from the microSD card, run the following command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ df -h
Filesystem Size Used Avail Use% Mounted on
@@ -1198,7 +1261,7 @@ The *ls* command shows what devices are available to mount. Because *mmcblk0* is
.. todo::
update
-.. code-block:: bash
+.. code-block:: shell-session
bone$ cd /mnt
bone$ sudo mkdir onboard
@@ -1219,7 +1282,7 @@ These are the contents of the onboard flash, which can be copied to and from lik
This same process should also work if you have booted from the onboard flash. When you are done
with the onboard flash, you can unmount it by using this command:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo umount /mnt/onboard
@@ -1253,7 +1316,7 @@ things as OpenCV, the Chromium web browser, and some documentation.
Here's how you can remove these:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt remove bb-node-red-installer (171M)
bone$ sudo apt autoremove
@@ -1266,7 +1329,7 @@ Discovering big files
The *du* (disk usage) command offers a quick way to discover big files:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo du -shx /*
12M /bin
@@ -1309,7 +1372,7 @@ of things disappeared while the command was running and thus produced some error
The ``/var`` directory appears to be the biggest user of space at 1.9 GB. You can then run the
following command to see what's taking up the space in ``/var``:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo du -sh /var/*
4.0K /var/backups
@@ -1329,7 +1392,7 @@ following command to see what's taking up the space in ``/var``:
A more interactive way to explore your disk usage is by installing *ncdu* (ncurses disk usage):
-.. code-block:: bash
+.. code-block:: shell-session
bone$ sudo apt install ncdu
bone$ ncdu /
@@ -1337,7 +1400,7 @@ A more interactive way to explore your disk usage is by installing *ncdu* (ncurs
After a moment, you'll see the following:
-.. code-block:: bash
+.. code-block:: shell-session
ncdu 1.15.1 ~ Use the arrow keys to navigate, press ? for help
--- / ------------------------------------------------------------------
@@ -1409,7 +1472,7 @@ For this example P9_14 is used, which the table shows in gpio 50.
Compile and run the code:
-.. code-block:: bash
+.. code-block:: shell-session
bone$ gcc -o blinkLED blinkLED.c
bone$ ./blinkLED
diff --git a/books/beaglebone-cookbook/06iot/iot.rst b/books/beaglebone-cookbook/06iot/iot.rst
index 2b06b712d63ac39a7ed21897213fec8795cf4d8a..7c6f4a8143951fe447e1fbfeb6828cdec6109efb 100644
--- a/books/beaglebone-cookbook/06iot/iot.rst
+++ b/books/beaglebone-cookbook/06iot/iot.rst
@@ -764,7 +764,7 @@ Run this by using the following commands:
.. code-block:: bash
- bone$ ./weather.js
+ bone$ ./weather.py
Getting weather
Temp: 73.72
Humid: 31
diff --git a/books/beaglebone-cookbook/11misc/misc.rst b/books/beaglebone-cookbook/11misc/misc.rst
index 7b03b8001ac454fd7c310b23ca44f5b7e8b74c2f..928948b86d9d00bfcc442805711790d81b09b9de 100644
--- a/books/beaglebone-cookbook/11misc/misc.rst
+++ b/books/beaglebone-cookbook/11misc/misc.rst
@@ -406,6 +406,59 @@ Now generate some traffic:
You can see the pattern ``ca11ab1ebeef`` appears in the packets.
+Find what UU is in i2cdetect
+================================
+
+Problem
+-------
+
+You run ``i2cdetect`` and want to know what the **UU**'s are.
+
+.. code-block:: shell-session
+
+ bone:~$ i2cdetect -y -r 2
+ 0 1 2 3 4 5 6 7 8 9 a b c d e f
+ 00: -- -- -- -- -- -- -- --
+ 10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 30: UU -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 40: 40 -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 50: UU -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+ 60: -- -- -- -- -- -- -- -- UU -- -- -- -- -- -- --
+ 70: -- -- -- -- -- -- -- --
+
+Solution
+--------
+
+Running ``man i2cdetect`` shows that:
+
+ "UU". Probing was skipped, because this address is currently in use by a driver. This strongly suggests that there is a chip at this address.
+
+You can quickly see what the drivers are by looking at ``/sys/bus/i2c/devices``
+
+.. code-block:: shell-session
+
+ bone:~$ cd /sys/bus/i2c/devices
+ bone:~$ ls
+ 2-0030 2-0050 2-0068 4-004c i2c-1 i2c-2 i2c-3 i2c-4 i2c-5
+
+Here on the BeagleY-AI we see there are 5 i2c buses (``i2c-1``, ``i2c-2``, ``i2c-3``, ``i2c-4`` and ``i2c-5``). There are three devices on bus 2 (``2-0030``, ``2-0050`` and ``2-0068``) and one device on bus 4 (``4-004c``). The first digit is the bus number and the last digits are the address on the bus in hex. You can see what these devices are by running:
+
+.. code-block:: shell-session
+
+ bone:~$ cat */name
+ tps65219
+ 24c32
+ ds1340
+ it66122
+ OMAP I2C adapter
+ OMAP I2C adapter
+ OMAP I2C adapter
+ OMAP I2C adapter
+ OMAP I2C adapter
+
+You can the Google the names to see what they are. For example, the ``24c32`` is a 32K EEPROM by Microchip.
+
Converting a tmp117 to a tmp114
================================
diff --git a/conf.py b/conf.py
index db300f03bce69ef8fbb25a53256d8ffb61c9b073..518bba251201e0569d1698e1ed516fcc3171dae6 100644
--- a/conf.py
+++ b/conf.py
@@ -42,6 +42,8 @@ latex_documents = []
pdf_paths = []
oshw_details = []
board_details = []
+book_details = []
+project_details = []
with open('conf.yml', 'r') as conf_file:
conf_data = yaml.safe_load(conf_file)
@@ -79,7 +81,39 @@ with open('conf.yml', 'r') as conf_file:
oshw_details.append([board, path, oshw_id])
# Board basic details
- board_details.append([board, path, page, git, forum])
+ board_details.append([name, path, page, git, forum])
+
+ # Books
+ if(type == "books"):
+ for book, data in conf_data["books"].items():
+ name = book
+ path = data['path']
+ pdf = data.get('pdf', False)
+
+ #Books PDF build details
+ if(pdf and (name in pdf_build or pdf_build_all)):
+ pdf_paths.append(path)
+ tex_name = '-'.join(path.split('/')[1:])
+ latex_documents.append((path+"/index", tex_name+".tex", "", author, "manual"))
+
+ # Book basic details
+ book_details.append([name, path])
+
+ # Projects
+ if(type == "projects"):
+ for book, data in conf_data["projects"].items():
+ project = book
+ path = data['path']
+ pdf = data.get('pdf', False)
+
+ #Projects PDF build details
+ if(pdf and (project in pdf_build or pdf_build_all)):
+ pdf_paths.append(path)
+ tex_name = '-'.join(path.split('/')[1:])
+ latex_documents.append((path+"/index", tex_name+".tex", "", author, "manual"))
+
+ # Project basic details
+ project_details.append([name, path])
# -- General configuration --
@@ -95,11 +129,55 @@ extensions = [
"sphinx.ext.todo",
"sphinx.ext.autodoc",
"sphinx.ext.autosummary",
+ "sphinxext.rediraffe",
+ "notfound.extension",
"breathe",
"sphinx_copybutton",
"sphinxcontrib.youtube",
]
+# Initialize the rediraffe_redirects dictionary
+rediraffe_redirects = {}
+rediraffe_branch_excludes = [
+ '_build',
+ '_static',
+ '_templates',
+ '.*', # Exclude hidden directories and files starting with '.'
+ '*/_*', # Exclude any directories starting with '_'
+ '*/.*', # Exclude any directories starting with '.'
+]
+
+# Automatically redirect all matching files
+rediraffe_auto_redirect_perc = 100
+
+# Define the mapping from old folders to new folders
+redirect_folders = {
+ "latest": "", # Map from 'latest/' to the root directory
+}
+
+def is_excluded(path):
+ """Check if any part of the path starts with '_' or '.'."""
+ return any(part.startswith(('_', '.')) for part in path.parts)
+
+# Loop through the files in the new folder and create redirects
+for old_folder, new_folder in redirect_folders.items():
+ # Ensure new_folder is '.' if it's empty (root directory)
+ new_folder = new_folder or '.'
+
+ # Convert new_folder to a Path object
+ new_folder_path = Path(new_folder)
+
+ # Iterate over all .rst and .md files in the new folder
+ for newpath in new_folder_path.rglob("*"):
+ # Exclude directories and files that start with '_' or '.'
+ if is_excluded(newpath.relative_to(new_folder_path)):
+ continue
+ if newpath.is_file() and newpath.suffix in [".rst"]:
+ # Build the old path by combining the old folder and the relative path of the new file
+ oldpath = Path(old_folder) / newpath.relative_to(new_folder_path)
+ # Add the mapping to rediraffe_redirects
+ rediraffe_redirects[str(oldpath)] = str(newpath.relative_to(new_folder_path))
+
#graphviz_output_format = 'svg'
breathe_projects = {"librobotcontrol": "projects/librobotcontrol/docs/xml"}
@@ -137,37 +215,7 @@ numfig = True
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env', ".venv"]
-
-# parse pages details from 'PAGES' file
-docs_url = ""
-with open("PAGES") as f:
- m = re.match(
- (
- r"^PAGES_URL\s*=\s*(\S+)$\n"
- + r"^PAGES_SLUG\s*=\s*(\S+)$\n"
- + r"^GITLAB_USER\s*=\s*(\S+)$\n"
- + r"^PROJECT_BRANCH\s*=\s*(\S+)$\n"
- + r"^GITLAB_HOST\s*=\s*(\S+)$\n"
- + r"^PROJECT_REPO\s*=\s*(\S+)$\n"
- ),
- f.read(),
- re.MULTILINE,
- )
-
- if not m:
- sys.stderr.write("Warning: Could not extract pages information\n")
- else:
- url, slug, user, branch, host, repo = m.groups(1)
- slug = "latest" if slug == "main" else slug
- pages_url = url
- pages_slug = slug
- gitlab_user = user
- gitlab_version = branch
- gitlab_url = host
- gitlab_repo = repo
- gitlab_project = "/".join((gitlab_url, gitlab_user, gitlab_repo))
- docs_url = "/".join((url, slug))
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env', ".venv", '*/_*', '*/.*',]
# HTML
html_theme = 'pydata_sphinx_theme'
@@ -261,14 +309,57 @@ html_theme_options = {
},
}
-# Variables here holds default settings
-pages_url = "https://docs.beagleboard.io"
+# Variables for gitlab pages
+pages_url = ""
pages_slug = ""
-gitlab_user = "docs"
-gitlab_version = "main"
-gitlab_url = "https://openbeagle.org"
-gitlab_repo = "docs.beagleboard.io"
-gitlab_project = "/".join((gitlab_url, gitlab_user, gitlab_repo))
+gitlab_user = ""
+gitlab_version = ""
+gitlab_url = ""
+gitlab_repo = ""
+gitlab_project = ""
+
+# parse pages details from 'PAGES' file
+docs_url = ""
+with open("PAGES") as f:
+ m = re.match(
+ (
+ r"^PAGES_URL\s*=\s*(\S+)$\n"
+ + r"^GITLAB_USER\s*=\s*(\S+)$\n"
+ + r"^PROJECT_BRANCH\s*=\s*(\S+)$\n"
+ + r"^GITLAB_HOST\s*=\s*(\S+)$\n"
+ + r"^PROJECT_REPO\s*=\s*(\S+)$\n"
+ ),
+ f.read(),
+ re.MULTILINE,
+ )
+
+ if not m:
+ sys.stderr.write("Warning: Could not extract pages information\n")
+ else:
+ url, user, branch, host, repo = m.groups(1)
+ pages_url = url
+ gitlab_user = user
+ gitlab_version = branch
+ gitlab_url = host
+ gitlab_repo = repo
+ gitlab_project = "/".join((gitlab_url, gitlab_user, gitlab_repo))
+ docs_url = url
+
+# Specify the 404 template file
+notfound_template = '404.html'
+
+# Set the URLs prefix
+if gitlab_user == 'docs':
+ notfound_urls_prefix = '/'
+elif gitlab_repo:
+ notfound_urls_prefix = '/' + gitlab_repo.strip('/') + '/'
+else:
+ notfound_urls_prefix = ''
+
+# Provide additional context variables if needed
+notfound_context = {
+ 'title': 'Page Not Found (404)',
+}
html_context = {
"display_gitlab": True,
@@ -291,6 +382,8 @@ html_context = {
"oshw_details": oshw_details,
"pdf_paths": pdf_paths,
"board_details": board_details,
+ "book_details": book_details,
+ "project_details": project_details,
"announcement_message": announcement_message,
"development_version_message": development_version_message,
"forked_version_message": forked_version_message,
diff --git a/conf.yml b/conf.yml
index f97aeee63e2ea278fb919f8217f9d886a34cddb0..c7fd163c011d3aea14a0b329f64b9441455e3ebd 100644
--- a/conf.yml
+++ b/conf.yml
@@ -92,6 +92,13 @@ boards:
oshw: PocketBeagle_US000083.svg
# Books
+books:
+ BeagleBone-Cookbook:
+ path: books/beaglebone-cookbook
+ pdf: True
+ PRU-Cookbook:
+ path: books/pru-cookbook
+ pdf: True
books:
BeagleBone Cookbook:
@@ -99,3 +106,16 @@ books:
pdf: True
# Projects
+projects:
+ BB-Config:
+ path: projects/bb-config
+ pdf: True
+ BeagleConnect:
+ path: projects/beagleconnect
+ pdf: True
+ libRobotControl:
+ path: projects/librobotcontrol
+ pdf: False
+ SimpPRU:
+ path: projects/simppru
+ pdf: True
\ No newline at end of file
diff --git a/gitlab-build.sh b/gitlab-build.sh
index d154d12ee57ee029dd70c8ef28bf6edc2cf07f4e..7307fcfc9a47a7bf374fabf8a58e50b02f5956bd 100755
--- a/gitlab-build.sh
+++ b/gitlab-build.sh
@@ -1,28 +1,14 @@
#!/bin/bash -xe
-export VER_LATEST_MAJOR=1
-export VER_LATEST_MINOR=0
-export VER_LATEST_EXTRA=wip
-export PATCHLEVEL=$(date +%Y%m%d)
-export VERSION_TWEAK=$(( $(date "+10#%H * 60 + 10#%M") ))
function do_build() {
- echo "**** Updating $PAGES_URL/$VER_DIR: $1 ****"
+ echo "**** Updating $PAGES_URL: $1 ****"
cat << EOF > PAGES
PAGES_URL = $PAGES_URL
-PAGES_SLUG = $PAGES_SLUG
GITLAB_USER = $GITLAB_USER
PROJECT_BRANCH = $PROJECT_BRANCH
GITLAB_HOST = $GITLAB_HOST
PROJECT_REPO = $PROJECT_REPO
-EOF
-
- cat << EOF > VERSION
-VERSION_MAJOR = $VERSION_MAJOR
-VERSION_MINOR = $VERSION_MINOR
-PATCHLEVEL = $PATCHLEVEL
-VERSION_TWEAK = $VERSION_TWEAK
-EXTRAVERSION = $EXTRAVERSION
EOF
echo "**** make librobotcontrol xml ****"
@@ -34,18 +20,6 @@ EOF
if [ "x$1" == "xhtml" ]; then
mkdir -p public/html
- cat <<HERE > public/html/redir.html
-<!DOCTYPE html>
-<html>
- <head>
- <meta http-equiv="refresh" content="0; url='latest/'" />
- </head>
- <body>
- <p>Please follow <a href="latest/">this link</a>.</p>
- </body>
-</html>
-HERE
-
echo "**** make html ****"
# Build HTML
make html BUILDDIR=public
@@ -69,55 +43,28 @@ HERE
if [ "x$1" == "xpublish" ]; then
# Move files
- mkdir -p public/$VER_DIR/
- mv public/html/redir.html public/index.html
- mv public/html/* public/$VER_DIR/
- mv public/pdf/*.pdf public/$VER_DIR/
+ mkdir -p public/
+ mv public/html/* public/
+ mv public/pdf/*.pdf public/
# Update docs.beagleboard.org
if [ "$CI_COMMIT_TAG" != "" ]; then
mkdir -p ~/.ssh
eval "$(ssh-agent -s)"
echo "${PRIVATE_KEY}" | base64 -d | ssh-add -
- if [ "$VER_DIR" = "latest" ]; then
- rsync -e 'ssh -p 45 -o "StrictHostKeyChecking=no"' -vP public/index.html docs@beagleboard.org:/var/www/docs/
- fi
- rsync -e 'ssh -p 45 -o "StrictHostKeyChecking=no"' -avP --delete public/$VER_DIR/. docs@beagleboard.org:/var/www/docs/$VER_DIR
+ rsync -e 'ssh -p 45 -o "StrictHostKeyChecking=no"' -avP --delete public/. docs@beagleboard.org:/var/www/docs
fi
fi
}
-if [ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then
- export VER_DIR=latest
- export PAGES_URL=$CI_PAGES_URL
- export PAGES_SLUG=$CI_COMMIT_BRANCH
- export GITLAB_USER=$CI_PROJECT_NAMESPACE
- export GITLAB_HOST=$CI_SERVER_HOST
- export PROJECT_BRANCH=$CI_COMMIT_BRANCH
- export PROJECT_REPO=$CI_PROJECT_NAME
- export VERSION_MAJOR=$VER_LATEST_MAJOR
- export VERSION_MINOR=$VER_LATEST_MINOR
- export EXTRAVERSION=$VER_LATEST_EXTRA
- do_build $1
-elif [ "$CI_COMMIT_BRANCH" != "" ]; then
- export VER_DIR=$CI_COMMIT_BRANCH
+if [ "$CI_COMMIT_BRANCH" != "" ]; then
export PAGES_URL=$CI_PAGES_URL
- export PAGES_SLUG=$CI_COMMIT_BRANCH
export GITLAB_USER=$CI_PROJECT_NAMESPACE
export GITLAB_HOST=$CI_SERVER_HOST
export PROJECT_BRANCH=$CI_COMMIT_BRANCH
export PROJECT_REPO=$CI_PROJECT_NAME
- export BRANCH_VER=($(echo $CI_COMMIT_BRANCH | tr "." "\n"))
- export VERSION_MAJOR=${BRANCH_VER[0]}
- export VERSION_MINOR=${BRANCH_VER[1]}
- export EXTRAVERSION=wip
do_build $1
elif [ "$CI_COMMIT_TAG" != "" ]; then
- export TAG_SPLIT=($(echo $CI_COMMIT_TAG | tr "-" "\n"))
- export TAG_VER=($(echo ${TAG_SPLIT[0]} | tr "." "\n"))
- export VERSION_MAJOR=${TAG_VER[0]}
- export VERSION_MINOR=${TAG_VER[1]}
- export EXTRAVERSION=${TAG_SPLIT[1]}
export PAGES_URL=https://docs.beagleboard.org
export GITLAB_USER=docs
export GITLAB_HOST=$CI_SERVER_HOST
@@ -125,13 +72,6 @@ elif [ "$CI_COMMIT_TAG" != "" ]; then
git fetch --all -v
export GIT_BRANCH=$(git branch -a --contains tags/$CI_COMMIT_TAG | grep origin | tr -d '* ' | sed 's/.*origin\///' | head -n 1)
export PROJECT_BRANCH=$GIT_BRANCH
- if [ "$GIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]; then
- export VER_DIR=latest
- export PAGES_SLUG=latest
- else
- export VER_DIR=$GIT_BRANCH
- export PAGES_SLUG=$GIT_BRANCH
- fi
export SPHINXOPTS="-D todo_include_todos=0"
do_build $1
else
diff --git a/intro/contribution/how.rst b/intro/contribution/how.rst
index 66ada15ab2c3eb50320b25376297f9233bd001b0..b1649d3b249da856291502852351a8982d58911b 100644
--- a/intro/contribution/how.rst
+++ b/intro/contribution/how.rst
@@ -4,38 +4,32 @@ How can I contribute?
#####################
The most obvious way to contribute is using the `OpenBeagle (BeagleBoard.org GitLab server) <https://openbeagle.org>`_ to report
-bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware
-designs and documentation.
+bugs, suggest enhancements and providing merge requests / pull requests to fix software, hardware designs and documentation. We
+have made it easy to share the link while you are working with documentation and provide feedback for any heading, figure, and table.
-Reading the `help guide <https://openbeagle.org/help/>`_ is a great way to get started using OpenBeagle.
+1. :fas:`link;pst-color-secondary` button is to copy the link of current heading, figure, or table.
+2. :fas:`message;pst-color-secondary` button is to open feedback modal for submitting issue, feedback, and idea.
-.. _contribution-todo-list:
-
-Tackle to-do list
-*****************
+.. figure:: images/copy-link-and-feedback-button.png
+ :align: center
+ :alt: Copy link and feedback button
-This documentation has a number of ``todo`` items where help is needed that can be searched in the source. This list will
-show up directly in the staging documentation at https://docs.beagleboard.io/latest/intro/contribution/how.html#contribution-todo-list
-
-.. todolist::
-
-Google Summer of Code (GSoC)
-****************************
-
-For newcomers venturing into the realm of open-source contribution, Google Summer of Code (GSoC) stands as an invaluable platform. GSoC provides a unique opportunity to collaborate with the open-source community, engaging in the identification and development of exciting projects during the summer term.
-
-BeagleBoard.org serves as a mentorship organization that takes part in the Google Summer of Code program actively, giving students the opportunity to work on open-source projects during the summer. Visit our dedicated :ref:`beagleboard-gsoc` for more information about this program, including past projects and mentorship opportunities.
+ Copy link and feedback button
-Reporting bugs
-***************
+When you click on :fas:`message;pst-color-secondary` button, you will see the modal as shown in the image below.
+With this you can easily provide us ideas, feedback, and create issues directly on OpenBeagle from docs site.
-Start by reading the `OpenBeagle Issues help page <https://openbeagle.org/help/user/project/issues/index.md>`_.
+.. figure:: images/feedback-modal.png
+ :align: center
+ :alt: Feedback modal
-Please request an account and report any issues on the appropriate project issue tracker at https://openbeagle.org.
+ Feedback modal
-Report issues on the software images at https://openbeagle.org/explore/topics/distros.
+.. note::
+ You need an active OpenBeagle account to use the feedback modal.
-Report issues on the hardware at https://openbeagle.org/explore/projects/topics/boards.
+.. tip::
+ Reading the `help guide <https://openbeagle.org/help/>`_ is a great way to get started using OpenBeagle.
Suggesting enhancements
***********************
@@ -61,6 +55,247 @@ we'll review your work and give comments back to you. If suitable, we'll update
A bit more detailed suggestions can be found in the articles linked below.
+.. _docs-site-editing-guide:
+
+Site Editing Guide
+*******************
+
+`Docs <https://docs.beagleboard.org/>`_ site uses `OpenBeagle Continous Integration (CI) / Continous Development
+(CD) <https://docs.gitlab.com/ee/ci/>`_ which is a continuous method of software development, where
+you continuously build, test, deploy, and monitor iterative code changes. which means you don't have to setup
+anything on your local machine to update anything on the site. To contribute to this site, you can follow the
+simple steps provided below.
+
+.. note:: `OpenBeagle <https://openbeagle.org/>`_ is a self hosted instance of open source program called `GitLab <https://about.gitlab.com/>`_.
+
+.. tip::
+
+ If you want to build on your local machine we have added ``venv-build-env.sh`` and ``requirements.txt``
+ to help you setup sphinx and all the other dependencies. Execute these commands in your terminal,
+
+ Install python modules and setup virtual environment,
+
+ .. code:: shell
+
+ . ./venv-build-env.sh
+
+ Build and serve it live using ``sphinx-autobuild``,
+
+ .. code:: shell
+
+ make livehtml
+
+ Now, you can open `http://127.0.0.1:8000 <http://127.0.0.1:8000>`_ on any browser to see the rendered HTML with live updates.
+ Clear cookies and site data in your browser window to view up-to-date site.
+
+Fork the project
+=================
+
+Go to `docs.beagleboard.io repo on OpenBeagle <https://openbeagle.org/docs/docs.beagleboard.io>`_
+and click on fork button create a fork on your personal OpenBeagle profile.
+
+.. figure:: images/fork-button.png
+ :align: center
+ :alt: Fork button
+
+ Fork button
+
+After clicking on the fork button, you'll be taken to a page like shown below where you have to,
+
+1. Select your profile from the dropdown.
+2. Click on fork project button to initiate the forking process.
+
+.. figure:: images/fork-project.png
+ :align: center
+ :alt: Fork project
+
+ Fork project
+
+Select file to edit
+====================
+
+After successfully forking the project you have to,
+
+1. Make sure you are on the forked repo on your profile, it should be ``https://openbeagle.org/<user-name>/docs.beagleboard.io`` where <user-name> should be replaced with your OpenBeagle username.
+2. Select any file you want to edit from the files & folders view of the repo page.
+
+.. figure:: images/repo-file-folders.png
+ :align: center
+ :alt: Repository files and folders
+
+ Repository files and folders
+
+After selecting the file you have to click on ``edit button`` and then choose either of the options from drop-down,
+
+1. ``Open in Web IDE``, choose this if you want to work on multiple files.
+2. ``Edit single file``, choose this if you want to make some small edits in a single file.
+
+.. figure:: images/edit-button.png
+ :align: center
+ :alt: Edit button
+
+ Edit button
+
+.. note::
+ Choosing ``Web IDE`` will load a `Visual Studio Code Server <https://code.visualstudio.com/docs/remote/vscode-server>`_
+ instance which is a feature rich source code editor. Depending on the internent connection, your machine will take some time to
+ load the editor and it can be a bit heavy for some machines to handle. Once fully loaded it should run smoothly but, if that is
+ not the case then please consider using single file editor option. Considering majority of the users will be using ``Web IDE`` option,
+ we are using the ``Web IDE`` for the rest of this guide.
+
+Start editing
+==============
+
+If you select to open your file in ``Web IDE`` you'll see a familar interface. The GitLab Web IDE is actually a rich
+`Visual Studio Code Server <https://code.visualstudio.com/docs/remote/vscode-server>`_ hosted on OpenBeagle.
+
+.. figure:: images/ide.png
+ :align: center
+ :alt: Web IDE
+
+ Wed IDE
+
+.. tip:: We use `reStructuredText (RST) <https://en.wikipedia.org/wiki/ReStructuredText>`_ for all of our documentation projects
+ including `GSoC site <https://gsoc.beagleboard.io/>`_ and `documentation site <https://docs.beagleboard.org/latest/>`_.
+ If you are new to reStructuredText you can checkout our `reStructuredText cheatsheet <https://docs.beagleboard.org/latest/
+ intro/contribution/rst-cheat-sheet.html>`_ to get yourself familiar with reStructuredText.
+
+.. admonition:: Why not use Markdown for documentation?
+
+ Because reStructuredText stands out against Markdown as,
+
+ 1. It’s more fully-featured.
+ 2. It’s much more standardized and uniform.
+ 3. It has built-in support for extensions.
+
+ For more detailed comparison you can checkout `this article on reStructuredText vs. Markdown for technical
+ documentation <https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/>`_
+
+Now you have to select a file and start editing. Below image shows some,
+
+1. Edits made to the ``conf.py`` file, changes are highlighted with green bar on left side of code editor window near line numbers.
+2. Source control button indicating (1) file updated in the repo.
+
+.. figure:: images/make-edits.png
+ :align: center
+ :alt: Make edits
+
+ Make edits
+
+.. tip:: Just like you do on your normal Visual Studio Code desktop application, to commit your changes you can either
+ click on Source control ( :fa:`code-branch;pst-color-secondary` ) button or press ``CTRL + SHIFT + G`` to see all the edited files.
+
+After switching to source control you have to,
+
+1. Add a commit message in the input field then commit your changes.
+2. Click on ``Commit to main`` button (not recommended).
+3. Click on drop down button to choose ``Commit to new branch`` (recommended).
+
+.. figure:: images/commit-changes.png
+ :align: center
+ :alt: Commit changes
+
+ Commit changes
+
+After clicking ``Commit to 'main'`` button you'll be prompted with a window (shown below) with three options,
+
+1. ``Create new branch``
+2. ``Cancel``
+3. ``Continue``
+
+Click on ``Continue`` button if you want to commit to main (default branch) if it's a single edit or commit.
+Click on ``Create new branch`` if you want to create a new branch and want to keep your main branch clean. Advantage
+of creating a new branch is that assigned reviewer for a pull request / merge request can also add commits to your
+newly created branch which is not possible for your main branch because it's a `protected branch <https://docs.gitlab.com/
+ee/user/project/protected_branches.html>`_ by default.
+
+.. figure:: images/commit-branch.png
+ :align: center
+ :alt: Commit branch
+
+ Commit branch
+
+When all done right, at the lower right side of the ``Web IDE`` you'll see a prompt showing
+``Success! Your changes have been committed`` message with two buttons,
+
+1. ``Go to Project``
+2. ``Continue working``
+
+.. figure:: images/commit-success.png
+ :align: center
+ :alt: Commit success
+
+ Commit success
+
+If you click on ``Go to Project`` button, you'll see,
+1. The commit successfully applied and the green tick shown on the right side indicates that the CI build was also successful.
+2. Option to create a merge request and update your fork.
+
+.. figure:: images/commit.png
+ :align: center
+ :alt: Commit
+
+ Commit
+
+.. admonition:: Congratulations!!
+
+ You have made a valuable contribution to an OpenBeagle project!
+
+Create a merge request
+=======================
+
+After making your changes and commiting them to your forked repo, you are set to create a new `pull request / merge request
+<https://en.wikipedia.org/wiki/Distributed_version_control#Pull_requests>`_ so that those changes can be merged to upstream
+repo. To start your new PR, click on the dedicated button to create a new merge request and fill out all the details. The image
+below shows all the fields you have to update,
+
+1. Provide a good title that reflects your work.
+2. Add a detailed description of the work you have done. Add pictures whenever seems useful.
+3. (Optional) you can assign it to yourself if you'll be working on further updates or assign it to someone else who might want to work on the comments we may provide on your work.
+4. Add ``lorforlinux`` as reviewer for PRs with site content update or add your mentor as reviewer if it's related to project work / proposal.
+5. If you want your commits to be shown as a single commit, then you can choose the ``sqash commits ...`` check box.
+6. Check if all your commits are shown in the bottom of the screen and if everything looks okay, then click on ``Create merge request`` button.
+
+.. tip:: If you are still working on some updates, you may also choose ``Mark as draft`` checkbox (below title)
+ which indicates that you are seeking feedback before making your commits suitable to merge.
+
+.. figure:: images/merge-request.png
+ :align: center
+ :alt: Merge request
+
+ Merge request
+
+Now wait for a review and, if comments are raised, then you can continue working on the project
+until everything looks perfect and your changes are merged in upstream.
+
+Google Summer of Code (GSoC)
+****************************
+
+For newcomers venturing into the realm of open-source contribution, Google Summer of Code (GSoC) stands as an invaluable platform. GSoC provides a unique opportunity to collaborate with the open-source community, engaging in the identification and development of exciting projects during the summer term.
+
+BeagleBoard.org serves as a mentorship organization that takes part in the Google Summer of Code program actively, giving students the opportunity to work on open-source projects during the summer. Visit our dedicated :ref:`beagleboard-gsoc` for more information about this program, including past projects and mentorship opportunities.
+
+Reporting bugs
+***************
+
+Start by reading the `OpenBeagle Issues help page <https://openbeagle.org/help/user/project/issues/index.md>`_.
+
+Please request an account and report any issues on the appropriate project issue tracker at https://openbeagle.org.
+
+Report issues on the software images at https://openbeagle.org/explore/topics/distros.
+
+Report issues on the hardware at https://openbeagle.org/explore/projects/topics/boards.
+
+.. _contribution-todo-list:
+
+Tackle to-do list
+*****************
+
+This documentation has a number of ``todo`` items where help is needed that can be searched in the source. This list will
+show up directly in the staging documentation at https://docs.beagleboard.io/latest/intro/contribution/how.html#contribution-todo-list
+
+.. todolist::
+
Articles on contribution
**************************
diff --git a/intro/contribution/images/commit-branch.png b/intro/contribution/images/commit-branch.png
new file mode 100644
index 0000000000000000000000000000000000000000..a12463e10c19ec0c29431ad12d8a4b368e91f967
Binary files /dev/null and b/intro/contribution/images/commit-branch.png differ
diff --git a/intro/contribution/images/commit-changes.png b/intro/contribution/images/commit-changes.png
new file mode 100644
index 0000000000000000000000000000000000000000..a1b09a488a3e26f5c750dee3d36d1e12719fd085
Binary files /dev/null and b/intro/contribution/images/commit-changes.png differ
diff --git a/intro/contribution/images/commit-success.png b/intro/contribution/images/commit-success.png
new file mode 100644
index 0000000000000000000000000000000000000000..f0f3410e4cf6e8ca4d0d852a81c7a12c0b428f49
Binary files /dev/null and b/intro/contribution/images/commit-success.png differ
diff --git a/intro/contribution/images/commit.png b/intro/contribution/images/commit.png
new file mode 100644
index 0000000000000000000000000000000000000000..d75ee3d9bf50058f26a89902c8ab1fe61bb7b01c
Binary files /dev/null and b/intro/contribution/images/commit.png differ
diff --git a/intro/contribution/images/copy-link-and-feedback-button.png b/intro/contribution/images/copy-link-and-feedback-button.png
new file mode 100644
index 0000000000000000000000000000000000000000..5d1a2956d096ed95301db4bc1e6209f3a81cac46
Binary files /dev/null and b/intro/contribution/images/copy-link-and-feedback-button.png differ
diff --git a/intro/contribution/images/edit-button.png b/intro/contribution/images/edit-button.png
new file mode 100644
index 0000000000000000000000000000000000000000..1f25248437640c9f3740f8caa648a485decc4d8a
Binary files /dev/null and b/intro/contribution/images/edit-button.png differ
diff --git a/intro/contribution/images/feedback-modal.png b/intro/contribution/images/feedback-modal.png
new file mode 100644
index 0000000000000000000000000000000000000000..bdfed6878ce4fb16003106e35ae8d533e42ec2f7
Binary files /dev/null and b/intro/contribution/images/feedback-modal.png differ
diff --git a/intro/contribution/images/fork-button.png b/intro/contribution/images/fork-button.png
new file mode 100644
index 0000000000000000000000000000000000000000..ed1f7c9176ca2dc495edac6de7c98bbcb70a391b
Binary files /dev/null and b/intro/contribution/images/fork-button.png differ
diff --git a/intro/contribution/images/fork-project.png b/intro/contribution/images/fork-project.png
new file mode 100644
index 0000000000000000000000000000000000000000..1a6ea588a2a995e204ecfdbfa74095bf0ef5674e
Binary files /dev/null and b/intro/contribution/images/fork-project.png differ
diff --git a/intro/contribution/images/ide.png b/intro/contribution/images/ide.png
new file mode 100644
index 0000000000000000000000000000000000000000..09ba5376cdded6b8f12374219293081c5aacee90
Binary files /dev/null and b/intro/contribution/images/ide.png differ
diff --git a/intro/contribution/images/make-edits.png b/intro/contribution/images/make-edits.png
new file mode 100644
index 0000000000000000000000000000000000000000..7979e44e7fbd32d4240bbcb4008f185c75ee8c15
Binary files /dev/null and b/intro/contribution/images/make-edits.png differ
diff --git a/intro/contribution/images/merge-request.png b/intro/contribution/images/merge-request.png
new file mode 100644
index 0000000000000000000000000000000000000000..5f72cabe174a1b4d32629ca6a709fe7b63ac34c5
Binary files /dev/null and b/intro/contribution/images/merge-request.png differ
diff --git a/intro/contribution/images/repo-file-folders.png b/intro/contribution/images/repo-file-folders.png
new file mode 100644
index 0000000000000000000000000000000000000000..49eb086f9c0835a5136631d64d213abe4aede849
Binary files /dev/null and b/intro/contribution/images/repo-file-folders.png differ
diff --git a/requirements.txt b/requirements.txt
index 0f24296d2da78f0da0e67aa7bd3a0abf6882928a..592ffd72b3f452f0edee1459f1ca7bdce1335c8d 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -37,3 +37,5 @@ sphinxcontrib-youtube==1.4.1
tornado==6.4
urllib3==2.1.0
pyyaml>=3.13
+sphinxext-rediraffe>=0.2.7
+sphinx-notfound-page>=1.0.4