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
+134 −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
2 changes: 1 addition & 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 @@ -121,8 +121,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.
131 changes: 131 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

Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
===========================
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 built-in Wi-Fi and Bluetooth, multiple

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.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": 9, "column": 93}}}, "severity": "INFO"}
low power modes, and an integrated fuel gauge for precise battery power monitoring.

The board provides a rich interface including an e-paper connector, DSI connector, Grove expansion,

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

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.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": 13, "column": 41}}}, "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 '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": 36}}}, "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": 32}}}, "severity": "INFO"}
boot options (OSPI, UART, SD, USB-DFU) and runs Zephyr or Linux OS with Debian or Arago distributions,

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

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.CaseSensitiveTerms] Use 'operating system' rather than 'OS'.

Raw Output:
{"message": "[RedHat.CaseSensitiveTerms] Use 'operating system' rather than 'OS'.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 14, "column": 65}}}, "severity": "WARNING"}

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": 21}}}, "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": 15}}}, "severity": "INFO"}
Copy link
Contributor

@jonaswood01 jonaswood01 Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

nitpick, but it should say "Debian or Yocto" or "Armbian or Arago", instead of the mixed "Debian or Arago", elsewhere in guide too

making it an ideal open source solution for modern IoT and HMI projects.
Comment on lines +13 to +15
Copy link
Member

@StaticRocket StaticRocket Dec 19, 2025

Choose a reason for hiding this comment

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

Suggested change
seven-segment displays, and an RGB LED. Fully supported in TI sources, the BeagleBadge offers flexible
boot options (OSPI, UART, SD, USB-DFU) and runs Zephyr or Linux OS with Debian or Arago distributions,
making it an ideal open source solution for modern IoT and HMI projects.
seven-segment displays, and an RGB LED. Fully supported in TI sources, the BeagleBadge offers flexible
boot options (OSPI, UART, SD, USB-DFU). It supports Zephyr or Linux (with Debian or Arago distributions),
making it an ideal open source solution for modern IoT and HMI projects.


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 go :ref:`here <building-the-sdk-with-yocto>`
Copy link
Contributor

@jonaswood01 jonaswood01 Dec 19, 2025

Choose a reason for hiding this comment

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

No longer putting debian build instructions or a link to the existing debian build guide ?

Copy link
Contributor

@jonaswood01 jonaswood01 Dec 19, 2025

Choose a reason for hiding this comment

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

Is your solution now just addition of beaglebadge.conf line in source/debian/Building_Debian_Image.rst ?


.. note::

Yocto: Due to the limited 128MB size of LPDDR on BeagleBadge, only the *tisdk-tiny-image*
can boot on BeagleBadge. Switching to SystemV for init system instead of SystemD will reduce
the memory footprint since more system services will be enabled by default with SystemD.
Copy link
Contributor

@glneo glneo Dec 19, 2025

Choose a reason for hiding this comment

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

Although this isn't necessarily true, it just happens to be true today as most services are now ported over to systemd (btw systemd is usually stylized as all lower-case) and the old sysvinit versions have started to bit-rot away.


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 4
Copy link
Contributor

@glneo glneo Dec 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Not just "until" step 4, it needs to be held "through" step 4, or 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

=> fatload mmc 1 ${loadaddr} tiboot3.bin
221296 bytes read in 11 ms (19.2 MiB/s)
=> print filesize
Copy link
Contributor

@glneo glneo Dec 19, 2025

Choose a reason for hiding this comment

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

No need to print filesize, just use it directly in the commands below.

filesize=36070
=> sf probe
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
=> sf erase 0 40000
SF: 262144 bytes @ 0x0 Erased: OK
=> sf write ${loadaddr} 0 36070
Copy link
Contributor

@glneo glneo Dec 19, 2025

Choose a reason for hiding this comment

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

Like here, instead of having to type in the number from print filesize above, simply use ${filesize}.

Also if you use sf update instead of sf write you don't need to do the sf erase step above first.

One last thing, you shouldn't need to do sf probe after each operation. So this whole code block could be just:

=> sf probe
=> fatload mmc 1 ${loadaddr} tiboot3.bin
=> sf write ${loadaddr} 0 ${filesize}
=> fatload mmc 1 ${loadaddr} tispl.bin
=> sf write ${loadaddr} 0x80000 ${filesize}
=> fatload mmc 1 ${loadaddr} tiboot3.bin
=> sf write ${loadaddr} 0x280000 ${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)
=> print filesize
filesize=165710
=> sf probe
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
=> sf erase 0x80000 180000
SF: 1572864 bytes @ 0x80000 Erased: OK
=> sf write ${loadaddr} 0x80000 165710
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)
=> print filesize
filesize=140fbb
=> sf probe
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
=> sf erase 0x280000 180000
SF: 1572864 bytes @ 0x280000 Erased: OK
=> sf write ${loadaddr} 0x280000 140fbb
device 0 offset 0x280000, size 0x140fbb
SF: 1314747 bytes @ 0x280000 Written: OK

3. Reset the board (S1 RST)

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 bootloader binaries from host MACHINE

Check failure on line 120 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.TermsErrors] Use 'boot loader' rather than 'bootloader'.

Raw Output:
{"message": "[RedHat.TermsErrors] Use 'boot loader' rather than 'bootloader'.", "location": {"path": "source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst", "range": {"start": {"line": 120, "column": 12}}}, "severity": "ERROR"}
Copy link
Member

@StaticRocket StaticRocket Dec 19, 2025

Choose a reason for hiding this comment

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

Suggested change
4. Send bootloader binaries from host MACHINE
4. Send boot loader binaries from host MACHINE

Copy link
Contributor

@jonaswood01 jonaswood01 Dec 19, 2025

Choose a reason for hiding this comment

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

bootloader is typically one word

Copy link
Member

@StaticRocket StaticRocket Dec 19, 2025

Choose a reason for hiding this comment

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

Even GRUB [1] includes both spellings, but most spellcheck utilities do not recognize the single word spelling. If you look up the definition of the single word spelling, you are redirected to the dual word definition.

[1] https://www.gnu.org/software/grub/index.html


.. 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