Skip to content

docs(linux): Add initial documentation for BeagleBadge #602

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jmenti wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(linux): Add initial documentation for BeagleBadge #602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions configs/AM62LX/AM62LX_linux_toc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,7 @@ linux/How_to_Guides/Target/How_to_emmc_boot
linux/How_to_Guides/Target/How_to_mmcsd_boot_emmc_uda
linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started
linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
linux/How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
linux/How_to_Guides_Hardware_Setup_with_CCS
Expand Down
13 changes: 12 additions & 1 deletion source/debian/Building_Debian_Image.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,17 @@ Therefore, the first step is to fetch TI's fork:

git clone https://github.com/TexasInstruments/armbian-build.git

.. ifconfig:: CONFIG_part_variant in ('AM62LX')

.. note::

BeagleBadge is supported in Armbian but is not yet supported on **ti-main** branch, therefore run the following command
before building for BeagleBadge:

.. code-block:: console

git checkout 2025.12-beaglebadge

Repository Structure
--------------------

Expand Down Expand Up @@ -121,8 +132,8 @@ For a list of boards and branches supported by each SoC, refer:
AM62-LP,sk-am62-lp,``config/boards/sk-am62-lp.conf``,"vendor, vendor-rt, vendor-edge, edge"
AM62SIP,sk-am62-sip,``config/boards/sk-am62-sip.conf``,"vendor, vendor-rt, vendor-edge, edge"
AM62Lx,tmds62levm,``config/boards/tmds62levm.conf``,"vendor, vendor-rt, vendor-edge"
AM62Lx,beaglebadge,``config/boards/beaglebadge.conf``,"vendor-edge"
AM62Px,sk-am62p,``config/boards/sk-am62p.conf``,"vendor, vendor-rt, vendor-edge, edge"
AM64x,sk-am64b,``config/boards/sk-am64b.conf``,"vendor, vendor-rt, vendor-edge, edge"


``output/images/`` stores the built images. These images have a ``.img`` extension.
177 changes: 177 additions & 0 deletions source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst
View file
Open in desktop
Copy link
Member

@StaticRocket StaticRocket Dec 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please use the standard section hierarchy.

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections

Copy link
Member

@StaticRocket StaticRocket Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This comment is still valid

Copy link

@jmende27 jmende27 Jan 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

WYM, headers are already fixed. *** for chapters, ==== for sections, and ---- for subsections. Am I missing something here?

Copy link
Member

@StaticRocket StaticRocket Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Every file is parsed from ordinal 0, so it should actually be like the following:
https://github.com/TexasInstruments/processor-sdk-doc/blob/master/CONTRIBUTING.md#headings--sections

Copy link
Member

@StaticRocket StaticRocket Jan 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now Judith, that change needs to be propagated to all the other sections...

Original file line number Diff line number Diff line change
@@ -0,0 +1,177 @@
###########################
BeagleBadge Getting Started

Check warning on line 2 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Headings] Use sentence-style capitalization in 'BeagleBadge Getting Started'.

Raw Output:
{"message": "[RedHat.Headings] Use sentence-style capitalization in 'BeagleBadge Getting Started'.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 2, "column": 1}}}, "severity": "INFO"}
###########################

********
Overview
********

The BeagleBadge is a compact development platform from `BeagleBoard <https://www.beagleboard.org/>`__ powered
by the `TI AM62L SoC <https://www.ti.com/product/AM62L/>`__. Designed for portable and low-power applications,

Check warning on line 10 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.SentenceLength] Try to keep sentences to an average of 32 words or fewer.

Raw Output:
{"message": "[RedHat.SentenceLength] Try to keep sentences to an average of 32 words or fewer.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 10, "column": 62}}}, "severity": "INFO"}
it features a built-in CC33xx chip supporting WI-FI and Bluetooth applications, multiple low power modes, and

Check warning on line 11 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.SimpleWords] Use simple language. Consider using 'many' rather than 'multiple'.

Raw Output:
{"message": "[RedHat.SimpleWords] Use simple language. Consider using 'many' rather than 'multiple'.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 11, "column": 81}}}, "severity": "INFO"}
an integrated fuel gauge for battery power monitoring. The board provides a rich interface including an e-paper
connector, DSI connector, Grove expansion, seven-segment displays, and an RGB LED. Fully supported in TI sources,

Check warning on line 13 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'LED') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'LED') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 13, "column": 79}}}, "severity": "INFO"}

Check warning on line 13 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'RGB') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'RGB') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 13, "column": 75}}}, "severity": "INFO"}

Check warning on line 13 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'DSI') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'DSI') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 13, "column": 12}}}, "severity": "INFO"}
the BeagleBadge offers flexible boot options (OSPI, UART, SD, USB-DFU). It supports Zephyr or Linux (with Armbian

Check warning on line 14 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'UART') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'UART') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 14, "column": 53}}}, "severity": "INFO"}

Check warning on line 14 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'OSPI') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'OSPI') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 14, "column": 47}}}, "severity": "INFO"}
or Arago distributions), making it an ideal open source solution for modern IoT and HMI projects.

Check warning on line 15 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Definitions] Define acronyms and abbreviations (such as 'HMI') on first occurrence if they're likely to be unfamiliar.

Raw Output:
{"message": "[RedHat.Definitions] Define acronyms and abbreviations (such as 'HMI') on first occurrence if they're likely to be unfamiliar.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 15, "column": 85}}}, "severity": "INFO"}

Check warning on line 15 in source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst

View workflow job for this annotation

GitHub Actions / vale 

[vale] reported by reviewdog 🐶
[RedHat.Spelling] Verify the word 'Arago'. It is not in the American English spelling dictionary used by Vale.

Raw Output:
{"message": "[RedHat.Spelling] Verify the word 'Arago'. It is not in the American English spelling dictionary used by Vale.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 15, "column": 4}}}, "severity": "WARNING"}

*********
Boot Flow
*********

BeagleBadge has a `TI AM62L SoC <https://www.ti.com/product/AM62L/>`__, refer to :ref:`AM62Lx Boot Flow <Boot-Flow-label>`
for more details on AM62L boot flow.

************
Applications
************

- Deep Sleep Low Power mode as low as 350mW power draw
- RTC only mode with 3-5mW power draw
- E-Paper display support with tinyDRM
- Battery-powered with fuel gauge monitoring

*****************
Low level sources
*****************

.. list-table::
:header-rows: 1
:widths: 15, 15, 15

* - Component
- Branch
- Source File
* - U-Boot
- `ti-u-boot-2025.01 <https://git.ti.com/cgit/ti-u-boot/ti-u-boot/log/?h=ti-u-boot-2025.01>`__
- :file:`configs/am62lx_beaglebadge_defconfig`
* - Linux Kernel
- `ti-linux-6.12.y <https://git.ti.com/cgit/ti-linux-kernel/ti-linux-kernel/log/?h=ti-linux-6.12.y>`__
- :file:`arch/arm64/boot/dts/ti/k3-am62l3-beaglebadge.dts`

***********************
Supported Distributions
***********************

.. list-table::
:header-rows: 1
:widths: 15, 15

* - Component
- Branch
* - Armbian
- `2025.12-beaglebadge <https://github.com/TexasInstruments/armbian-build/tree/2025.12-beaglebadge>`__
* - Arago
- `Scarthgap <https://github.com/TexasInstruments/meta-tisdk/tree/scarthgap>`__

************************
Building for BeagleBadge
************************

.. code-block:: console

$ git clone https://git.ti.com/git/arago-project/oe-layersetup.git tisdk
$ cd tisdk
$ ./oe-layertool-setup.sh -f configs/arago-scarthgap-config.txt
$ cd build
$ . conf/setenv
$ export MACHINE=beaglebadge-ti
$ ARAGO_SYSVINIT=1 bitbake -k tisdk-tiny-image

For more information on building Arago for BeagleBadge, go :ref:`here <building-the-sdk-with-yocto>`.

.. note::

Yocto: Due to the 256MB size of LPDDR on BeagleBadge, there may be limited free memory (about 17-20MB)
for developing applications with the **default**, TI-provided Arago distribution image. Switching to
sysVinit for init system instead of systemd can help reduce the memory footprint further. Please go
`here <https://www.linuxjournal.com/content/embracing-future-transition-sysvinit-systemd-linux>`__
for a comparison of both init systems.

To build Armbian for BeagleBadge, refer to **Debian SDK user manual** found `here <https://www.ti.com/tool/download/AM62L-LINUX-SDK>`__.

*******************
Booting BeagleBadge
*******************

BeagleBadge supports four boot modes with the following configuration:

+-------------------------+-------------------+------------------+
| Button *Select* Pressed | Primary boot mode | Backup boot mode |
+=========================+===================+==================+
| Yes | SD boot | USB-DFU boot |
+-------------------------+-------------------+------------------+
| No | OSPI boot | UART boot |
+-------------------------+-------------------+------------------+

In the following instructions, assume /dev/ttyUSB0 is the serial port enumerated
on host machine from BeagleBadge USB C connection.

SD boot
=======

1. Flash SD card with Debian or Arago image
2. Insert Micro SD card
3. Press & hold **Select** until step 5
4. Connect USB C cable
5. Connect to /dev/ttyUSB0 on host machine

OSPI boot
=========

1. Boot via SD boot and stop at u-boot prompt
2. Flash OSPI

.. code-block:: console

=> sf probe
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
=> fatload mmc 1 ${loadaddr} tiboot3.bin
221296 bytes read in 11 ms (19.2 MiB/s)
=> sf update ${loadaddr} 0 ${filesize}
device 0 offset 0x0, size 0x36070
SF: 221296 bytes @ 0x0 Written: OK
=> fatload mmc 1 ${loadaddr} tispl.bin
1464080 bytes read in 62 ms (22.5 MiB/s)
=> sf update ${loadaddr} 0x80000 ${filesize}
device 0 offset 0x80000, size 0x165710
SF: 1464080 bytes @ 0x80000 Written: OK
=> fatload mmc 1 ${loadaddr} u-boot.img
1314747 bytes read in 57 ms (22 MiB/s)
=> sf update ${loadaddr} 0x280000 ${filesize}
device 0 offset 0x280000, size 0x140fbb
SF: 1314747 bytes @ 0x280000 Written: OK

3. Cold reset the board by disconnecting and reconnecting USB C cable.
4. Reconnect to /dev/ttyUSB0 on host machine

UART boot
=========

1. Connect USB C cable
2. Connect to /dev/ttyUSB0 on host machine
3. Run the following instructions on host machine:

.. code-block:: console

$ sb --xmodem tiboot3.bin > /dev/ttyUSB0 < /dev/ttyUSB0
$ sb --xmodem tispl.bin > /dev/ttyUSB0 < /dev/ttyUSB0
$ sb --ymodem u-boot.img > /dev/ttyUSB0 < /dev/ttyUSB0

USB-DFU boot
============

1. Press & hold **Select** until step 4
2. Connect USB C cable
3. Connect to /dev/ttyUSB0 on host machine
4. Send boot loader binaries from host MACHINE

.. code-block:: console

$ sudo -E -S dfu-util -R -a bootloader -D tiboot3.bin
$ sudo -E -S dfu-util -R -a bootloader -D tispl.bin
$ sudo -E -S dfu-util -R -a u-boot.img -D u-boot.img

Any of the above boot methods can be used to boot to u-boot prompt,
from here, loading the rootfs is generic and can be loaded from SD
card, OSPI flash, or USB DFU as is discussed in other sections of this
documentation.
1 change: 1 addition & 0 deletions source/linux/How_to_Guides_Developer_Notes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ Developer Notes
How_to_Guides/Target/How_to_enable_SSC_for_DSS
How_to_Guides/Target/How_to_boot_quickly
How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
How_to_Guides/Target/How_to_BeagleBadge_getting_started
How_to_Guides/FAQ/How_to_Verify_Ipc_Linux_R5
How_to_Guides/FAQ/How_to_Configure_MSMC_memory
How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
Expand Down
Loading