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
+148 −1
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.
134 changes: 134 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

Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
###########################
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.org powered by the TI AM62L SoC.
Designed for portable and low-power applications, it features a built-in CC33xx chip supporting WI-FI and

Check warning on line 9 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": 9, "column": 1}}}, "severity": "INFO"}
Bluetooth applications, multiple low power modes, and an integrated fuel gauge for battery power monitoring.

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.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": 10, "column": 25}}}, "severity": "INFO"}
The board provides a rich interface including an e-paper connector, DSI connector, Grove expansion,

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.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": 11, "column": 69}}}, "severity": "INFO"}
seven-segment displays, and an RGB LED. Fully supported in TI sources, the BeagleBadge offers flexible boot

Check warning on line 12 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": 12, "column": 36}}}, "severity": "INFO"}

Check warning on line 12 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": 12, "column": 32}}}, "severity": "INFO"}
options (OSPI, UART, SD, USB-DFU). It supports Zephyr or Linux (with Armbian or Arago distributions), making

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.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": 13, "column": 81}}}, "severity": "WARNING"}

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 '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": 13, "column": 16}}}, "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 '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": 13, "column": 10}}}, "severity": "INFO"}
it an ideal open source solution for modern IoT and HMI projects.

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 '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": 14, "column": 53}}}, "severity": "INFO"}

Applications
============

- Deep Sleep Low Power mode down to 0.66W power draw
- E-Paper display support with tinyDRM
- WIFI & Bluetooth connectivity
- Battery-powered with fuel gauge monitoring

Supported Distributions
=======================

- Debian: https://github.com/TexasInstruments/armbian-build.git branch: 2025.12-beaglebadge
- Arago: https://github.com/TexasInstruments/meta-tisdk branch: scarthgap

Low level sources
=================

- TI Linux: :file:`arch/arm64/boot/dts/til3-am62l3-beaglebadge.dts` branch: ti-linux-6.12.y
- TI U-boot: :file:`configs/am62lx_beaglebadge_defconfig` branch ti-u-boot-2025.01

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 limited 128MB size of LPDDR on BeagleBadge, only the *tisdk-tiny-image*
can boot on BeagleBadge. Furthermore, switching to sysVinit for init system instead of systemd
will 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
===================

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. Reset the board by disconnecting and reconnecting USB C cable.

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