WIP reorganize

* List all boards in top-level ToC * Fix BeagleConnect headings and general clean-up

WIP reorganize
* List all boards in top-level ToC * Fix BeagleConnect headings and general clean-up
ef4f094b · Jason Kridner · 5e559903 · ef4f094b · ef4f094b · ef4f094b
Commit ef4f094b authored 2 years ago by Jason Kridner
--- a/boards/beagleboard/index.rst
+++ b/boards/beagleboard/index.rst
-BeagleBoard
+BeagleBoard (all)
 ###################

 BeagleBoard boards are low-cost, ARM-based development boards suitable for rapid prototyping and 

--- a/boards/beaglebone/index.rst
+++ b/boards/beaglebone/index.rst
-BeagleBone
+BeagleBone (all)
 ###################

 BeagleBone boards are intended to be bare-bones, with a balance of features to enable
@@ -19,14 +19,8 @@ with links to their latest PDF-formatted System Reference Manual and the latest
 included both here and in the downloadable beagleboard-docs.pdf linked on the bottom-left
 of your screen.

-* `BeagleBone (original) <https://git.beagleboard.org/beagleboard/beaglebone/-/blob/master/BeagleBone_SRM_A6_0_1.pdf>`_
-
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Boards
-
-   /boards/beaglebone/black/index
-   /boards/beaglebone/ai-64/index
-   /boards/beaglebone/blue/index
+* `BeagleBone (original) <https://git.beagleboard.org/beagleboard/beaglebone/-/blob/master/BeagleBone_SRM_A6_0_1.pdf>`__
+* `BeagleBone Black </boards/beaglebone/black/index.html>`__
+* `BeagleBone Blue </boards/beaglebone/blue/index.html>`__
+* `BeagleBone AI-64 </boards/beaglebone/ai-64/index.html>`__

--- a/boards/beagleconnect/freedom/index.rst
+++ b/boards/beagleconnect/freedom/index.rst
-BeagleConnect™ Freedom
+BeagleConnect Freedom
 ######################

 .. image:: media/image1.jpg
@@ -7,10 +7,6 @@ BeagleConnect™ Freedom
   :height: 400
   :alt: BeagleConnect-Freedom-C5-HandPhoto

-Important: BeagleConnect™ Freedom enables wirelessly adding new device nodes 
-and is targeted to cost initially around US$20 with a roadmap to variants as 
-low as US$1. 
-
 The initial BeagleConnect™ Freedom production release will:

 * Support at least 100 mikroBUS-based Click boards from Mikroelectronika
@@ -25,41 +21,14 @@ Future releases will be collaborated with the community, evolve dynamically,
 and contain additional functionality. The goal is to support over 500 add-on 
 devices within the first year after the initial release.

-BeagleConnect™ Freedom beta kit
-*******************************
-
-A small number of beta kits have been assembled with BeagleConnect™ Freedom 
-rev C5 boards, which is the version that should be taken to production.
-
-The kit includes:
-
-* 1x `Seeed BeagleBone® Green Gateway <https://wiki.seeedstudio.com/BeagleBone-Green-Gateway/>`_ (board, USB cable)
-* 3x BeagleConnect™ Freedom (board, attenna, USB cable)
-* 1x `Mikroelectronika Click ID Board <https://www.mikroe.com/unique-id-click>`_
-
-To get started with this kit, see [demo-1].
-
-
-BeagleConnect™ Mobile Gateway
-#############################
-
-This is a work-in-progress that will be released as the first integrated 
-BeagleConnect™ gateway. It is possible to assemble a gateway with any Linux 
-computer, but this computer will ship setup and ready to go.
-
-The gateway is built from:
-
-* BeagleBoard.org PocketBeagle,
-* BeagleConnect™ Freedom,
-* a cellular modem,
-* a USB WiFi dongle,
-* antennas, and
-* an enclosure.
+.. important::
+   BeagleConnect™ Freedom enables wirelessly adding new device nodes 
+   and is targeted to cost initially around US$20 with a roadmap to variants as 
+   low as US$1. 

-Architecture
-************
 BeagleConnect™ Freedom
 **********************
+
 BeagleConnect™ Freedom is based on the `TI CC1352 <https://www.ti.com/product/CC1352R>`_ 
 and is the first available BeagleConnect™ solution. It implements:

@@ -73,13 +42,30 @@ and is the first available BeagleConnect™ solution. It implements:

 #TODO: provide image of BeagleConnect™ Freedom in a case with a hand for size perspective

+BeagleConnect™ Freedom beta kit
+*******************************
+
+A small number of beta kits have been assembled with BeagleConnect™ Freedom 
+rev C5 boards, which is the version that should be taken to production.
+
+The kit includes:
+
+* 1x `Seeed BeagleBone® Green Gateway <https://wiki.seeedstudio.com/BeagleBone-Green-Gateway/>`_ (board, USB cable)
+* 3x BeagleConnect™ Freedom (board, attenna, USB cable)
+* 1x `Mikroelectronika Click ID Board <https://www.mikroe.com/unique-id-click>`_
+
+To get started with this kit, see [demo-1].
+
+
 What makes BeagleConnect™ new and different?
 ********************************************
-Important: BeagleConnect™ solves IoT in a different and better way than any 
-previous solution.
+
+.. important::
+  BeagleConnect™ solves IoT in a different and better way than any 
+  previous solution.

 The device interface software is already done
-*********************************************
+=============================================

 BeagleConnect™ uses the collaboratively developed Linux kernel to contain the 
 intelligence required to speak to these devices (sensors, actuators, and 
@@ -108,7 +94,7 @@ microcontroller firmware and the Linux kernel, which is highly peer reviewed
 under a `highly-regarded governance model <https://wiki.p2pfoundation.net/Linux_-_Governance>`_. 

 On-going maintenance
-********************
+====================

 Because there isn't code specific to any given network-of-devices configuration
 , we can all leverage the same software code base. This means that when someone
@@ -122,7 +108,7 @@ potential for bugs is kept low. With large user base, the potential for
 discovering and resolving bugs is high.

 Rapid prototyping without wiring
-********************************
+================================

 BeagleConnect™ utilizes the `mikroBUS standard <https://elinux.org/Mikrobus>`_.
 The mikroBUS standard interface is flexible enough for almost any typical 
@@ -136,7 +122,7 @@ available Click mikroBUS add-on boards will be supported as well as the
 hundreds of compliant boards developed every year. 

 Long-range, low-power wireless
-******************************
+==============================

 BeagleConnect™ Freedom wireless hardware is built around a 
 `TI CC1352 <http://www.ti.com/product/CC1352R>`_ multiprotocol and multi-band 
@@ -146,7 +132,7 @@ ultra-low leakage SRAM, and `Over-the-Air <https://en.wikipedia.org/wiki/Over-th
 upgrades (OTA).

 Full customization possible
-***************************
+===========================

 BeagleConnect™ utilizes `open source hardware <https://www.oshwa.org/definition/>`_ 
 and `open source software <https://en.wikipedia.org/wiki/Open-source_software>`_, 
@@ -171,9 +157,15 @@ Each BeagleBoard.org BeagleConnect™ solution will be:
  to secure your own network, and
 * Fully FCC/CE certified.

+Getting Started
+***************
+
+* `Typical usage with a Linux host </boards/beagleconnect/freedom/usage.html>`__
+* `Programming with Zephyr </boards/beagleconnect/freedom/zephyr.html>`__
+
 .. toctree::
   :maxdepth: 1
+   :hidden:

   usage.rst
   zephyr.rst
-
--- a/boards/beagleconnect/freedom/usage.rst
+++ b/boards/beagleconnect/freedom/usage.rst
 .. _beagleconnect-Usage:

-********************
-BeagleConnect™ Usage
-********************
+BeagleConnect Freedom Usage
+###########################

-
-
-This section describes the usage model we are developing. To use the current 
+This section describes the usage model we are developing. To use the current
 code in development, please refer to the [development] section.


-BeagleConnect™ wireless user experience
-#######################################
-
-Enable a Linux host with BeagleConnect™
+BeagleConnect wireless user experience
 ***************************************
+
+Enable a Linux host with BeagleConnect
+=======================================
 .. image:: media/ProvStep1.jpg
   :width: 600
   :align: center
   :height: 400
   :alt: ProvStep1

-Log into a host system running Linux that is BeagleConnect™ enabled. Enable a 
-Linux host with BeagleConnect™ by plugging a **BeagleConnect™ gateway device** 
-into it’s USB port. You’ll also want to have a **BeagleConnect™ node device** 
+Log into a host system running Linux that is BeagleConnect™ enabled. Enable a
+Linux host with BeagleConnect™ by plugging a **BeagleConnect™ gateway device**
+into it’s USB port. You’ll also want to have a **BeagleConnect™ node device**
 with a sensor, actuator or indicator device connected.

-Note: BeagleConnect™ Freedom can act as either a BeagleConnect™ gateway device 
-or a BeagleConnect™ node device. 
+.. note::
+  BeagleConnect™ Freedom can act as either a BeagleConnect™ gateway device
+  or a BeagleConnect™ node device.

-Important: The Linux host will need to run the BeagleConnect™ management 
-software, most of which is incorporated into the Linux kernel. Support will be 
-provided for BeagleBoard and BeagleBone boards, x86 hosts, and Raspberry Pi. 
+.. important::
+  The Linux host will need to run the BeagleConnect™ management
+  software, most of which is incorporated into the Linux kernel. Support will be
+  provided for BeagleBoard and BeagleBone boards, x86 hosts, and Raspberry Pi.

-TODO: Clean up images
+#TODO#: Clean up images

 Connect host and device
-***********************
+=======================
+
 .. image:: media/ProvStep2.jpg
   :width: 600
   :align: center
   :height: 400
   :alt: ProvStep2
-Initiate a connection between the host and devices by pressing the discovery 
+
+Initiate a connection between the host and devices by pressing the discovery
 button(s).

 Device data shows up as files
-*****************************
+=============================
+
 .. image:: media/ProvStep3.jpg
   :width: 600
   :align: center
   :height: 400
   :alt: ProvStep3
-New streams of self-describing data show up on the host system using native 
+
+New streams of self-describing data show up on the host system using native
 device drivers.

-High-level applications, like Node-RED, can directly read/write these 
-high-level data streams (including data-type information) to Internet-based 
-`MQTT <https://mqtt.org/>`_ brokers, live dashboards, or other logical 
-operations without requiring any sensor-specific coding. Business logic can be 
-applied using simple if-this-then-that style operations or be made as complex 
+High-level applications, like Node-RED, can directly read/write these
+high-level data streams (including data-type information) to Internet-based
+`MQTT <https://mqtt.org/>`_ brokers, live dashboards, or other logical
+operations without requiring any sensor-specific coding. Business logic can be
+applied using simple if-this-then-that style operations or be made as complex
 as desired using virtually any programming language or environment.

 Components
-##########
-BeagleConnect™ enabled host Linux computer, possibly single-board computer 
-(SBC), with BeagleConnect™ management software and BeagleConnect™ gateway 
-function. BeagleConnect™ gateway function can be provided by a BeagleConnect™ 
-compatible interface or by connecting a BeagleConnect™ gateway device over USB.
+**********
+
+BeagleConnect™ enabled host Linux computer, possibly single-board computer
+(SBC), with BeagleConnect™ management software and BeagleConnect™ gateway
+function. BeagleConnect™ gateway function can be provided by a BeagleConnect™
+compatible interface or by connecting a BeagleConnect™ **gateway** device over USB.

-Note: If the Linux host has BLE, the BeagleConnect™ is optional for short 
-distances
+.. note::
+  If the Linux host has BLE, the BeagleConnect™ **gateway** is optional for short
+  distances

 BeagleConnect™ Freedom Board, case, and wireless MCU with Zephyr based firmware
-for acting as either a BeagleConnect™ gateway device or BeagleConnect™ node 
-device. 
-* In BeagleConnect™ gateway device mode: Provides long-range, low-power
-  wireless communications, Connects with the host via USB and an associated 
-  Linux kernel driver, and is powered by the USB connector. 
-* In BeagleConnect™ node device mode: Powered by a battery or USB connector 
-  Provides 2 mikroBUS connectors for connecting any of hundreds of `Click Board <https://bbb.io/click>`_ 
-  mikroBUS add-on devices Provides new Linux host controllers for SPI, I2C, 
+for acting as either a BeagleConnect™ gateway device or BeagleConnect™ node
+device.
+
+* In BeagleConnect™ **gateway** device mode: Provides long-range, low-power
+  wireless communications, Connects with the host via USB and an associated
+  Linux kernel driver, and is powered by the USB connector.
+* In BeagleConnect™ **node** device mode: Powered by a battery or USB connector
+  Provides 2 mikroBUS connectors for connecting any of hundreds of `Click Board <https://bbb.io/click>`_
+  mikroBUS add-on devices Provides new Linux host controllers for SPI, I2C,
  UART, PWM, ADC, and GPIO with interrupts via Greybus

-**BeagleConnect™ gateway device**
+BeagleConnect **gateway** device
+==================================

-Provides a BeagleConnect™ compatible interface to a host. This could be a 
+Provides a BeagleConnect™ compatible interface to a host. This could be a
 built-in interface device or one connected over USB. BeagleConnect™ Freedom can
 provide this function.

-**BeagleConnect™ node device**
+BeagleConnect **node** device
+==============================

 Utilizes a BeagleConnect™ compatible interface and TODO

-**BeagleConnect™ compatible interface**
+BeagleConnect compatible interface
+==================================

 Immediate plans are to support Bluetooth Low Energy (BLE), 2.4GHz IEEE 802.15.4
-, and Sub-GHz IEEE 802.15.4 wireless interfaces. A built-in BLE interface is 
-suitable for this at short range, whereas IEEE 802.15.4 is typically 
-significantly better at long ranges. Other wired interfaces, such as CAN and 
-RS-485, are being considered for future BeagleConnect™ gateway device and 
+, and Sub-GHz IEEE 802.15.4 wireless interfaces. A built-in BLE interface is
+suitable for this at short range, whereas IEEE 802.15.4 is typically
+significantly better at long ranges. Other wired interfaces, such as CAN and
+RS-485, are being considered for future BeagleConnect™ gateway device and
 BeagleConnect™ node device designs.

-**Greybus**
+Greybus
+-------

 TODO

 #TODO: Find a place for the following notes:

-* The device interfaces get exposed to the host via Greybus BRIDGED_PHY 
+* The device interfaces get exposed to the host via Greybus BRIDGED_PHY
  protocol
-* The I2C bus is probed for a an identifier EEPROM and appropriate device 
+* The I2C bus is probed for a an identifier EEPROM and appropriate device
  drivers are loaded on the host
-* Unsupported Click Boards connected are exposed via userspace drivers on the 
+* Unsupported Click Boards connected are exposed via userspace drivers on the
  host for development

-What’s different
-################
+What’s different?
+*****************

 So, in summary, what is so different with this approach?


--- a/boards/beagleconnect/freedom/zephyr.rst
+++ b/boards/beagleconnect/freedom/zephyr.rst
 .. _beagleconnect-connectivity:

-*******************************
-BeagleConnect™ Freedom & Zephyr
-*******************************
+BeagleConnect Freedom & Zephyr
+###############################

-Develop for BeagleConnect™ Freedom with Zephyr
-##############################################
+Develop for BeagleConnect Freedom with Zephyr
+**********************************************

 Developing directly in Zephyr will not be ultimately required for end-users 
 who won't touch the firmware running on BeagleConnect™ Freedom and will instead
@@ -15,7 +14,7 @@ source design. If you are one of those people, this is a good place to get
 started.

 Equipment to begin development
-******************************
+==============================

 There are many options, but let's get started with one recommended set for the beta users.

@@ -55,7 +54,7 @@ Optional


 Install the latest software image for BeagleBone Green Gateway
-**************************************************************
+==============================================================

 Download and install the Debian Linux operating system image for the Seeed 
 BeagleBone® Green Gateway host.
@@ -75,7 +74,7 @@ BeagleBone® Green Gateway host.
 #TODO: describe how to know it is working

 Log into BeagleBone Green Gateway
-*********************************
+=================================

 These instructions assume an x86_64 computer runing Ubuntu 20.04.3 LTS, but any
 computer can be used to connect to your BeagleBone Green Gateway.
@@ -128,7 +127,7 @@ establishment procedure easy.
 TODO: Simplify and elaborate on this section, add boot session debugging walkthrough

 Install Zephyr development tools on BeagleBone Green Gateway
-************************************************************
+============================================================

 #. Update the system.
    .. code-block:: bash
@@ -189,7 +188,7 @@ Install Zephyr development tools on BeagleBone Green Gateway
        source $HOME/.bashrc
    
 Build applications for BeagleConnect Freedom on BeagleBone Green Gateway
-************************************************************************
+========================================================================

 Now you can build various Zephyr applications

@@ -226,7 +225,7 @@ Now you can build various Zephyr applications


 Flash applications to BeagleConnect Freedom from BeagleBone Green Gateway
-*************************************************************************
+=========================================================================

 And then you can flash the BeagleConnect Freedom boards over USB

@@ -241,6 +240,6 @@ And then you can flash the BeagleConnect Freedom boards over USB
        cc2538-bsl.py build/blinky

 Debug applications over the serial terminal
-*******************************************
+===========================================

-#TODO
+#TODO#
--- a/boards/beagleconnect/technology/index.rst
+++ b/boards/beagleconnect/technology/index.rst
 .. _beagleconnect-overview:

-BeagleConnect Overview
-#######################
+BeagleConnect Technology
+########################

-This is the deep-dive introduction to BeagleConnect technology and software
+This is the deep-dive introduction to BeagleConnect™ technology and software
 architecture.

 .. note:: 

--- a/index.rst
+++ b/index.rst
@@ -48,9 +48,14 @@ from source using appropriate design tools.
   :hidden:
   :caption: Boards

-   /boards/beaglebone/black/index
   /boards/beaglebone/ai-64/index
-   more... </boards/index.rst>
+   /boards/beaglebone/black/index
+   /boards/beaglebone/blue/index
+   /boards/beaglebone/index
+   /boards/capes/index
+   /boards/pocketbeagle/original/index
+   /boards/beagleconnect/freedom/index
+   /boards/beagleboard/index


 Projects
@@ -65,7 +70,7 @@ developers. Some developers choose to host documentation for their projects `her
   :caption: Projects

   /projects/simppru/index
-   more... </projects/index.rst>
+   /boards/beagleconnect/technology/index

 Books
 *****

--- a/projects/index.rst
+++ b/projects/index.rst
@@ -6,5 +6,5 @@ This is a collection of reasonably well-supported projects useful to Beagle deve
 .. toctree::
   :maxdepth: 1

-   simppru/index.rst
-
+   /projects/simppru/index.rst
+   /boards/beagleconnect/technology/index.rst