Cleanups

CONTRIBUTING.md

@@ -2,30 +2,20 @@
 
 **First off, thanks for taking the time to think about contributing!**
 
-The following is a set of guidelines for contributing to docs.beagleboard.io, which is hosted by the BeagleBoard.org Foundation at https://git.beagleboard.org/docs/docs.beagleboard.io. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+The following is a set of guidelines for contributing to docs.beagleboard.io, which is hosted by
+the BeagleBoard.org Foundation at https://git.beagleboard.org/docs/docs.beagleboard.io. These are
+mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this
+document in a pull request.
 
 ## Code of Conduct
 
-This project and everyone participating in it is governed by the [BeagleBoard.org Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [coc@bbb.io](mailto:coc@bbb.io) or contact one of the administrators on https://forum.beagleboard.org.
+This project and everyone participating in it is governed by
+the [BeagleBoard.org Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to
+uphold this code. Please report unacceptable behavior to [coc@bbb.io](mailto:coc@bbb.io) or
+contact one of the administrators on https://forum.beagleboard.org.
 
 ## FAQ
 
 * [Frequently Asked Questions category on the BeagleBoard.org Forum](https://forum.beagleboard.org/c/faq/19)
 
-## What should I know before I get started?
-
-## How can I contribute?
-
-### Reporting bugs
-
-### Suggesting enhancements
-
-### Submitting pull requests
-
-## Style guides
-
-### Git commit messages
-
-### RST style guide
-
-## Additional notes
+See more at https://docs.beagleboard.org/en/latest/intro/contribution/.

boards/beaglebone/index.rst

@@ -10,7 +10,7 @@ embedded Linux single board computer.
 `BeagleBone AI-64 <ai-64>`__ is our most powerful design with tremendous machine learning inference
 performance and 
 
-For simplicity of developing small, mobile robotics, check out BeagleBone Blue, a highly
+For simplicity of developing small, mobile robotics, check out `BeagleBone Blue <blue>`__, a highly
 integrated board with motor drivers, battery support, altimeter, gyroscope, accelerometer,
 and much more to get started developing quickly.
 

books/beaglebone-cookbook/01basics/basics.rst

@@ -3,9 +3,6 @@
 Basics
 #######
 
-Introduction
-*************
-
 When you buy BeagleBone Black, pretty much everything you need to get going comes with it. 
 You can just plug it into the USB of a host computer, and it works. The goal of this 
 chapter is to show what you can do with your Bone, right out of the box. It has enough 

books/beaglebone-cookbook/02sensors/sensors.rst

@@ -3,9 +3,6 @@
 Sensors
 ########
 
-Introduction
-*************
-
 In this chapter, you will learn how to sense the physical world with BeagleBone Black. 
 Various types of electronic sensors, such as cameras and microphones, can be connected 
 to the Bone using one or more interfaces provided by the standard USB 2.0 host port, 

books/beaglebone-cookbook/03displays/displays.rst

@@ -3,9 +3,6 @@
 Displays and Other Outputs
 ###########################
 
-Introduction
-*************
-
 In this chapter, you will learn how to control physical hardware via 
 BeagleBone Black's general-purpose input/output (GPIO) pins. The Bone has 
 65 GPIO pins that are brought out on two 46-pin headers, called 

books/beaglebone-cookbook/04motors/motors.rst

@@ -3,9 +3,6 @@
 Motors
 ########
 
-Introduction
-**************
-
 One of the many fun things about embedded computers is that you can move physical things with motors.
 But there are so many different kinds of motors (``servo``, ``stepper``, ``DC``), so how do you select the right one?
 

books/beaglebone-cookbook/05tips/tips.rst

@@ -3,9 +3,6 @@
 Beyond the Basics
 ##################
 
-Introduction
-*************
-
 In :ref:`beaglebone-cookbook-basics`, you learned how to set up BeagleBone Black, and 
 :ref:`beaglebone-cookbook-sensors`, :ref:`beaglebone-cookbook-displays`, 
 and :ref:`beaglebone-cookbook-motors` showed how to 

books/beaglebone-cookbook/06iot/iot.rst

@@ -3,9 +3,6 @@
 Internet of Things
 ####################
 
-Introduction
-*************
-
 You can easily connect BeagleBone Black to the Internet via a wire (:ref:`networking_wired`), wirelessly 
 (:ref:`networking_wireless`), or through the USB to a host and then to the Internet (:ref:`networking_usb`). 
 Either way, it opens up a world of possibilities for the "Internet of Things" (IoT). 

books/beaglebone-cookbook/07kernel/kernel.rst

@@ -3,9 +3,6 @@
 The Kernel
 ###########
 
-Introduction
-*************
-
 The kernel is the heart of the Linux operating system. It's the software that takes the 
 low-level requests, such as reading or writing files, or reading and writing general-purpose 
 input/output (GPIO) pins, and maps them to the hardware. When you install a new version of the 

books/beaglebone-cookbook/08realtime/realtime.rst

@@ -3,9 +3,6 @@
 Real-Time I/O
 ###############
 
-Introduction
-*************
-
 Sometimes, when BeagleBone Black interacts with the physical world, it needs to respond in a timely manner. 
 For example, your robot has just detected that one of the driving motors needs to turn a bit faster. 
 Systems that can respond quickly to a real event are known as ``real-time`` systems. There are two broad 

books/beaglebone-cookbook/09capes/capes.rst

@@ -3,9 +3,6 @@
 Capes
 #####
 
-Introduction
-**************
-
 Previous chapters of this book show a variety of ways to interface BeagleBone Black 
 to the physical world by using a breadboard and wiring to the +P8+ and +P9+ headers. 
 This is a great approach because it's easy to modify your circuit to debug it or try 

books/beaglebone-cookbook/10parts/parts.rst

@@ -3,9 +3,6 @@
 Parts and Suppliers
 ####################
 
-Parts
-******
-
 The following tables list where you can find the parts used in this book. 
 We have listed only one or two sources here, but you can often find a given part in many places.
 

conf.py

@@ -148,6 +148,10 @@ latex_documents = [
     ("index-tex", "beagleboard-docs.tex", "BeagleBoard Docs", author, "manual"),
 ]
 
+#language = 'en'
+#locales_dir = ['locale/']
+#gettext_compact = True
+
 def setup(app):
     # theme customizations
     app.add_css_file("css/custom.css")

index.rst

@@ -8,9 +8,11 @@ BeagleBoard Documentation
 
 Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__.
 
-.. note:: BeagleBoard.org is a US-based 501(c)3 non-profit organization providing open hardware
+.. note:: 
+   The BeagleBoard.org Foundation is a US-based 501(c)3 non-profit organization providing open hardware
    computing solutions for a community of makers, educators and professionals that enable
-   rapid prototyping without barriers to creating real-world embedded systems.
+   rapid prototyping without barriers to creating real-world embedded systems. The BeagleBoard.org Foundation
+   supports the BeagleBoard community through efforts like developing this documentation.
 
 Introduction
 ************
@@ -26,6 +28,7 @@ Get started by `engaging the BealgeBoard.org developer community </intro/>`__.
    :caption: Introduction
 
    /intro/support/index
+   /intro/bone101/index
    /intro/contribution/index
 
 

intro/bone101/index.rst

+.. _intro_bone101:
+
+Bone101
+#######
+
+.. note::
+   This page is under construction. Most of the information here is drastically out of date.
+
+Most of the useful information has moved to :ref:`bone-cook-book-home` , but this can be
+to be a place for nice introductory articles on using Bealges and Linux from a different
+approach.
+
+Articles under construction:
+
+* :ref:`qwiic_stemma_grove_addons`
+
+Also, I don't want to completely lose the useful documentation we had at:
+
+* https://beagleboard.github.io/bone101/Support/bone101/
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   /intro/bone101/qwiic-stemma-grove-addons.rst
+

intro/bone101/qwiic-stemma-grove-addons.rst

+.. _qwiic_stemma_grove_addons:
+
+QWIIC, STEMMA and Grove Add-ons in Linux
+########################################
+
+.. note::
+
+   This article is under construction.
+
+I'm creating a place for me to start taking notes on how to load drivers for I2C devices (mostly), but also other Grove add-ons.
+
+For simplicity sake, I'll use these definitions
+
+* **add-on**: the QWIIC, STEMMA (QT) or Grove add-on separate from your Linux computer
+* **device**: the "smart" IC on the add-on to which we will interface from your Linux computer
+* **board**: the Linux single board computer with the embedded interface controller you are using
+* **module**: a kernel module that might contain the driver
+
+.. _bone101_i2c:
+
+Using I2C with Linux drivers
+****************************
+
+Linux has a ton of drivers for I2C devices. We just need a few parameters to load them.
+
+Using a Linux I2C kernel driver module can be super simple, like in the below example for
+monitoring a digital light sensor.
+
+.. code-block:: bash
+
+  cd /sys/bus/i2c/devices/i2c-1
+  echo tsl2561 0x29 > new_device
+  watch -n0 cat "1-0029/iio:device0/in_illuminance0_input"
+
+Once you issue this, your screen continuously refresh with luminance values from the
+add-on sensor.
+
+In the above example, `/sys/bus/i2c/devices/i2c-1` comes from which I2C controller
+we are using on the board and there are specific pins on the board where you can
+access it.
+
+`tsl2561` is the name of the driver we want to load and `0x29` is the address of the
+device on the I2C bus. If you want to know about I2C device addresses, the
+`Sparkfun I2C tutorial <https://learn.sparkfun.com/tutorials/i2c>`__ isn't a bad
+place to start. The `new_device` virtual file is documented in the
+`Linux kernel documentation on instantiating I2C devices <https://www.kernel.org/doc/html/v5.19/i2c/instantiating-devices.html>`__.
+
+On the last line, `watch <https://manpages.debian.org/bullseye/procps/watch.1.en.html>`__
+is a program that will repeatedly run the command that follows. The `-n0` sets the refresh 
+rate. The program `cat <https://manpages.debian.org/bullseye/coreutils/cat.1.en.html>`__
+will share the contents of the file `1-0029/iio\:device0/in_illuminance0_input`.
+
+`1-0029/iio:device0/in_illuminance0_input` is not a file on a disk, but output directly
+from the driver. The 1 in `1-0029` represents the I2C controller index. The `0029`
+represents the device I2C address. Most small sensor and actuator drivers will show up as
+`Industrial I/O (IIO) devices <https://www.kernel.org/doc/html/v5.19/driver-api/iio/index.html>`__.
+New IIO devices get incrementing indexes. In this case, `iio:device0` is the first IIO device
+driver loaded. Finally, `in_illuminance0_input` comes from the
+`SYSFS <https://www.kernel.org/doc/html/v5.19/filesystems/sysfs.html>`__ 
+`application binary interface <https://www.kernel.org/doc/html/v5.19/admin-guide/abi.html>`__
+for this type of device, a light sensor. The
+`Linux kernel ABI documentation for sysfs-bus-iio <https://www.kernel.org/doc/html/v5.19/admin-guide/abi-testing.html#abi-sys-iio-devicex-in-illuminance-input>`__ provides the definition of available data often provided by light sensor drivers.
+
+.. code-block::
+
+  What:		/sys/.../iio:deviceX/in_illuminance_input
+  What:		/sys/.../iio:deviceX/in_illuminance_raw
+  What:		/sys/.../iio:deviceX/in_illuminanceY_input
+  What:		/sys/.../iio:deviceX/in_illuminanceY_raw
+  What:		/sys/.../iio:deviceX/in_illuminanceY_mean_raw
+  What:		/sys/.../iio:deviceX/in_illuminance_ir_raw
+  What:		/sys/.../iio:deviceX/in_illuminance_clear_raw
+  KernelVersion:	3.4
+  Contact:	linux-iio@vger.kernel.org
+  Description:
+		Illuminance measurement, units after application of scale
+		and offset are lux.
+
+Read further to discover how to find these bits of magic text used above.
+
+The generic steps are fairly simple:
+
+1. :ref:`Identify the name and address used to load the appropriate driver for your add-on <bone101_i2c_driver_name>`
+2. :ref:`Ensure the driver is included in your kernel build <bone101_i2c_kernel_cfg>`
+3. :ref:`Identify the location of the I2C signals on the board and the controller link in Linux <bone101_i2c_dev>`
+4. :ref:`Ensure the board pinmux is set properly to expose the I2C peripheral <bone101_i2c_pinmux>`
+5. :ref:`Ensure the board to add-on connection is good <bone101_i2c_wiring>`
+6. :ref:`Issue the Linux command to load the driver <bone101_i2c_command>`
+7. :ref:`Identify and utilize the interface provided by the driver <bone101_i2c_iio>`
+
+.. _bone101_i2c_driver_name:
+
+Driver name
+===========
+
+One resource that is very helpful is the list that Vaishnav put together for supporting
+Mikroelektronika Click add-ons. His `list of Click add-ons with driver information <https://git.beagleboard.org/jkridner/manifesto/-/blob/main/click_info.csv>`__ can help a lot with matching
+a device to the driver name, device address, and kernel configuration setting.
+
+.. note::
+
+  Documentation for your particular add-on might indicate a different device address than is
+  configured on Click add-ons.
+
+I'm not aware of a trivial way of discovering the mapping that Vaishnav created outside
+of looking at the kernel sources. As an example, let's look at the 
+`Grove Digital Light Sensor add-on <https://wiki.seeedstudio.com/Grove-Digital_Light_Sensor/>`__ 
+which is documented to utilize a TSL2561.
+
+Searching through the kernel sources, we can find the driver code at
+`drivers/iio/light/tsl2563.c`. There is a list of driver names in a
+`i2c_device_id table <https://elixir.bootlin.com/linux/v5.19.5/source/drivers/iio/light/tsl2563.c#L862>`__:
+
+.. code-block::
+
+  static const struct i2c_device_id tsl2563_id[] = {
+  	{ "tsl2560", 0 },
+  	{ "tsl2561", 1 },
+  	{ "tsl2562", 2 },
+  	{ "tsl2563", 3 },
+  	{}
+  };
+
+.. important::
+
+  Don't miss that the driver, `tsl2561` , is actually part of a a superset driver, `tsl2563` . This can make things a bit trickier to find, so you have to look
+  within the text of the driver source, not just the filenames.
+
+
+.. _bone101_i2c_kernel_cfg:
+
+Kernel configuration
+====================
+
+.. _bone101_i2c_dev:
+
+I2C signals and controller
+==========================
+
+.. _bone101_i2c_pinmux:
+
+Pinmuxing
+=========
+
+.. _bone101_i2c_wiring:
+
+Wiring
+======
+
+.. _bone101_i2c_command:
+
+Load driver
+===========
+
+.. _bone101_i2c_iio:
+
+Interface
+=========
+
+.. _bone101_i2c_addons:
+
+Finding I2C add-on modules
+==========================
+
+.. note::
+
+  There are some great resources out there:
+
+  * `Adafruit list of I2C devices <https://learn.adafruit.com/i2c-addresses/the-list>`__
+  * `Sparkfun list of QWIIC devices <https://www.sparkfun.com/qwiic>`__
+  * `Adafruit STEMMA QT introduction <https://learn.adafruit.com/introducing-adafruit-stemma-qt/sparkfun-qwiic>`__
+
+.. _bone101_i2c_pitfalls:
+
+Pitfalls
+========
+
+Not all I2C devices with drivers in the Linux kernel can be loaded this way. The most common
+reason is that the device driver expects an interrupt signal or other GPIO along with the I2C
+communication. In these cases, a device tree overlay or driver modification may be necessary.

intro/contribution/index.rst

@@ -3,10 +3,65 @@
 Contribution 
 ###############
 
-.. note:: This section is under developmement right now.
+.. note::
+   This section is under developmement right now.
+
+.. important::
+   First off, thanks for taking the time to think about contributing!
+
+The BeagleBoard.org Foundation maintains source for many open source projects.
+
+Example projects suitable for first contributions:
+
+* `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__
+* `Debian image bug repository <https://git.beagleboard.org/beagleboard/Latest-Images>`__
+* `Debian image builder <https://git.beagleboard.org/beagleboard/image-builder>`__
+
+These guidelines are mostly suggestions, not hard-set rules. Use your best judgment, and feel free
+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.
+
+.. note::
+   Check out https://forum.beagleboard.org/faq as a starting place to unify our code of conduct.
+
+By participating, you are expected to
+uphold this code. Please report unacceptable behavior to
+contact one of our administrators or moderators on https://forum.beagleboard.org/about.
+
+Frequently Asked Questions
+**************************
+
+* `Frequently asked questions contribution category on the BeagleBoard.org Forum <https://forum.beagleboard.org/c/faq/19>`__
+
+What should I know before I get started?
+****************************************
+
+How can I contribute?
+*********************
+
+Reporting bugs
+===============
+
+Suggesting enhancements
+=======================
+
+Submitting pull requests
+========================
+
+Style and usage guidelines
+**************************
+
+* :ref:`beagleboard-git-usage`
+* Git commit messages
+* :ref:`beagleboard-doc-style`
 
 .. toctree::
    :maxdepth: 1
+   :hidden:
 
    /intro/contribution/git-usage
    /intro/contribution/style