Forum | Documentation | Website | Blog

Skip to content
Snippets Groups Projects
Commit 7912e911 authored by Jason Kridner's avatar Jason Kridner
Browse files

Redo the introduction

parent b9e26d3a
No related merge requests found
...@@ -10,8 +10,7 @@ BeagleBoard Docs ...@@ -10,8 +10,7 @@ BeagleBoard Docs
.. toctree:: .. toctree::
intro/blinkLED intro/index
intro/index.rst
boards/beagleplay/index boards/beagleplay/index
boards/beaglebone/ai-64/index boards/beaglebone/ai-64/index
boards/beaglebone/ai/index boards/beaglebone/ai/index
......
...@@ -7,9 +7,7 @@ BeagleBoard Documentation ...@@ -7,9 +7,7 @@ BeagleBoard Documentation
############################ ############################
Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__. Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__.
If you are looking for help with your Beagle open-hardware development platform, you've found the right place!
Official documentation releases are provided at https://docs.beagle.cc (cached with local proxies) and
https://docs.beagleboard.org (non-cached, without proxies).
.. note:: .. note::
The BeagleBoard.org Foundation is a US-based 501(c)3 non-profit organization providing open hardware The BeagleBoard.org Foundation is a US-based 501(c)3 non-profit organization providing open hardware
...@@ -20,21 +18,26 @@ https://docs.beagleboard.org (non-cached, without proxies). ...@@ -20,21 +18,26 @@ https://docs.beagleboard.org (non-cached, without proxies).
Introduction Introduction
************ ************
Get started engaging the BeagleBoard.org developer community by reading our :ref:`introduction` page. Get started quickly on our Linux-enabled boards with :ref:`blinkLED`, follow-up with articles in :ref:`intro_beagle-101`, and reach out
via resources on our :ref:`support` page as needed to resolve issues
and engage with the developer community. Don't forget that this is an open-source project! Your contributions are welcome.
Learn about how to contribute to the BeagleBoard documentation project and any of the many open-source Beagle
projects ongoing on our :ref:`contribution` page.
* Read about how to get started and get help on our :ref:`support` page. * Get started quickly at :ref:`blinkLED`.
* Learn how to contribute to the project on our :ref:`contribution` page. * Go a bit deaper at :ref:`intro_beagle-101`.
* Read the book at :ref:`bone-cook-book-home`.
* Get help from the community at :ref:`support`.
* Learn how to contribute to the project at :ref:`contribution`..
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
:hidden: :hidden:
:caption: Introduction :caption: Introduction
/intro/blinkLED
/intro/support/index
/intro/beagle101/index /intro/beagle101/index
/intro/support/index
/intro/contribution/index /intro/contribution/index
CONTRIB
Boards Boards
......
File moved
.. _intro_beagle-101: .. _intro_beagle-101:
Beagle 101 An Introduction to Beagles
########### ##########################
.. note:: Linux-enabled boards
This page is under construction. Most of the information here is drastically out of date. ********************
This is a collection of articles to aide in quickly understanding how to make use of Beagles running Linux. Most Beagles have on-board flash preconfigured to run Linux. These resources will get you started quickly.
Most of the useful information has moved to :ref:`bone-cook-book-home`, but some articles
are being built here from a different perspective.
Articles under construction or to be imported and updated: * Get started at :ref:`blinkLED`.
* Learn to reset a board back to factory defaults and dive a bit deeper into the IDE at :ref:`beagleboard-getting-started`.
* Learn a bit about Linux at :ref:`intro-linux`.
* Learn about accessories at :ref:`accessories-home`
* Learn about using 3rd party I2C add-on boards at :ref:`qwiic_stemma_grove_addons`.
* Learn about using mikroBUS add-on boards at :ref:`beagleplay-mikrobus`.
* Learn about using Cape add-on boards at :ref:`capes`.
* Read :ref:`bone-cook-book-home`.
* Read :ref:`pru-cookbook-home`.
* Find more books at https://www.beagleboard.org/books.
* :ref:`qwiic_stemma_grove_addons` Zephyr-enabled boards
* https://beagleboard.github.io/bone101/Support/bone101/ *********************
Our Zephyr-enabled boards ship with a build of Micropython and, in the future, will also
ship with a BeagleConnect Greybus node service for quick, transparent access from any BeagleConnect
Greybus host enabled system.
* See :ref:`beagleconnect-freedom-using-micropython` to get started quickly.
* See :ref:`beagleconnect-freedom-using-zephyr` to learn to setup the Zephyr SDK.
* See :ref:`beagleconnect-overview` to learn about BeagleConnect Greybus.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
:hidden: :hidden:
/intro/beagle101/qwiic-stemma-grove-addons.rst blinkLED
linux
qwiic-stemma-grove-addons
.. todo::
Make sure we have everything critical from https://beagleboard.github.io/bone101/Support/bone101/
.. _intro_linux:
An Introduction to Linux
########################
This article seeks to give you some quick exploration of Linux. For a deeper training,
scroll down to :ref:`embedded-linux-training`.
Linux is designed to make the details of the hardware it is running on not matter so much
to users. It gives you a *somewhat* common experience on any hardware.
It also goes a bit further, providing some description of the harware as part of the running
"file system".
Typical Command-line Utilities
******************************
Most of what a new user experiences with Linux is the command-line.
.. table::
+=========+================================+=========+====================================+
| command | function | command | function |
+=========+================================+=========+====================================+
| pwd | *show current directory* | echo | *print/dump value* |
+---------+--------------------------------+---------+------------------------------------+
| cd | *change current directory* | env | *dump environment variables* |
+---------+--------------------------------+---------+------------------------------------+
| ls | *list directory contents* | export | *set environment variable* |
+---------+--------------------------------+---------+------------------------------------+
| chmod | *change file permissions* | history | *dump command history* |
+---------+--------------------------------+---------+------------------------------------+
| cp | *copy files* | man | *get help on command* |
+---------+--------------------------------+---------+------------------------------------+
| mv | *move files* | apropos | *show list of man pages* |
+---------+--------------------------------+---------+------------------------------------+
| rm | *remove files* | find | *search for files* |
+---------+--------------------------------+---------+------------------------------------+
| mkdir | *make directory* | tar | *create/extract file archives* |
+---------+--------------------------------+---------+------------------------------------+
| rmdir | *remove directory* | gzip | *compress a file* |
+---------+--------------------------------+---------+------------------------------------+
| cat | *dump file contents* | gunzip | *decompress a file* |
+---------+--------------------------------+---------+------------------------------------+
| less | *progressively dump file* | du | *show disk usage* |
+---------+--------------------------------+---------+------------------------------------+
| vi | *edit file (complex)* | df | *show disk free space* |
+---------+--------------------------------+---------+------------------------------------+
| nano | *edit file (simple)* | mount | *mount disks* |
+---------+--------------------------------+---------+------------------------------------+
| head | *trim dump to top* | tee | *write dump to file in parallel* |
+---------+--------------------------------+---------+------------------------------------+
| tail | *trim dump to bottom* | hexdump | *readable binary dumps* |
+---------+--------------------------------+---------+------------------------------------+
Kernel.org Documentation
************************
See https://www.kernel.org/doc.
Linux Standard Base
*******************
See https://refspecs.linuxfoundation.org/lsb.shtml.
.. shell-session::
$ lsb_release -a
Filesystem Hierarchy Standard
*****************************
See https://www.pathname.com/fhs/
Kernel Application Binary Interface
***********************************
See https://www.kernel.org/doc/Documentation/ABI/.
Busybox
*******
Even though large distros like Debian and Ubuntu do not make extensive use of `busybox`, it is still very useful to
learn
See http://www.busybox.net/.
.. _embedded-linux-training:
Training
********
To continue learning more about Linux, we highly recommend https://bootlin.com/training/embedded-linux/.
...@@ -53,12 +53,6 @@ the skills required for Linux contributions in the :ref:`beagleboard-linux-upstr ...@@ -53,12 +53,6 @@ the skills required for Linux contributions in the :ref:`beagleboard-linux-upstr
The most useful thing to know is how to ask smart questions. Read about this in the :ref:`intro-getting-support` section. If you ask The most useful thing to know is how to ask smart questions. Read about this in the :ref:`intro-getting-support` section. If you ask
smart questions on the issue trackers and forum, you'll be doing a lot to help us improve the designs and documentation. smart questions on the issue trackers and forum, you'll be doing a lot to help us improve the designs and documentation.
.. toctree::
:maxdepth: 1
:hidden:
/intro/contribution/linux-upstream
How can I contribute? How can I contribute?
********************* *********************
...@@ -66,6 +60,8 @@ The most obvious way to contribute is using the `git.beagleboard.org Gitlab serv ...@@ -66,6 +60,8 @@ The most obvious way to contribute is using the `git.beagleboard.org Gitlab serv
bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware bugs, suggest enhancements and providing merge requests, also called pull requests, the provide fixes to software, hardware
designs and documentation. designs and documentation.
Reading the `help guide <https://git.beagleboard.org/help/>`_ is a great way to get started using our Gitlab server.
This documentation has a number of ``todo`` items where help is needed that can be searched in the source. This documentation has a number of ``todo`` items where help is needed that can be searched in the source.
.. todolist:: .. todolist::
...@@ -73,32 +69,47 @@ This documentation has a number of ``todo`` items where help is needed that can ...@@ -73,32 +69,47 @@ This documentation has a number of ``todo`` items where help is needed that can
Reporting bugs Reporting bugs
=============== ===============
.. todo:: Start by reading the `Gitlab Issues help page <https://git.beagleboard.org/help/user/project/issues/index.md>`_.
Describe where and how to report issues on git.beagleboard.org
Please request an account and report any issues on the appropriate project issue tracker at https://git.beagleboard.org.
Report issues on the software images at https://git.beagleboard.org/explore/topics/distros.
Report issues on the hardware at https://git.beagleboard.org/explore/projects/topics/boards.
Suggesting enhancements Suggesting enhancements
======================= =======================
.. todo:: An issue doesn't have to be something wrong, it can just be about making something better. If in doubt how to make
Describe how to introduct ideas on forum.beagleboard.org and git.beagleboard.org a productive suggestion, hop on the forum and live chat groups to see what other people say. Check the current
ideas that are already out there and give us your idea. Try to be constructive in your suggestion. We are a primarily
a volunteer community looking to make your experience better, as those that follow you, and your suggestion could be
key in that endeavor.
Where available, use the "enhancement" `label <https://git.beagleboard.org/help/user/project/labels.md>`_ on your issue
to make sure we know you are looking for a future improvement, not reporting something critically wrong.
Submitting merge requests Submitting merge requests
========================= =========================
.. todo:: If you want to contribute to a project, the most practical way is with a
Describe how to introduct ideas on forum.beagleboard.org and git.beagleboard.org `merge request <https://git.beagleboard.org/help/user/project/merge_requests/index.html>`_. Start
by `creating a fork <https://git.beagleboard.org/help/user/project/repository/forking_workflow.html>`_, which
is your own copy of the project you can feel free to edit how you see fit. When ready,
`create a merge request <https://git.beagleboard.org/help/user/project/merge_requests/creating_merge_requests.html>`_ and
we'll review your work and give comments back to you. If suitable, we'll update the code to include your contribution!
Style and usage guidelines A bit more detailed suggestions can be found in the articles linked below.
**************************
* :ref:`beagleboard-git-usage` Articles on contribution
* Git commit messages **************************
* :ref:`beagleboard-doc-style`
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
:hidden:
/intro/contribution/git-usage /CONTRIBUTING
/intro/contribution/style git-usage
/intro/contribution/rst-cheat-sheet style
rst-cheat-sheet
linux-upstream
/CONTRIB
..
This adds content to the print version that is in /index.rst, but skipped in /index-tex.rst
.. _introduction: .. _introduction:
Introduction Introduction
############# #############
Welcome to the BeagleBoard documentation project. If you are looking for help with your Beagle Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__.
open-hardware development platform, you've found the right place! If you are looking for help with your Beagle open-hardware development platform, you've found the right place!
.. important:: .. important::
...@@ -18,7 +22,8 @@ open-hardware development platform, you've found the right place! ...@@ -18,7 +22,8 @@ open-hardware development platform, you've found the right place!
* https://docs.beagleboard.io (straight from `docs repo <https://git.beagleboard.org/docs/docs.beagleboard.io>`_) * https://docs.beagleboard.io (straight from `docs repo <https://git.beagleboard.org/docs/docs.beagleboard.io>`_)
Please check out our :ref:`support` page to find out how to get started, resolve issues, Get started quickly on our Linux-enabled boards with :ref:`blinkLED`, follow-up with articles in :ref:`intro_beagle-101`, and reach out
via resources on our :ref:`support` page as needed to resolve issues
and engage with the developer community. Don't forget that this is an open-source project! Your contributions are welcome. and engage with the developer community. Don't forget that this is an open-source project! Your contributions are welcome.
Learn about how to contribute to the BeagleBoard documentation project and any of the many open-source Beagle Learn about how to contribute to the BeagleBoard documentation project and any of the many open-source Beagle
projects ongoing on our :ref:`contribution` page. projects ongoing on our :ref:`contribution` page.
...@@ -27,12 +32,12 @@ projects ongoing on our :ref:`contribution` page. ...@@ -27,12 +32,12 @@ projects ongoing on our :ref:`contribution` page.
Make sure you thoroughly read and agree with our :ref:`boards-terms-and-conditions` which covers Make sure you thoroughly read and agree with our :ref:`boards-terms-and-conditions` which covers
warnings, restrictions, disclaimers, and warranty for all of our boards. Use of either the boards or warnings, restrictions, disclaimers, and warranty for all of our boards. Use of either the boards or
the design materials constitutes agreement to the T&C including any modifications done to the design materials constitutes agreement to the T&C including any modifications done to
the hardware or software solutions provided by beagleboard.org foundation. the hardware or software solutions provided by the BeagleBoard.org Foundation.
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
/intro/support/index
/intro/beagle101/index /intro/beagle101/index
/intro/support/index
/intro/contribution/index /intro/contribution/index
...@@ -3,30 +3,26 @@ ...@@ -3,30 +3,26 @@
Support Support
######### #########
Getting started First, read the manual
*************** **********************
The starting experience for all Beagles has been made to be as
consistent as is possible. For any of the Beagle Linux-based open
hardware computers, visit :ref:`beagleboard-getting-started`.
.. toctree:: Before reaching out for support, make sure you've gone through the process of resetting your
:maxdepth: 2 board back to factory conditions.
/intro/support/getting-started For any of the Beagle Linux-based open hardware computers, visit :ref:`beagleboard-getting-started`.
.. _intro-getting-support: .. _intro-getting-support:
Getting support Getting support
*************** ***************
BeagleBoard.org products and `open BeagleBoard.org products are `open
hardware <https://www.oshwa.org/definition/>`_ designs are supported hardware <https://www.oshwa.org/definition/>`_ designs supported
via the on-line community resources. We are very confident in our via the on-line community resources. We are very confident in our
community’s ability to provide useful answers in a timely manner. If you community’s ability to provide useful answers in a timely manner. If you
don’t get a productive response within 24 hours, please escalate issues don’t get a productive response within 24 hours, please escalate issues
to Jason Kridner (contact info available on the `About to Jason Kridner (contact info available on the `About
Page <https://beagleboard.org/about>`_). In case it is needed, Jason Page <https://www.beagleboard.org/about>`_). In case it is needed, Jason
will help escalate issues to suppliers, manufacturers or others. Be sure will help escalate issues to suppliers, manufacturers or others. Be sure
to provide a link to your questions on the `community to provide a link to your questions on the `community
forums <https://forum.beagleboard.org>`_ as answers will be provided forums <https://forum.beagleboard.org>`_ as answers will be provided
...@@ -71,14 +67,17 @@ Community resources ...@@ -71,14 +67,17 @@ Community resources
=================== ===================
Please execute the board diagnostics, review the hardware documentation, Please execute the board diagnostics, review the hardware documentation,
and consult the mailing list and IRC channel for support. and consult the form and live chat for support.
BeagleBoard.org is a “community” project with free support only given to BeagleBoard.org is a “community” project with free support only given to
those who are willing to discussing their issues openly for the benefit those who are willing to discuss their issues openly for the benefit
of the entire community. of the entire community.
- `Frequently Asked Questions <https://forum.beagleboard.org/c/faq>`_ - `Frequently Asked Questions <https://forum.beagleboard.org/c/faq>`_
- `Mailing List <https://forum.beagleboard.org>`_ - `Forum <https://forum.beagleboard.org>`_
- `Live Chat <https://beagleboard.org/chat>`_ - `Live Chat <https://www.beagleboard.org/discord>`_
If you need to escalate an issue already reported over 24 hours ago on the `forum <https://forum.beagleboard.org>`_, please
schedule a meeting to discuss it with Jason via contact information near the bottom of the `about page <https://www.beagleboard.org/about>`_.
.. _consulting-resources: .. _consulting-resources:
...@@ -103,21 +102,4 @@ form: ...@@ -103,21 +102,4 @@ form:
Understanding Your Beagle Understanding Your Beagle
************************* *************************
- :ref:`intro_beagle-101` Spend some time getting to know your Beagle via :ref:`intro_beagle-101`
- `Hardware <https://beagleboard.org/Support/Hardware+Support>`_
- `Software <https://beagleboard.org/Support/Software+Support>`_
- :ref:`books-home`
- :ref:`pru-cookbook-home`
- :ref:`bone-cook-book-home`
- `Exploring BeagleBone <https://beagleboard.org/ebb>`_
- `Bad to the Bone <https://beagleboard.org/bad-to-the-bone>`_
Working with Cape Add-on Boards
*******************************
- :ref:`capes`
- :ref:`beaglebone-cape-interface-spec`
- :ref:`accessories-home`
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment