WIP: Setup BeagleConnect documenation flow

boards/beagleconnect/freedom/ch1-introduction.rst

+.. _beagleconnect-freedom-introduction:
+
+Introduction
+##############
+
+What is BeagleConnect™ Freedom?
+********************************
+
+BeagleConnect™ Freedom is based on a `TI Arm Cortex-M4 wireless-enabled microcontroller <https://www.ti.com/product/CC1352P7>`_ 
+and is the first available BeagleConnect™ solution. It implements:
+
+* BeagleConnect™ gateway device function for Sub-GHz 802.15.4 long-range wireless
+* BeagleConnect™ node device function for Bluetooth Low-Energy (BLE) and Sub-GHz 802.15.4 long range wireless
+* USB-based serial console and firmware updates
+* 2x `mikroBUS sockets <https://www.mikroe.com/mikrobus>`_ with BeagleConnect™ protocol support.
+
+.. image:: media/BeagleConnect-Freedom-C5-HandPhoto.jpg
+   :width: 600
+   :align: center
+   :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.
+
+What makes BeagleConnect™ new and different?
+==============================================
+
+Plug & Play approach
+--------------------
+
+BeagleConnect™ uses the collaboratively developed Linux kernel to contain the 
+intelligence required to speak to these devices (sensors, actuators, and 
+indicators), rather than relying on writing code on a microcontroller specific 
+to these devices. Some existing solutions rely on large libraries of 
+microcontroller code, but the integration of communications, maintenance of the
+library with a limited set of developer resources and other constraints to be 
+explained later make those other solutions less suitable for rapid prototyping 
+than BeagleConnect™.
+
+Linux presents these devices abstractly in ways that are self-descriptive. Add 
+an accelerometer to the system and you are automatically fed a stream of force 
+values in standard units. Add a temperature sensor and you get it back in 
+standard units again. Same for sensing magnetism, proximity, color, light, 
+frequency, orientation, or multitudes of other inputs. Indicators, such as LEDs
+and displays, are similarly abstracted with a few other kernel subsystems and 
+more advanced actuators with and without feedback control are in the process of
+being developed and standardized. In places where proper Linux kernel drivers 
+exist, no new specialized code needs to be created for the devices.
+
+.. important:: 
+    BeagleConnect™ solves IoT in a different and better way than any previous solution. For hundreds of devices, 
+    users won't have to write a single line of code to add them their systems. The automation code they do 
+    write can be extremely simple, done with graphical tools or in any language 
+    they want. Maintenance of the code is centralized in a small reusable set of 
+    microcontroller firmware and the Linux kernel, which is highly peer reviewed 
+    under a `highly-regarded governance model <https://wiki.p2pfoundation.net/Linux_-_Governance>`_.
+
+Reliable software update mechanism
+-----------------------------------
+
+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
+fixes an issue in either BeagleConnect™ firmware or the Linux kernel, you 
+benefit from the fixes. The source for BeagleConnect™ firmware is also 
+submitted to the `Zephyr Project <https://www.zephyrproject.org/>`_ upstream, 
+further increasing the user base. Additionally, we will maintain stable 
+branches of the software and provide mechanisms for updating firmware on 
+BeagleConnect™ hardware. With a single, relatively small firmware load, the 
+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 
+sensor or indicator with hundreds of devices available.
+
+Note: Currently, we have support in the Linux kernel for a bit over 100 Click 
+mikroBUS add-on boards from Mikroelektronika and are working with 
+Mikroelektronika on a updated version of the specification for these boards to 
+self-identify. Further, eventually the vast majority of over 800 currently 
+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 CC1352P7 <http://www.ti.com/product/CC1352P7>`_ multiprotocol and multi-band 
+Sub-1 GHz and 2.4-GHz wireless microcontroller (MCU). CC1352P7 includes a 48-MHz
+Arm® Cortex®-M4F processor, 704KB Flash, 256KB ROM, 8KB Cache SRAM, 144KB of 
+ultra-low leakage SRAM, and `Over-the-Air <https://en.wikipedia.org/wiki/Over-the-air_programming>`_ 
+upgrades (OTA).
+
+Fully customizable design
+--------------------------
+
+BeagleConnect™ utilizes `open source hardware <https://www.oshwa.org/definition/>`_ 
+and `open source software <https://en.wikipedia.org/wiki/Open-source_software>`_, 
+making it possible to optimize hardware and software implementations and 
+sourcing to meet end-product requirements. BeagleConnect™ is meant to enable 
+rapid-prototyping and not to necessarily satisfy any particular end-product’s 
+requirements, but with full considerations for go-to-market needs.
+
+Each BeagleBoard.org BeagleConnect™ solution will be:
+
+* Readily available for over 10 years,
+* Built with fully open source software with submissions to mainline Linux and 
+  Zephyr repositories to aide in support and porting,
+* Built with fully open source and non-restrictive hardware design including 
+  schematic, bill-of-materials, layout, and manufacturing files (with only the 
+  BeagleBoard.org logo removed due to licensing restrictions of our brand),
+* Built with parts where at least a compatible part is available from worldwide
+  distributors in any quantity,
+* Built with design and manufacturing partners able to help scale derivative
+  designs,
+* Based on a security model using public/private keypairs that can be replaced 
+  to secure your own network, and
+* Fully FCC/CE certified.
+

boards/beagleconnect/freedom/ch10-pictures.rst

+.. _beagleconnect-freedom-pictures:
+
+Pictures 
+#########
\ No newline at end of file

boards/beagleconnect/freedom/ch2-change-history.rst

+.. _beagleconnect-freedom-change-history:
+
+Change History
+###############
+
+.. note:: 
+    This section describes the change history of this document and board. 
+    Document changes are not always a result of a board change. A board 
+    change will always result in a document change.
+
+.. _beagleconnect-freedom-document-change-history:
+
+Document Changes
+******************
+
+.. _beagleconnect-freedom-board-changes:
+
+Board Changes
+**************

boards/beagleconnect/freedom/zephyr.rst → boards/beagleconnect/freedom/ch3-quick-start.rst

+.. _beagleconnect-freedom-quick-start:
+
+Quick Start Guide
+####################
+
+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
+=======================================
+.. 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 its 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.
+
+.. 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
+
+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
+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
+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
+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.
+
+.. 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,
+  UART, PWM, ADC, and GPIO with interrupts via Greybus
+
+BeagleConnect **gateway** device
+==================================
+
+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
+==============================
+
+Utilizes a BeagleConnect™ compatible interface and TODO
+
+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
+BeagleConnect™ node device designs.
+
+Greybus
+-------
+
+TODO
+
+#TODO: Find a place for the following notes:
+
+* 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
+  drivers are loaded on the host
+* Unsupported Click Boards connected are exposed via userspace drivers on the
+  host for development
+
+What’s different?
+*****************
+
+So, in summary, what is so different with this approach?
+
+* No microcontroller code development is required by users
+* Userspace drivers make rapid prototyping really easy
+* Kernel drivers makes the support code collaborative parts of the Linux kernel
+  , rather than cut-and-paste
+
 .. _beagleconnect-zephyr:
 
 BeagleConnect Freedom & Zephyr
-###############################
+******************************
 
 Develop for BeagleConnect Freedom with Zephyr
 **********************************************

boards/beagleconnect/freedom/ch4-detailed-overview.rst

+.. _beagleconnect-freedom-detailed-overview:
+
+Detailed overview
+##################
\ No newline at end of file

boards/beagleconnect/freedom/ch5-high-level-specifications.rst

+.. _beagleconnect-freedom-high-level-specifications:
+
+High-level specification
+#########################
\ No newline at end of file

boards/beagleconnect/freedom/ch6-detailed-hardware-design.rst

+.. _beagleconnect-freedom-detailed-hardware-design:
+
+Detailed hardware design
+#########################
\ No newline at end of file

boards/beagleconnect/freedom/ch7-connectors.rst

+.. _beagleconnect-freedom-connectors:
+
+Connectors 
+###########
\ No newline at end of file

boards/beagleconnect/freedom/ch8-support.rst

+.. _beagleconnect-freedom-support:
+
+Support
+########

boards/beagleconnect/freedom/ch9-mechanical.rst

+.. _beagleconnect-freedom-mechanical:
+
+Mechanical
+###########
\ No newline at end of file

boards/beagleconnect/freedom/index.rst

 .. _beagleconnect_freedom_home:
 
-BeagleConnect Freedom
+BeagleConnect™ Freedom
 ######################
 
 .. important::
 
-   Currently under development
+   This is a work in progress, for latest documentation please visit https://docs.beagleboard.org/latest/
 
-.. image:: media/image1.jpg
-   :width: 600
-   :align: center
-   :height: 400
-   :alt: BeagleConnect-Freedom-C5-HandPhoto
+.. image:: media/BeagleConnect-Freedom-C5-Boards.jpg
+  :align: center
+  :alt: BeagleConnect™ Freedom board
+  :height: 700
 
-The initial BeagleConnect™ Freedom production release will:
+.. grid:: 1 1 2 3
+   :margin: 4 4 0 0
+   :gutter: 4
 
-* Support at least 100 mikroBUS-based Click boards from Mikroelectronika
-* Work with Bluetooth Low Energy (BLE)-enabled Linux computers at 2.4GHz
-* Work with long-range sub-1GHz IEEE 802.15.4 wireless connections at 500 
-  meters with data rates of 1kbps, and
-* Work with a low-cost BeagleBoard.org Linux single-board computer (SBC) as a 
-  BeagleConnect™ gateway device and work with at least 10 other BeagleConnect™ 
-  node devices each supporting 2 add-on sensor, actuator or indicator devices.
+   .. grid-item-card::
+      :link: beagleconnect-freedom-introduction
+      :link-type: ref
 
-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.
+      **1. Introduction**
+      ^^^
 
-.. 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. 
+      .. image:: media/chapter-thumbnails/introduction.jpg
+         :align: center
+      
+      +++
 
-BeagleConnect™ Freedom
-**********************
+      Introduction to BeagleConnect™ Freedom.
 
-BeagleConnect™ Freedom is based on a `TI Arm Cortex-M4 wireless-enabled microcontroller <https://www.ti.com/product/CC1352P7>`_ 
-and is the first available BeagleConnect™ solution. It implements:
 
-* BeagleConnect™ gateway device function for Sub-GHz 802.15.4 long-range 
-  wireless
-* BeagleConnect™ node device function for Bluetooth Low-Energy (BLE) and 
-  Sub-GHz 802.15.4 long range wireless
-* USB-based serial console and firmware updates
-* 2x `mikroBUS sockets <https://www.mikroe.com/mikrobus>`_ with BeagleConnect™ 
-  protocol support
+   .. grid-item-card::
+      :link: beagleconnect-freedom-change-history
+      :link-type: ref
 
-#TODO: provide image of BeagleConnect™ Freedom in a case with a hand for size perspective
+      **2. Change History**
+      ^^^
 
-BeagleConnect™ Freedom beta kit
-*******************************
+      .. image:: media/chapter-thumbnails/change-history.jpg
+         :align: center
 
-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:
+      Hardware, Software, and Documentation change history.
 
-* 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>`_
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-quick-start
+      :link-type: ref
 
-To get started with this kit, see [demo-1].
+      **3. Quick start**
+      ^^^
 
+      .. image:: media/chapter-thumbnails/quick-start.jpg
+         :align: center
 
-What makes BeagleConnect™ new and different?
-********************************************
+      +++
 
-.. 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 
-indicators), rather than relying on writing code on a microcontroller specific 
-to these devices. Some existing solutions rely on large libraries of 
-microcontroller code, but the integration of communications, maintenance of the
-library with a limited set of developer resources and other constraints to be 
-explained later make those other solutions less suitable for rapid prototyping 
-than BeagleConnect™.
-
-Linux presents these devices abstractly in ways that are self-descriptive. Add 
-an accelerometer to the system and you are automatically fed a stream of force 
-values in standard units. Add a temperature sensor and you get it back in 
-standard units again. Same for sensing magnetism, proximity, color, light, 
-frequency, orientation, or multitudes of other inputs. Indicators, such as LEDs
-and displays, are similarly abstracted with a few other kernel subsystems and 
-more advanced actuators with and without feedback control are in the process of
-being developed and standardized. In places where proper Linux kernel drivers 
-exist, no new specialized code needs to be created for the devices.
-
-Important: *Bottom line*: For hundreds of devices, users won't have to write a 
-single line of code to add them their systems. The automation code they do 
-write can be extremely simple, done with graphical tools or in any language 
-they want. Maintenance of the code is centralized in a small reusable set of 
-microcontroller firmware and the Linux kernel, which is highly peer reviewed 
-under a `highly-regarded governance model <https://wiki.p2pfoundation.net/Linux_-_Governance>`_. 
-
-ongoing 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
-fixes an issue in either BeagleConnect™ firmware or the Linux kernel, you 
-benefit from the fixes. The source for BeagleConnect™ firmware is also 
-submitted to the `Zephyr Project <https://www.zephyrproject.org/>`_ upstream, 
-further increasing the user base. Additionally, we will maintain stable 
-branches of the software and provide mechanisms for updating firmware on 
-BeagleConnect™ hardware. With a single, relatively small firmware load, the 
-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 
-sensor or indicator with hundreds of devices available.
-
-Note: Currently, we have support in the Linux kernel for a bit over 100 Click 
-mikroBUS add-on boards from Mikroelektronika and are working with 
-Mikroelektronika on a updated version of the specification for these boards to 
-self-identify. Further, eventually the vast majority of over 800 currently 
-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 CC1352P7 <http://www.ti.com/product/CC1352P7>`_ multiprotocol and multi-band 
-Sub-1 GHz and 2.4-GHz wireless microcontroller (MCU). CC1352P7 includes a 48-MHz
-Arm® Cortex®-M4F processor, 704KB Flash, 256KB ROM, 8KB Cache SRAM, 144KB of 
-ultra-low leakage SRAM, and `Over-the-Air <https://en.wikipedia.org/wiki/Over-the-air_programming>`_ 
-upgrades (OTA).
-
-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>`_, 
-making it possible to optimize hardware and software implementations and 
-sourcing to meet end-product requirements. BeagleConnect™ is meant to enable 
-rapid-prototyping and not to necessarily satisfy any particular end-product’s 
-requirements, but with full considerations for go-to-market needs.
-
-Each BeagleBoard.org BeagleConnect™ solution will be:
-
-* Readily available for over 10 years,
-* Built with fully open source software with submissions to mainline Linux and 
-  Zephyr repositories to aide in support and porting,
-* Built with fully open source and non-restrictive hardware design including 
-  schematic, bill-of-materials, layout, and manufacturing files (with only the 
-  BeagleBoard.org logo removed due to licensing restrictions of our brand),
-* Built with parts where at least a compatible part is available from worldwide
-  distributors in any quantity,
-* Built with design and manufacturing partners able to help scale derivative
-  designs,
-* Based on a security model using public/private keypairs that can be replaced 
-  to secure your own network, and
-* Fully FCC/CE certified.
-
-Getting Started
-***************
-
-* :ref:`Typical BeagleConnect Freedom usage with a Linux host <beagleconnect-usage>`
-* :ref:`Programming BeagleConnect Freedom with Zephyr <beagleconnect-zephyr>`
+      Getting started guide.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-detailed-overview
+      :link-type: ref
+
+      **4. Detailed overview**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/detailed-overview.jpg
+         :align: center
+
+      +++
+
+      Detailed overview.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-high-level-specifications
+      :link-type: ref
+
+      **5. High level specification**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/specifications.jpg
+         :align: center
+
+      +++
+
+      High level specifications.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-detailed-hardware-design
+      :link-type: ref
+
+      **6. Detailed hardware design**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/hardware-design.jpg
+         :align: center
+
+      +++
+
+      Detailed hardware design.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-connectors
+      :link-type: ref
+
+      **7. Connectors**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/connectors.jpg
+         :align: center
+
+      +++
+
+      Connectors pinout diagrams and more.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-support
+      :link-type: ref
+
+      **8. Support**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/support-documents.jpg
+         :align: center
+
+      +++
+
+      User support document for easy development.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-mechanical
+      :link-type: ref
+
+      **9. Mechanical**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/mechanical-specifications.jpg
+         :align: center
+
+      +++
+
+      Mechanical dimensions.
+
+   .. grid-item-card:: 
+      :link: beagleconnect-freedom-pictures
+      :link-type: ref
+
+      **10. Pictures**
+      ^^^
+
+      .. image:: media/chapter-thumbnails/pictures.jpg
+         :align: center
+
+      +++
+
+      BeagleConnect™ Freedom board pictures.
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
-   /boards/beagleconnect/freedom/usage.rst
-   /boards/beagleconnect/freedom/zephyr.rst
+   /boards/beagleconnect/freedom/ch1-introduction.rst
+   /boards/beagleconnect/freedom/ch2-change-history.rst
+   /boards/beagleconnect/freedom/ch3-quick-start.rst
+   /boards/beagleconnect/freedom/ch4-detailed-overview.rst
+   /boards/beagleconnect/freedom/ch5-high-level-specifications.rst
+   /boards/beagleconnect/freedom/ch6-detailed-hardware-design.rst
+   /boards/beagleconnect/freedom/ch7-connectors.rst
+   /boards/beagleconnect/freedom/ch8-support.rst
+   /boards/beagleconnect/freedom/ch9-mechanical.rst
+   /boards/beagleconnect/freedom/ch10-pictures.rst
+