Skip to content

Commit 758fc3d

Browse files
jmentijmenti
committed
docs(linux): Add initial documentation for BeagleBadge
Add an initial 'How to guide' for BeagleBadge board supported in Debian in Arago distributions. Signed-off-by: Judith Mendez <[email protected]>
1 parent 52b997e commit 758fc3d

File tree

4 files changed

+279
-0
lines changed

4 files changed

+279
-0
lines changed

‎configs/AM62LX/AM62LX_linux_toc.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -123,6 +123,8 @@ linux/How_to_Guides/Target/How_to_emmc_boot
123123
linux/How_to_Guides/Target/How_to_mmcsd_boot_emmc_uda
124124
linux/How_to_Guides/Target/How_To_Enable_M2CC3301_in_linux
125125
linux/How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
126+
linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started
127+
linux/How_to_Guides/Target/How_to_build_debian_for_beaglebadge
126128
linux/How_to_Guides/FAQ/How_to_Check_Device_Tree_Info
127129
linux/How_to_Guides/FAQ/How_to_Integrate_Open_Source_Software
128130
linux/How_to_Guides_Hardware_Setup_with_CCS

‎source/linux/How_to_Guides/Target/How_to_BeagleBadge_getting_started.rst‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
###########################
2+
BeagleBadge Getting Started
3+
###########################
4+
5+
Overview
6+
========
7+
8+
The BeagleBadge is a compact development platform from BeagleBoard.org powered by the TI AM62L SoC.
9+
Designed for portable and low-power applications, it features built-in Wi-Fi and Bluetooth, multiple
10+
low power modes, and an integrated fuel gauge for precise battery power monitoring.
11+
12+
The board provides a rich interface including an e-paper connector, DSI connector, Grove expansion,
13+
seven-segment displays, and an RGB LED. Fully supported in TI releases, the BeagleBadge offers flexible
14+
boot options (OSPI, UART, SD, USB-DFU) and runs Zephyr OS or Linux via Debian, Arago, or Buildroot,
15+
making it an ideal open-source solution for modern IoT and HMI projects.
16+
17+
Supported OS
18+
============
19+
20+
- Linux : https://github.com/TexasInstruments/ti-linux-kernel branch: ti-linux-6.12.y
21+
- Zephyr : https://github.com/glneo/zephyr branch: openamp-am62x-sk-m4
22+
23+
Supported Distributions
24+
=======================
25+
26+
- Debian: https://github.com/TexasInstruments/armbian-build.git branch: beaglebadge
27+
- Arago: https://github.com/TexasInstruments/meta-tisdk branch: scarthgap
28+
29+
What are the low level sources?
30+
===============================
31+
32+
- TI Linux: arch/arm64/boot/dts/til3-am62l3-beaglebadge.dts
33+
- TI U-boot: configs/am62lx_beaglebadge_defconfig
34+
35+
How to build?
36+
=============
37+
38+
Debian:
39+
40+
.. code-block:: console
41+
42+
$ sudo apt-get install docker.io qemu-user-static binfmt-support
43+
$ git clone https://github.com/TexasInstruments/armbian-build.git
44+
$ cd armbian-build
45+
$ git checkout beaglebadge
46+
$ ./compile.sh build BOARD=beaglebadge BRANCH=vendor-edge BUILD_MINIMAL=yes KERNEL_CONFIGURE=no RELEASE=trixie GIT_SKIP_SUBMODULES=yes SKIP_ARMBIAN_REPO=yes
47+
48+
For more information go :ref:`here <debian-building-images-beaglebadge>`
49+
50+
Arago:
51+
52+
.. code-block:: console
53+
54+
$ git clone https://git.ti.com/git/arago-project/oe-layersetup.git tisdk
55+
$ cd tisdk
56+
$ ./oe-layertool-setup.sh -f configs/arago-scarthgap-config.txt
57+
$ cd build
58+
$ . conf/setenv
59+
$ export MACHINE=beaglebadge-ti
60+
$ ARAGO_SYSVINIT=1 bitbake -k tisdk-tiny-image
61+
62+
For more information go :ref:`here <building-the-sdk-with-yocto>`
63+
64+
.. note::
65+
66+
Due to the limited 128MB size of LPDDR on BeagleBadge, only the *tisdk-tiny-image* can boot
67+
on BeagleBadge with SystemV for init system. SystemD based images will not boot or may cause
68+
kernel panics due to memory constraints.
69+
70+
How to boot?
71+
============
72+
73+
In the following instructions, assume /dev/ttyUSB0 is the serial port enumerated
74+
on host machine from BeagleBadge USB C connection.
75+
76+
SD boot:
77+
1. Flash SD card with Debian or Arago image
78+
2. Insert Micro SD card
79+
3. Press & hold Select until step 4
80+
4. Connect USB C cable
81+
5. Connect to /dev/ttyUSB0 on host machine
82+
83+
OSPI boot:
84+
1. Boot via SD boot and stop at u-boot prompt
85+
2. Flash OSPI
86+
87+
.. code-block:: console
88+
89+
=> fatload mmc 1 ${loadaddr} tiboot3.bin
90+
221296 bytes read in 11 ms (19.2 MiB/s)
91+
=> print filesize
92+
filesize=36070
93+
=> sf probe
94+
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
95+
=> sf erase 0 40000
96+
SF: 262144 bytes @ 0x0 Erased: OK
97+
=> sf write ${loadaddr} 0 36070
98+
device 0 offset 0x0, size 0x36070
99+
SF: 221296 bytes @ 0x0 Written: OK
100+
=> fatload mmc 1 ${loadaddr} tispl.bin
101+
1464080 bytes read in 62 ms (22.5 MiB/s)
102+
=> print filesize
103+
filesize=165710
104+
=> sf probe
105+
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
106+
=> sf erase 0x80000 180000
107+
SF: 1572864 bytes @ 0x80000 Erased: OK
108+
=> sf write ${loadaddr} 0x80000 165710
109+
device 0 offset 0x80000, size 0x165710
110+
SF: 1464080 bytes @ 0x80000 Written: OK
111+
=> fatload mmc 1 ${loadaddr} u-boot.img
112+
1314747 bytes read in 57 ms (22 MiB/s)
113+
=> print filesize
114+
filesize=140fbb
115+
=> sf probe
116+
SF: Detected is25wx256 with page size 256 Bytes, erase size 4 KiB, total 32 MiB
117+
=> sf erase 0x280000 180000
118+
SF: 1572864 bytes @ 0x280000 Erased: OK
119+
=> sf write ${loadaddr} 0x280000 140fbb
120+
device 0 offset 0x280000, size 0x140fbb
121+
SF: 1314747 bytes @ 0x280000 Written: OK
122+
123+
3. Reset the board (S1 RST)
124+
125+
UART boot:
126+
1. Connect USB C cable
127+
2. Connect to /dev/ttyUSB0 on host machine
128+
3. Run the following instructions on host machine:
129+
130+
.. code-block:: console
131+
132+
$ sb --xmodem tiboot3.bin > /dev/ttyUSB0 < /dev/ttyUSB0
133+
$ sb --xmodem tispl.bin > /dev/ttyUSB0 < /dev/ttyUSB0
134+
$ sb --ymodem u-boot.img > /dev/ttyUSB0 < /dev/ttyUSB0
135+
136+
USB-DFU boot:
137+
1. Press & hold Select until step 4
138+
2. Connect USB C cable
139+
3. Connect to /dev/ttyUSB0 on host machine
140+
4. Send bootloader binaries from host MACHINE
141+
142+
.. code-block:: console
143+
144+
$ sudo -E -S dfu-util -R -a bootloader -D tiboot3.bin
145+
$ sudo -E -S dfu-util -R -a bootloader -D tispl.bin
146+
$ sudo -E -S dfu-util -R -a u-boot.img -D u-boot.img
147+
148+
Any of the above boot methods can be used to boot to u-boot prompt,
149+
from here, loading the rootfs is generic and can be loaded from SD
150+
card, OSPI flash, or USB DFU as is discussed in other sections of this
151+
documentation.

‎source/linux/How_to_Guides/Target/How_to_build_debian_for_beaglebadge.rst‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
.. _debian-building-images-beaglebadge:
2+
3+
====================================================
4+
Building Debian Images for BeagleBadge Using Armbian
5+
====================================================
6+
7+
Introduction
8+
============
9+
10+
Texas Instruments uses the **Armbian** build framework to generate Debian images for its platforms.
11+
Armbian describes itself to be a "base operating system"; that is, a build framework used to build
12+
Linux images optimized for Single-Board Computers.
13+
14+
|__SDK_DOWNLOAD_URL__| provides Debian images, but users can also build these, especially if users
15+
require something custom (such as different kernel configurations or default desktop environments).
16+
17+
Armbian Usage
18+
=============
19+
20+
This document provides high-level information about how to build Debian images for TI platforms,
21+
using Armbian. For a full list of options available for users to configure these images at build
22+
time, see `Armbian Documentation <https://docs.armbian.com/>`__.
23+
24+
Get Armbian
25+
-----------
26+
27+
For the time being, `TI's fork <https://github.com/TexasInstruments/armbian-build.git>`__ of
28+
`Armbian/build <https://github.com/armbian/build.git>`__ maintains support for TI platforms.
29+
Therefore, the first step is to fetch TI's fork:
30+
31+
.. code-block:: console
32+
33+
git clone https://github.com/TexasInstruments/armbian-build.git
34+
35+
Repository Structure
36+
--------------------
37+
38+
The following files and directories are relevant to this high-level overview:
39+
40+
- :file:`config/`: This directory has configurations for boards, families, kernel configurations,
41+
desktop or CLI environments and so on. To find configuration files relevant to TI, see:
42+
43+
- :file:`config/boards/<TI EVM board>.conf`
44+
- :file:`config/sources/families/include/k3_common.inc`
45+
- :file:`config/sources/families/k3.conf`
46+
- :file:`config/kernel/linux-k3-vendor.conf`
47+
- :file:`config/kernel/linux-k3-vendor-rt.conf`
48+
- :file:`config/kernel/linux-k3-vendor-edge.conf`
49+
- :file:`config/kernel/linux-k3-edge.conf`
50+
51+
- :file:`compile.sh`: This is the script that the user should run for building Armbian images.
52+
53+
- :file:`lib/`: This directory stores the scripts that do most of the work in building Armbian images.
54+
55+
- :file:`extensions/`: This directory has files that define **extension hooks**. In Armbian, extension
56+
hooks are function signatures, which the build framework calls in the process of building an
57+
image. However, the build framework does not define these in ``lib/``. Users can define these
58+
functions and integrate custom steps in the build process. TI has ``extensions/ti-debpkgs.sh``
59+
extension file. To customize the build process, create a new file in this directory, and define
60+
your extension hooks there. Once the file is created, be sure to add the following line to
61+
board/family config file:
62+
63+
.. code-block:: console
64+
65+
enable_extension <extension_name>
66+
67+
- :file:`userpatches/`: This directory stores files that define build parameters, user patches and so on.
68+
69+
Building Images
70+
---------------
71+
72+
Armbian supports both an interactive UI and a noninteractive build process.
73+
74+
.. note::
75+
76+
This build guide has been tested on an x86 host machine running Ubuntu 22.04. The Armbian :file:`compile.sh` script
77+
builds in an ARM64 docker container. Install the following packages and configure docker:
78+
79+
.. code-block:: console
80+
81+
sudo apt update
82+
sudo apt install docker.io qemu-user-static binfmt-support
83+
sudo usermod -aG docker $USER
84+
newgrp docker
85+
86+
- To build interactively:
87+
88+
.. code-block:: console
89+
90+
./compile.sh
91+
92+
The build framework will then display dialog boxes. The user can use this to select the board, CLI
93+
or desktop environment, kernel configurations and so on.
94+
95+
- To build non-interactively:
96+
97+
.. code-block:: console
98+
99+
./compile.sh [command] [switch...] [command...]
100+
101+
A full list of build switches is available at `Build Switches <https://docs.armbian.com/Developer-Guide_Build-Switches/>`__.
102+
103+
.. warning::
104+
105+
If build issues arise, try adding these build switches to the end of the build command:
106+
107+
.. code-block:: console
108+
109+
GIT_SKIP_SUBMODULES=yes SKIP_ARMBIAN_REPO=yes
110+
111+
For example, the following command builds the minimal non-RT Trixie image:
112+
113+
.. code-block:: console
114+
115+
./compile.sh build BOARD=<board> BRANCH=vendor BUILD_MINIMAL=yes KERNEL_CONFIGURE=no RELEASE=trixie GIT_SKIP_SUBMODULES=yes SKIP_ARMBIAN_REPO=yes
116+
117+
For a list of boards and branches supported by each SoC, refer:
118+
119+
.. csv-table::
120+
:header: "SoC", "Board", "Board Config File", "Branch"
121+
122+
AM62Lx,beaglebadge,``config/boards/beaglebadge.conf``,"vendor-edge"
123+
124+
``output/images/`` stores the built images. These images have a ``.img`` extension.

‎source/linux/How_to_Guides_Developer_Notes.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ Developer Notes
3535
How_to_Guides/Target/How_to_enable_SSC_for_DSS
3636
How_to_Guides/Target/How_to_boot_quickly
3737
How_to_Guides/Target/Runtime_debug_unlock_on_secure_device
38+
How_to_Guides/Target/How_to_BeagleBadge_getting_started
39+
How_to_guides/Target/How_to_build_debian_for_beaglebadge
3840
How_to_Guides/FAQ/How_to_Verify_Ipc_Linux_R5
3941
How_to_Guides/FAQ/How_to_Configure_MSMC_memory
4042
How_to_Guides/FAQ/How_to_Check_Device_Tree_Info

0 commit comments

Comments
 (0)