mirror of
https://github.com/espressif/openthread.git
synced 2026-09-01 06:49:54 +00:00
[docs] update BeagleBone setup guide (#5606)
Added language to show how to replace Connman with Network Manager to enable the default setup scripts. Added pointers on setting up a WiLink 8 module for Wi-Fi AP development. Removed explanation of downloading and flashing the BeagleBone image in favor of linking to the public BeagleBone documentation. Removed explanation of expanding and truncating the filesystem in favor of using the helper tool from BeagleBone.
This commit is contained in:
Seth Rickard
@@ -1,338 +1,204 @@
|
||||
# BeagleBone Black
|
||||
|
||||
Contributor: https://github.com/DuaneEllis-TI
|
||||
Contributor: https://github.com/srickardti
|
||||
|
||||
OpenThread Border Router (OTBR) provides support for the [BeagleBone
|
||||
Black](http://www.ti.com/tool/BEAGLEBK) (BBB) platform.
|
||||
|
||||
Hardware requirements:
|
||||
|
||||
* External 5V AC adapter for power
|
||||
* An 8 GB or larger microSD card ("SD card" in this guide)
|
||||
* A supported OpenThread platform (such as the [TI
|
||||
CC2652](https://openthread.io/vendors/texas-instruments#cc2652))
|
||||
for Thread network connectivity in an RCP design
|
||||
* External 5V AC adapter for power
|
||||
* An 8 GB or larger microSD card ("uSD card" in this guide)
|
||||
* A supported OpenThread platform (such as the [TI
|
||||
CC2652](https://openthread.io/vendors/texas-instruments#cc2652)) for Thread
|
||||
network connectivity in an RCP design
|
||||
|
||||
To use BBB with OTBR:
|
||||
Steps to enable
|
||||
1. Download and install the OS.
|
||||
1. Prepare the Debian Environment for OTBR
|
||||
1. Build and install OTBR
|
||||
1. Set up a Wi-Fi access point
|
||||
|
||||
1. Download firmware and write the image to the SD card.
|
||||
1. Boot BBB from the SD card.
|
||||
1. Expand the SD card image to create enough space to build and install OTBR.
|
||||
1. Build and install OTBR.
|
||||
> Note: The BBB does not have built-in Wi-Fi support. This guide was built and
|
||||
> tested with a BBONE-GATEWAY-CAPE for Wi-Fi AP operation. Some BeagleBone
|
||||
> variants have onboard Wi-Fi capability, and some of this guide may be
|
||||
> applicable.
|
||||
|
||||
Note: The BBB does not have built-in Wi-Fi support, and cannot be used as a
|
||||
Wi-Fi Access Point.
|
||||
## Step 1: Download and install the OS
|
||||
|
||||
## Step 1: Download firmware
|
||||
1. Download the [latest Debian IoT image for
|
||||
BeagleBone](https://beagleboard.org/latest-images).
|
||||
* The version used for this guide was
|
||||
`bone-debian-10.3-iot-armhf-2020-04-06-4gb.img.xz`
|
||||
1. Install the OS image on a uSD Card by following the [BeagleBone getting
|
||||
started guide](https://beagleboard.org/getting-started).
|
||||
1. Boot the BeagleBone and SSH into the device.
|
||||
* Connectivity over a local Ethernet based network is recommended.
|
||||
* The cloud9 IDE will be disabled later in this guide.
|
||||
* This guide will change the state of BeagleBone network interfaces, be
|
||||
aware your secure shell session may disconnect.
|
||||
* Modern BeagleBone bootloaders will run from the uSD card by default, but
|
||||
some BeagleBone Black devices may try to boot from the internal eMMC.
|
||||
Make sure to press the BOOT Button in this case.
|
||||
|
||||
1. Recommended firmware is [Stretch for BeagleBone via microSD
|
||||
card](https://beagleboard.org/latest-images):
|
||||
* Debian 9.1 2017-08-31 4GB SD LXQT
|
||||
* **Filename:** `bone-debian-9.1-lxqt-armhf-2017-08-31-4gb.img.xz`
|
||||
1. Write the image to an 8 GB or larger SD card using a tool such as
|
||||
[Etcher](https://etcher.io/) or [Win32 Disk
|
||||
Imager](https://sourceforge.net/projects/win32diskimager/).
|
||||
> Warning: The power requirements of the development kit used for the
|
||||
> OpenThread RCP may be too great for the power that can be supplied from a
|
||||
> computer's USB port. It is recommended that you use the 5V power adaptor for
|
||||
> the BeagleBone where applicable.
|
||||
|
||||
## Step 2: Boot from the SD card
|
||||
For more detailed information on the BeagleBone, see the [BeagleBoard Support
|
||||
Page](https://beagleboard.org/support).
|
||||
|
||||
<figure class="attempt-right">
|
||||
<a href="/guides/images/otbr-platform-bbb_2x.png"><img src="/guides/images/otbr-platform-bbb.png" srcset="/guides/images/otbr-platform-bbb.png 1x, /guides/images/otbr-platform-bbb_2x.png 2x" border="0" alt="BeagleBone Black" /></a>
|
||||
</figure>
|
||||
## Step 2: Prepare the Debian Environment for OTBR
|
||||
|
||||
BBB can boot from either the on-board flash memory or the SD card. To use BBB
|
||||
with OTBR, you must boot from the SD card, as the on-board flash memory is not
|
||||
large enough to build and install OTBR.
|
||||
Certain parts of the default BeagleBone Debian image run by default. These may
|
||||
conflict with some parts of the OpenThread Border Router software.
|
||||
|
||||
To boot BBB from the SD card:
|
||||
Some packages are running by default on the BeagleBone to enable quick
|
||||
development. These can be found in systemd with the command `sudo systemctl
|
||||
list-units --all` and `sudo systemctl list-sockets --all`.
|
||||
|
||||
1. Insert the SD card.
|
||||
1. Disconnect the power.
|
||||
1. Press and hold the BOOT button.
|
||||
1. Connect the power.
|
||||
1. When the LEDs start to blink, release the BOOT button.
|
||||
|
||||
> Warning: By default, the BBB boots from the
|
||||
on-board flash memory. <b>You must repeat this boot process every time
|
||||
the BBB is power cycled.</b>
|
||||
|
||||
## Step 3: Expand the SD card image
|
||||
|
||||
Linux images for Beagle Bone Black (BBB) are purposely created small so that the
|
||||
image can be placed on any 4 GB SD card (or the on-board 4 GB Flash Memory),
|
||||
then expanded as needed. In total there is about 300 MB of free space. That may
|
||||
not be enough space to install and build the OpenThread Border Router using the
|
||||
BBB.
|
||||
|
||||
To solve this problem:
|
||||
|
||||
1. Write the Linux image to a larger SD card (at least 8 GB).
|
||||
1. Expand the ~4 GB Linux partition of the image to slightly less than the size
|
||||
of the entire SD card. For example, if using an 8 GB SD card, expand it to
|
||||
~7 GB. For a 16 GB card, expand it to ~15 GB.
|
||||
1. Boot the BBB from the SD card.
|
||||
|
||||
Note: Expanding the image to a size slightly less than the size of the entire SD
|
||||
card leaves unused space at the end of the card. This resulting image can be
|
||||
read back, truncated to size, and used to create other images as needed. See
|
||||
[Clone a re-configured SD card](#clone-a-re-configured-sd-card-optional) for
|
||||
more information.
|
||||
|
||||
### SD card partitions
|
||||
|
||||
Data on an SD card is effectively a continuous array of data sectors. The
|
||||
sectors are numbered starting with `0` and ending at Sector `N` somewhere around
|
||||
XX GB, the exact last number is dependent upon the actual SD card.
|
||||
|
||||
Sector 0 always contains an MS-DOS Partition table. An MS-DOS partition table
|
||||
can hold between 1 and 4 partition entries. Each partition is a continuous
|
||||
series of sectors from `X` to `Y` somewhere within the bounds of the SD card.
|
||||
This repeats for each of the 4 possible partitions. Typically, partitions are
|
||||
located in order, with some number (`0` to `N`) of unused sectors at the end.
|
||||
This "some number of unused sectors" (`SOME_N`) can be used to your advantage
|
||||
later.
|
||||
|
||||
Caution: The largest partition should be a Linux partition, and it must be the
|
||||
last partition on the SD card. This process does not work if the Linux partition
|
||||
is not the last partition.
|
||||
|
||||
When writing an image to an SD card, writing begins at Sector `0` and progresses
|
||||
to `SOME_N`, depending on the size of the image. What you cannot do is stretch
|
||||
the partition around the image—that's not possible. Instead, think of a
|
||||
picture frame around a canvas. The picture frame is the partition and the
|
||||
picture is the data. What you can do is replace the existing picture frame with
|
||||
a larger one, and expand the canvas within:
|
||||
|
||||
1. Delete the existing Linux partition without deleting the data. You have
|
||||
removed the picture frame, but the picture is still present on the canvas.
|
||||
1. Create a new Linux partition that starts exactly where the old one started,
|
||||
but ends close to the end of the SD card. You have created a larger picture
|
||||
frame. The picture—the data—is still there on the canvas. It has not moved
|
||||
and was not corrupted by this operation.
|
||||
1. Use a file system-specific tool to grow the file system within the bounds of
|
||||
the new partition. The canvas is stretched to fill the new, larger picture
|
||||
frame.
|
||||
|
||||
### 1. Identify the current data partition
|
||||
|
||||
Boot the BBB from the SD Card and log in as `root`:
|
||||
Stop and disable the modules:
|
||||
|
||||
```
|
||||
$ sudo bash
|
||||
$ sudo systemctl stop bonescript-autorun.service
|
||||
$ sudo systemctl stop bonescript.socket
|
||||
$ sudo systemctl stop bonescript.service
|
||||
$ sudo systemctl stop cloud9.socket
|
||||
$ sudo systemctl stop cloud9.service
|
||||
$ sudo systemctl stop nodered.service
|
||||
$ sudo systemctl disable bonescript-autorun.service
|
||||
$ sudo systemctl disable bonescript.socket
|
||||
$ sudo systemctl disable bonescript.service
|
||||
$ sudo systemctl disable cloud9.socket
|
||||
$ sudo systemctl disable cloud9.service
|
||||
$ sudo systemctl disable nodered.service
|
||||
$ sudo systemctl daemon-relaod
|
||||
```
|
||||
|
||||
Identify the SD card data partition. The `p1` suffix on the `Filesystem`
|
||||
field is the naming convention for Partition 1. The device itself is
|
||||
`/dev/mmcblk0`. In this example, only 295 MB are free. This is not enough
|
||||
space to build and install OTBR.
|
||||
Disable advertising the Cloud9 IDE and NodeRED services with Avahi by deleting
|
||||
the service files:
|
||||
|
||||
```
|
||||
root@beaglebone:/home/debian# df -hT /
|
||||
Filesystem Type Size Used Avail Use% Mounted on
|
||||
/dev/mmcblk0p1 ext4 3.3G 2.8G 295M 91% /
|
||||
$ sudo rm /etc/avahi/services/*
|
||||
```
|
||||
|
||||
> Note: This example image has a single partition,
|
||||
other images may have additional partitions.
|
||||
|
||||
### 2. Create the new, larger partition
|
||||
|
||||
Run `fdisk` on the device (SD card):
|
||||
The filesystem for the uSD BeagleBone image is limited to 4GB to fit on most
|
||||
uSD cards. Expand the partition to enable usage of the entire storage capacity.
|
||||
|
||||
```
|
||||
root@beaglebone:/home/debian# fdisk /dev/mmcblk0
|
||||
|
||||
Welcome to fdisk (util-linux 2.25.2).
|
||||
Changes will remain in memory only, until you decide to write them.
|
||||
Be careful before using the write command.
|
||||
$ sudo /opt/scripts/tools/grow_partitions.sh
|
||||
```
|
||||
|
||||
Print the current partition table to find the starting sector.
|
||||
The value of the `Start` field is the starting sector for the target
|
||||
partition. It should be listed with the same partition name as in Step 1,
|
||||
with a `Type` of `Linux`. In the output below, the starting sector is `8192`.
|
||||
You are encouraged to read that helper script to find out how the filesystem is
|
||||
expanded. You will have to reboot the BeagleBone and re-login to use this new
|
||||
filesystem definition.
|
||||
|
||||
```
|
||||
Command (m for help): p
|
||||
Disk /dev/mmcblk0: 7.2 GiB, 7744782336 bytes, 15126528 sectors
|
||||
Units: sectors of 1 * 512 = 512 bytes
|
||||
Sector size (logical/physical): 512 bytes / 512 bytes
|
||||
I/O size (minimum/optimal): 512 bytes / 512 bytes
|
||||
Disklabel type: dos
|
||||
Disk identifier: 0xca52207f
|
||||
|
||||
Device Boot Start End Sectors Size Id Type
|
||||
/dev/mmcblk0p1 * 8192 6963199 6955008 3.3G 83 Linux
|
||||
$ sudo shutdown -r now
|
||||
```
|
||||
|
||||
Delete the existing partition:
|
||||
This will close your SSH session.
|
||||
|
||||
Once logged back into the BeagleBone, install Network Manager with the command
|
||||
`sudo apt-get install network-manager`. Then disable `connman` and enable
|
||||
`network-manager`:
|
||||
|
||||
```
|
||||
Command (m for help): d
|
||||
Selected partition 1
|
||||
Partition 1 has been deleted.
|
||||
$ sudo systemctl disable connman
|
||||
$ sudo systemctl enable netowrk-manager
|
||||
```
|
||||
|
||||
Create the new partition, using a partition number of 1, the same starting
|
||||
sector of the previous partition (`8192` in this example), and a size that's
|
||||
1 GB less that the SD card size. For example, if using an 8 GB SD card,
|
||||
specify a size of `+7G`. For a 16 GB SD card, specify a size of `+15GB`.
|
||||
If we were to `stop` connman directly here it would break the SSH session
|
||||
because the network interface is managed by connman. Instead we configure the
|
||||
system to take effect on the next boot. Now reboot the Beaglebone and re-login.
|
||||
|
||||
```
|
||||
Command (m for help): n
|
||||
Partition type
|
||||
p primary (0 primary, 0 extended, 4 free)
|
||||
e extended (container for logical partitions)
|
||||
Select (default p): p
|
||||
Partition number (1-4, default 1): 1
|
||||
First sector (2048-15126527, default 2048): 8192
|
||||
Last sector, +sectors or +size{K,M,G,T,P} (8192-15126527, default 15126527): +7G
|
||||
|
||||
Created a new partition 1 of type 'Linux' and of size 7 GiB.
|
||||
$ sudo shutdown -r now
|
||||
```
|
||||
|
||||
Newer versions of `fdisk` prompt you to erase the old disk `ext4`
|
||||
signature. **Do not erase this signature.** Otherwise, data is corrupted and
|
||||
the entire image becomes useless.
|
||||
Network Manager may not have setup the DNS name servers. Edit `resolv.conf`
|
||||
with the command `sudo vim /etc/resolv.conf` and make sure the contents contain
|
||||
the Google DNS and Cloudflare DNS:
|
||||
|
||||
```
|
||||
Partition #1 contains a ext4 signature.
|
||||
|
||||
Do you want to remove the signature [Y]/No: n
|
||||
nameserver 8.8.8.8
|
||||
nameserver 1.1.1.1
|
||||
```
|
||||
|
||||
Write the new partition table to disk and quit `fdisk`:
|
||||
Restart to make sure Network Manager is setup correctly.
|
||||
|
||||
```
|
||||
Command (m for help): w
|
||||
The partition table has been altered.
|
||||
Calling ioctl() to re-read partition table.
|
||||
Re-reading the partition table failed.: Device or resource busy
|
||||
|
||||
The kernel still uses the old table. The new table will be used at the next
|
||||
reboot or after you run partprobe(8) or kpartx(8).
|
||||
$ sudo shutdown -r now
|
||||
```
|
||||
|
||||
### 3. Resize the file system
|
||||
> Note: If your BeagleBone has a WiLink based Wi-Fi module installed, the
|
||||
> following steps may be applicable to you. This was tested with a
|
||||
> BBONE-GATEWAY-CAPE. Some of these may not be required.
|
||||
|
||||
Use `resize2fs` to resize the image file system to the newly-expanded partition
|
||||
size. This tool expands or shrinks a file system.
|
||||
|
||||
Reboot the BBB.
|
||||
|
||||
Some images may throw an `fsck` error upon reboot. `fsck` runs
|
||||
automatically on boot and checks for file system consistency. If you get
|
||||
this error, ignore it and wait about 20 seconds for the login
|
||||
prompt to appear.
|
||||
The WiLink 8 module does not like to have its MAC address changed at runtime.
|
||||
Network Manager will try to do this when scanning. Edit the
|
||||
`NetworkManager.conf` with the command `sudo vim
|
||||
/etc/Networkmanager/NetworkManager.conf` and add the lines below:
|
||||
|
||||
```
|
||||
Loading, please wait...
|
||||
[ 4.873285] remoteproc1: failed to load am335x-pru0-fw
|
||||
[ 4.918852] remoteproc1: request_firmware failed: -2
|
||||
[ 4.924046] pru-rproc 4a334000.pru0: rproc_boot failed
|
||||
[ 5.052414] remoteproc1: failed to load am335x-pru1-fw
|
||||
[ 5.069652] remoteproc1: request_firmware failed: -2
|
||||
[ 5.074889] pru-rproc 4a338000.pru1: rproc_boot failed
|
||||
fsck: error 2 (No such file or directory) while executing fsck.ext4 for /dev/mmcblk0p1
|
||||
fsck exited with status code 8
|
||||
[device]
|
||||
wifi.scan-rand-mac-address=no
|
||||
```
|
||||
|
||||
Log in as `root`:
|
||||
The `BBONE-GATEWAY-CAPE` is not recognized by the BeagleBone by default because
|
||||
of a pin conflict. Add the configuration manually by editing the `uEnv.txt`
|
||||
with the command `sudo vim /boot/uEnv.txt` and make sure the following lines
|
||||
match:
|
||||
|
||||
```
|
||||
$ sudo bash
|
||||
###Custom Cape
|
||||
dtb_overlay=/lib/firmware/BB-GATEWAY-WL1837-00A0.dtbo
|
||||
###
|
||||
###Disable auto loading of virtual capes (emmc/video/wireless/adc)
|
||||
disable_uboot_overlay_emmc=1
|
||||
disable_uboot_overlay_video=1
|
||||
disable_uboot_overlay_audio=1
|
||||
disable_uboot_overlay_wireless=1
|
||||
disable_uboot_overlay_adc=1
|
||||
```
|
||||
|
||||
Resize the file system for the target partition:
|
||||
The BeagleBone wilink setup scripts try to use connman by default to enable
|
||||
Wi-Fi AP activity. Edit the default configuration folder with the command `sudo
|
||||
vim /etc/default/bb-wl18xx` and make sure the variables match below:
|
||||
|
||||
```
|
||||
root@beaglebone:/home/debian# resize2fs /dev/mmcblk0p1
|
||||
resize2fs 1.43 (17-May-2016)
|
||||
Filesystem at /dev/mmcblk0p1 is mounted on /; on-line resizing required
|
||||
old_desc_blocks = 1, new_desc_blocks = 1
|
||||
The filesystem on /dev/mmcblk0p1 is now 1835008 (4k) blocks long.
|
||||
TETHER_ENABLED=no
|
||||
USE_CONNMAN_TETHER=no
|
||||
```
|
||||
|
||||
Reboot the BBB. If you encountered the `fsck` issue, rebuild the `initramfs`, which is
|
||||
the initial RAM file system used when Linux boots.
|
||||
Restart to make sure Network Manager can see the new interface.
|
||||
|
||||
```
|
||||
$ sudo update-initramfs -u
|
||||
update-initramfs: Generating /boot/initrd.img-4.4.54-ti-r93
|
||||
$ sudo shutdown -r now
|
||||
```
|
||||
|
||||
Reboot the BBB again. It should boot without the `fsck` error.
|
||||
Once logged back in you can run `ifconfig` or `nmcli` to see the new `wlan`
|
||||
interface.
|
||||
|
||||
## Step 4: Build and install OTBR
|
||||
> Warning: The startup scripts may take a few moments to enable the `wlan0`
|
||||
> interface. If you do not see the interface, check `journalctl` to see if the
|
||||
> system is having difficulty bringing up the interface.
|
||||
|
||||
## Step 3: Build and install OTBR
|
||||
|
||||
See [Build and Configuration](https://openthread.io/guides/border-router/build)
|
||||
for instructions on building and installing OTBR.
|
||||
for instructions on building and installing OTBR.
|
||||
|
||||
## Step 5: Clone a re-configured SD card (optional)
|
||||
> NOTE: If your BeagleBone has Wi-Fi capabilities, you can enable the OTBR
|
||||
> build scripts to configure it as an access point by passing
|
||||
> `NETWORK_MANAGER_WIFI=1` to the build scripts.
|
||||
|
||||
An SD card re-configured with the resized Linux partition for BBB can be cloned
|
||||
for easier distribution.
|
||||
## Step 4: Set up a Wi-Fi access point
|
||||
|
||||
**The problem:** Many GUI tools read the entire SD card—including the free area
|
||||
after the end of the partition and up until the last sector—and do not
|
||||
offer a way to read only a portion of the image. Each SD card has a different
|
||||
number of good and bad sectors, and the total byte size of the new SD card may
|
||||
be smaller (7.999 GB) than the resized image (8.0 GB). In this case, the resized
|
||||
image cannot fit on the new SD card.
|
||||
If your BeagleBone is Wi-Fi enabled and automatic setup of the Wi-Fi access
|
||||
point by Network Manager is skipped, see [Wi-Fi Access Point
|
||||
Setup](https://openthread.io/guides/border-router/access-point) for manual
|
||||
configuration instructions. The guide is written for Raspberry Pi, but most of
|
||||
the configuration steps are applicable to the BeagleBone Debian distribution.
|
||||
|
||||
**The solution:** Use a partition size that's slightly smaller than the full
|
||||
size of the SD card. The [Expand the SD card
|
||||
image](#expand-the-sd-card-image) procedure uses `+7G` as the new partition
|
||||
size for an 8 GB SD card. This produces an image that is small enough to safely
|
||||
fit on any comparable 8 GB SD card (regardless of bad sectors) while still being
|
||||
large enough to build and install OTBR.
|
||||
|
||||
Use the ending sector of the data partition to calculate the entire byte size of
|
||||
the "data image" and truncate the IMG file at that byte offset. The simplest
|
||||
method is to use the `truncate` command. The `truncate` command is a standard
|
||||
Unix command line tool, and it is also present in the MS-Windows Git Bash
|
||||
distribution of MSYS.
|
||||
|
||||
As `root`, run `fdisk` on the device (SD card):
|
||||
|
||||
```
|
||||
root@beaglebone:/home/debian# fdisk /dev/mmcblk0
|
||||
|
||||
Welcome to fdisk (util-linux 2.25.2).
|
||||
Changes will remain in memory only, until you decide to write them.
|
||||
Be careful before using the write command.
|
||||
```
|
||||
|
||||
Print the current partition table to find the ending sector. In this
|
||||
example, the ending sector is `14688255`:
|
||||
|
||||
```
|
||||
Command (m for help): p
|
||||
Disk /dev/mmcblk0: 7.2 GiB, 7744782336 bytes, 15126528 sectors
|
||||
Units: sectors of 1 * 512 = 512 bytes
|
||||
Sector size (logical/physical): 512 bytes / 512 bytes
|
||||
I/O size (minimum/optimal): 512 bytes / 512 bytes
|
||||
Disklabel type: dos
|
||||
Disk identifier: 0xca52207f
|
||||
|
||||
Device Boot Start End Sectors Size Id Type
|
||||
/dev/mmcblk0p1 8192 14688255 14680064 7G 83 Linux
|
||||
```
|
||||
|
||||
Quit `fdisk` and calculate the total size of the image:
|
||||
|
||||
1. The last partition ends at sector `14688255`.
|
||||
1. Each sector is 512 bytes.
|
||||
1. The starting sector of an SD card is always `0`. Add 1 byte to account
|
||||
for this sector.
|
||||
1. The total size is: `(14688255 + 1) * 512 = 7520387072`
|
||||
|
||||
Read the SD card image into an `.img` file, using a tool such as
|
||||
[Etcher](https://etcher.io/) or [Win32 Disk
|
||||
Imager](https://sourceforge.net/projects/win32diskimager/). Truncate the
|
||||
image file to the calculated total size:
|
||||
|
||||
```
|
||||
root@beaglebone:/home/debian# truncate -s 7520387072 myimage.img
|
||||
```
|
||||
|
||||
Copy the truncated image file to other SD cards for distribution.
|
||||
Reference in New Issue
Block a user