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
Branches
Tags
3 merge requests!72Cleanup AI-64,!71v1.0 release updates,!69Reduce librobotcontrol for now and cleanup each board intro
Hide whitespace changes
Inline Side-by-side
index-tex.rst
+ 1
− 2
View file @ 7912e911
......@@ -10,8 +10,7 @@ BeagleBoard Docs
.. toctree::
intro/blinkLED
intro/index.rst
intro/index
boards/beagleplay/index
boards/beaglebone/ai-64/index
boards/beaglebone/ai/index
......
index.rst
+ 12
− 9
View file @ 7912e911
......@@ -7,9 +7,7 @@ BeagleBoard Documentation
############################
Welcome to the `BeagleBoard project documentation <https://git.beagleboard.org/docs/docs.beagleboard.io>`__.
Official documentation releases are provided at https://docs.beagle.cc (cached with local proxies) and
https://docs.beagleboard.org (non-cached, without proxies).
If you are looking for help with your Beagle open-hardware development platform, you've found the right place!
.. note::
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).
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.
* Learn how to contribute to the project on our :ref:`contribution` page.
* Get started quickly at :ref:`blinkLED`.
* 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::
:maxdepth: 2
:hidden:
:caption: Introduction
/intro/blinkLED
/intro/support/index
/intro/beagle101/index
/intro/support/index
/intro/contribution/index
CONTRIB
Boards
......
intro/blinkLED.rst → intro/beagle101/blinkLED.rst
+ 0
− 0
View file @ 7912e911
File moved
intro/beagle101/index.rst
+ 31
− 11
View file @ 7912e911
.. _intro_beagle-101:
Beagle 101
###########
An Introduction to Beagles
##########################
.. note::
This page is under construction. Most of the information here is drastically out of date.
Linux-enabled boards
********************
This is a collection of articles to aide in quickly understanding how to make use of Beagles running Linux.
Most of the useful information has moved to :ref:`bone-cook-book-home`, but some articles
are being built here from a different perspective.
Most Beagles have on-board flash preconfigured to run Linux. These resources will get you started quickly.
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`
* https://beagleboard.github.io/bone101/Support/bone101/
Zephyr-enabled boards
*********************
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::
:maxdepth: 1
: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/beagle101/linux.rst 0 → 100644
+ 93
− 0
View file @ 7912e911
.. _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/.
intro/contribution/index.rst
+ 32
− 21
View file @ 7912e911
......@@ -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
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?
*********************
......@@ -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
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.
.. todolist::
......@@ -73,32 +69,47 @@ This documentation has a number of ``todo`` items where help is needed that can
Reporting bugs
===============
.. todo::
Describe where and how to report issues on git.beagleboard.org
Start by reading the `Gitlab Issues help page <https://git.beagleboard.org/help/user/project/issues/index.md>`_.
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
=======================
.. todo::
Describe how to introduct ideas on forum.beagleboard.org and git.beagleboard.org
An issue doesn't have to be something wrong, it can just be about making something better. If in doubt how to make
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
=========================
.. todo::
Describe how to introduct ideas on forum.beagleboard.org and git.beagleboard.org
If you want to contribute to a project, the most practical way is with a
`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`
* Git commit messages
* :ref:`beagleboard-doc-style`
Articles on contribution
**************************
.. toctree::
:maxdepth: 1
:hidden:
/intro/contribution/git-usage
/intro/contribution/style
/intro/contribution/rst-cheat-sheet
/CONTRIBUTING
git-usage
style
rst-cheat-sheet
linux-upstream
/CONTRIB
intro/index.rst
+ 10
− 5
View file @ 7912e911
..
This adds content to the print version that is in /index.rst, but skipped in /index-tex.rst
.. _introduction:
Introduction
#############
Welcome to the BeagleBoard documentation project. If you are looking for help with your Beagle
open-hardware development platform, you've found the right place!
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!
.. important::
......@@ -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>`_)
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.
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.
......@@ -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
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 hardware or software solutions provided by beagleboard.org foundation.
the hardware or software solutions provided by the BeagleBoard.org Foundation.
.. toctree::
:maxdepth: 2
/intro/support/index
/intro/beagle101/index
/intro/support/index
/intro/contribution/index
intro/support/index.rst
+ 16
− 34
View file @ 7912e911
......@@ -3,30 +3,26 @@
Support
#########
Getting started
***************
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`.
First, read the manual
**********************
.. toctree::
:maxdepth: 2
Before reaching out for support, make sure you've gone through the process of resetting your
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:
Getting support
***************
BeagleBoard.org products and `open
hardware <https://www.oshwa.org/definition/>`_ designs are supported
BeagleBoard.org products are `open
hardware <https://www.oshwa.org/definition/>`_ designs supported
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
don’t get a productive response within 24 hours, please escalate issues
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
to provide a link to your questions on the `community
forums <https://forum.beagleboard.org>`_ as answers will be provided
......@@ -71,14 +67,17 @@ Community resources
===================
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
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.
- `Frequently Asked Questions <https://forum.beagleboard.org/c/faq>`_
- `Mailing List <https://forum.beagleboard.org>`_
- `Live Chat <https://beagleboard.org/chat>`_
- `Forum <https://forum.beagleboard.org>`_
- `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:
......@@ -103,21 +102,4 @@ form:
Understanding Your Beagle
*************************
- :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`
Spend some time getting to know your Beagle via :ref:`intro_beagle-101`
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

Open hardware computers for makers, educators and professionals