Linux Distributions for Beagle Boards

There are many different distributions of Linux for embedded system platforms, including expensive proprietary versions for real-time programming. At their heart, they all use the mainline Linux kernel, but each distribution contains different tools and configurations that result in quite different user experiences. The main open-source distributions used by the community on the Beagle boards include Debian, Ångström, Ubuntu, and Arch Linux.

Debian (a contraction of “Debbie and Ian”) is a community-driven Linux distribution that has an emphasis on open-source development. There is no commercial organization involved in the development of Debian; in fact, there is a formal social contract (tiny.cc/beagle201) that states that Debian will remain entirely free (as in software freedom). The Debian distribution is used for many of the practical steps in this book; in fact, it is recommended as the distribution of choice for the Beagle boards, and it is currently distributed with new BeagleBone boards. In addition, Debian is used throughout this book as the distribution for the Linux desktop computer, as it provides excellent support for cross-platform development through Debian Cross-Toolchains (see wiki.debian.org/CrossToolchains). Currently, there are different versions of Debian available for download from the BeagleBoard.org website.

• Debian Stretch LXQt, which has the Lightweight Qt Desktop (LXQt) environment installed. This version should be used if you are attaching the board to a monitor or an LCD panel.
• Debian Stretch IoT, which is a headless image that has a much smaller footprint on the micro-SD card and (of greater consequence) the eMMC of a BeagleBone.

Ångström is a stable and lean Linux distribution that is widely used on embedded systems. The team of developers behind Ångström is experienced in customizing Linux distributions for embedded devices such as set-top boxes, mobile devices, and networking devices. Impressively, Ångström can scale down to devices with only megabytes of flash storage. Ångström makes extensive use of BusyBox, a multicall binary (a single executable that can do the job of many) used to create a compact version of command-line utilities that are found on Linux systems. Many of my YouTube videos use Ångström, as it was the primary distribution for the BeagleBone for quite some time.

Ubuntu is closely related to Debian; in fact, it is described on the Ubuntu website (www.ubuntu.com) as follows: “Debian is the rock upon which Ubuntu is built.” Ubuntu is one of the most popular desktop Linux distributions, mainly because of its focus on making Linux more accessible to new users. It is easy to install and has excellent desktop driver support, and there are binary distributions available for the Beagle boards.

Arch Linux is a lightweight and flexible Linux distribution that aims to “keep it simple,” targeting competent Linux users in particular by giving them complete control and responsibility over the system configuration. There are prebuilt versions of the Arch Linux distribution available for the Beagle boards; however, compared to the other distributions, it currently has less support for new Linux users (see www.archlinux.org).

Create a Linux Micro-SD Card Image

The easiest way to set up an SD card so that it can be used to boot the PocketBeagle or other Beagle boards is to download a Linux distribution image file (.img file in a compressed .xz wrapper) from beagleboard.org/latest-images and write it to an SD card using an image writer utility such as Etcher (etcher.io). Etcher is particularly useful because it can use the compressed image file directly. The application is available for Windows, Mac, and Linux host machines.

Installing Drivers

Follow the steps in the guide displayed in Figure 2-1. With the latest Beagle board Linux images you should no longer have to install drivers for your operating system. If you have an older image and need to install drivers, browse to the Drivers folder and install the correct version. Once the board is fully booted, several new devices should be available on your desktop computer. For example, you will now have the following devices:

• Access to the FAT partition of the board (like a USB memory key).
• Serial access to the board using a new Gadget Serial driver COM port.
• A Linux USB Ethernet/RNDIS Gadget (for internet-over-USB). RNDIS stands for Remote Network Driver Interface Specification.

These new devices can be used to connect to the board. As you progress through the guide while the board is attached to your PC, the guide will highlight active connections, as illustrated in Figure 2-2. Similar steps for Linux and Mac desktop computers are available in the startup guide.

Wired Network Connections

There are three main ways to connect to and communicate with the board over a wired network, each with its own advantages and disadvantages. The first way is to use internet-over-USB, which creates a “private” virtual LAN using a single USB cable. This approach works for all Beagle boards, but the following approaches require a board that has an Ethernet adapter. The second way is to use regular Ethernet, and the third is to use an Ethernet crossover cable. Connecting to the board over a network can be a stumbling block for beginners. It is usually straightforward if you are working at home with control of your own network; however, complex networks, such as those in universities, can have multiple subnets for wired and wireless communication. In such complex networks, routing restrictions may make it difficult, if not impossible, to connect to the board over regular Ethernet.

Internet-over-USB (All Boards)

The standard BeagleBoard.org Linux distributions provide support for internet-over-USB using the Linux USB Ethernet/RNDIS Gadget device. For new users and for users within complex network infrastructures, this is probably the best way to get started with your board. For this setup you need only the board, a USB cable, and access to a desktop computer, ideally with administrator access levels. Table 2-1 describes the advantages and disadvantages of internet-over-USB for connecting to a board.

ADVANTAGES	DISADVANTAGES
Provides a stable network setup for beginners.	Without significant effort, you are limited to a single board per desktop.
When you do not have access to, or control of, network infrastructure hardware, you can still connect the board to the internet.	Network sharing configuration can be difficult, especially on Macintosh desktop computers. Additional configuration must also be performed on the board's Linux OS.
Power is supplied by your desktop machine over USB.	Your desktop machine must be running to transfer data to/from the internet.

For example, if you fully installed the board drivers under Windows, you should now have a new network connection (click Start, type view network status and tasks, and select “Change adapter settings”). Figure 2-3 shows a typical Network Connections window under Windows. In this case, “Ethernet 3” is the Linux USB Ethernet/RNDIS Gadget device. The desktop computer remains connected to your regular LAN (via Ethernet 2 in my case), which provides access to the internet and to a new private LAN that contains only the desktop computer (e.g., 192.168.7.1) and your board (e.g., 192.168.7.2). You can open a web browser and connect to the board's web server by typing 192.168.7.2 (or 192.168.6.2 on a Mac/Linux machine) in the address bar, as illustrated in Figure 2-3.

At this point, you can connect to the board's web server using a web browser so you have a fully functional private network; however, you may also want the board to have full direct access to the internet so that you can download files and update Linux software directly on the board. To do this, you need to share your main network adapter so that traffic from the board can be routed through your desktop machine to the internet. For example, under Windows, use the following steps:

1. Choose your desktop/laptop network adapter that provides you with internet access. Right-click it and choose Properties.
2. In the dialog that appears, as shown on the left side of Figure 2-4, click the Sharing tab at the top and enable the option “Allow other network users….”
3. In the drop-down list, choose your private LAN (e.g., referring to Figure 2-4, this is “Ethernet 3” in my case). Click OK.
4. Right-click the private LAN (e.g., Ethernet 3) and select Properties.
5. Double-click Internet Protocol Version 4. In this dialog, select “Obtain an IP address automatically” and enable “Obtain DNS server address automatically” (see Figure 2-4 on the right side).
6. Click OK and then Close to save the configurations.

The steps are similar under macOS using Apple Menu → System Preferences → Sharing. If all goes well, you will not have noticed any difference at this point, and you should be able to reload the web page that is shown in Figure 2-3. It can take about one minute for the network configuration to finalize. Please note that the impact of the last two steps can be appreciated only when you open a terminal connection to the board.

Communicating with Your Board

Once you have networked the board, the next thing you will want to do is communicate with it. You can connect to the Beagle board using either a serial connection over USB, USB-to-TTL, or a network connection, such as that just discussed. The network connection should be your main focus, as that type of connection provides your board with full internet access. The serial connection is generally used as a fallback connection when problems arise with the network connection. As such, you may skip the next section, but the information is here as a reference for when problems arise.

Serial Connection over USB

If you installed the device drivers for the Beagle board in the previous section, the Gadget Serial device will allow you to connect to the board directly using a terminal emulator program. Serial connections are particularly useful when the board is close to your desktop computer and connected via the USB cable. It is often a fallback communications method when something goes wrong with the network configuration or software services on the board.

To connect to the board via the serial connection, you need a terminal program. Several third-party applications are available for Windows, such as RealTerm (realterm.sourceforge.io) and PuTTY (www.putty.org). PuTTY is also used in the next section. Most distributions of desktop Linux include a terminal program (try Ctrl+Alt+T or use Alt+F2 and type gnome-terminal under Debian). A terminal emulator is included by default under macOS (e.g., type screen/dev/tty.usbmodemfa133 115200).

To connect to the Beagle board over the USB serial connection, you need to know some information.

• COM port number: You can find this by opening the Windows Device Manager and searching under the Ports section. Figure 2-5 captures an example Device Manager, where the Gadget Serial device is listed as COM3. This will be different on different machines.
• Speed of the connection: By default you need to enter 115,200 baud to connect to the board.
• Other information you may need for other terminal applications: Data bits = 8; Stop bits = 1; Parity = none; and, Flow control = XON/XOFF.

Save the configuration with a session name so that it is available each time you want to connect. Click Open, and it is important that you press Enter when the window appears. When connecting to Debian, you should see the following output:

Debian GNU/Linux 9 beaglebone ttyGS0
 
BeagleBoard.org Debian Image 2018-03-05
Support/FAQ: http://elinux.org/Beagleboard:BeagleBoneBlack_Debian
default username:password is [debian:temppwd]
beaglebone login: debian
Password: temppwd
debian@beaglebone:~$ 

This allows you to log in with username debian and password temppwd.

On a Linux desktop computer, you can install the screen program and connect to the serial-over-USB device with these commands:

molloyd@debian:~$ sudo apt-get install screen
molloyd@debian:~$ screen /dev/ttyUSB0/ 115200 

U-Boot SPL 2018.01-00002-ge9ff418fb8 (Feb 20 2018 - 20:14:57)
Trying to boot from MMC1
U-Boot 2018.01-00002-ge9ff418fb8 (Feb 20 2018 - 20:14:57 -0600), 
Build: jenkins-github_Bootloader-Builder-38
CPU  : AM335X-GP rev 2.1
I2C:   ready
DRAM:  512 MiB
…
Model: BeagleBoard.org PocketBeagle
… 

Secure Shell Connections Using PuTTY

PuTTY (www.putty.org) was mentioned earlier as a way of connecting to your board using serial-over-USB. PuTTY is a free, open-source terminal emulator, serial console, and SSH client that you can also use to connect to the board over the network. PuTTY has a few useful features.

• It supports serial and SSH connections.
• It installs an application called psftp that enables you to transfer files to and from the Beagle board over the network from your desktop computer.
• It supports SSH X11 forwarding, which is required in Chapter 13.

Figure 2-6 captures the PuTTY Configuration settings. Choose SSH as the connection type, enter the IP address for your board (192.168.7.2 or 192.168.6.2 if you are using internet-over-USB), use port 22 (the default), and then save the session with a useful name for future use. Click Open and log in using your username and password. You may get a security alert that warns about man-in-the-middle attacks, which may be a concern on insecure networks. Accept the fingerprint and continue. macOS and Linux users can run the Terminal application with similar settings (e.g., ssh -X [email protected]).

You will see the basic Linux commands that can be issued later in this chapter, but first it is necessary to examine how you can transfer files to and from the board.

Chrome Apps: Secure Shell Client

The Chrome web browser has support for Chrome extensions—applications that behave like locally installed (or native) applications but are written in HTML5, JavaScript, and CSS. Many of these applications use Google's Native Client (NaCl, or Salt!), which is a sandbox for running compiled C/C++ applications directly in the web browser, regardless of the OS. The benefit of NaCl is that applications can achieve near-native performance levels, as they can contain code that uses low-level instructions.

There is a useful Chrome extension called Secure Shell Extension available. Open a new tab on the Chrome browser and click the Apps icon. Go to the Chrome Web Store and search the store for Secure Shell. Once it is installed, it will appear as the Secure Shell App when you click the Apps icon again. When you start up the Secure Shell App, you will have to set the connection settings as in Figure 2-6, and the application will appear as in Figure 2-7.

Transferring Files Using PuTTY/psftp over SSH

The PuTTY installation also includes File Transfer Protocol (ftp) support that enables you to transfer files to and from your board over your network connection. You can start up the psftp (PuTTY secure file transfer protocol) application by typing psftp in the Windows Start command text field.

At the psftp> prompt, you can connect to the board by typing open [email protected] (e.g., the board address for internet-over-USB on a Windows PC). Your desktop machine is now referred to as the local machine, and the Beagle board is referred to as the remote machine. When you issue a command, you are typically issuing it on the remote machine. After connecting, you are placed in the home directory of the user account you used. Therefore, under the Debian distribution, if you connect as the user debian, you are placed in the /home/Debian/ directory.

To transfer a single file c: emp est.txt from the local desktop computer to the Beagle board, you can use the following steps:

psftp: no hostname specified; use "open host.name" to connect
psftp> open [email protected]
Using username "debian".
Remote working directory is /home/debian
psftp> lcd c:	emp
New local directory is c:	emp
psftp> mkdir test
mkdir /home/debian/test: OK
psftp> put test.txt
local:test.txt => remote:/home/debian/test.txt
psftp> dir test.*
Listing directory /home/debian
-rw-r--r--    1 debian   debian          0 Apr  5 00:46 test.txt 

Commands that are prefixed with an l refer to commands issued for the local machine, e.g., lcd (local change directory) or lpwd (local print working directory). To transfer a single file, the put command is issued, which transfers the file from the local machine to the remote machine. The get command can be used to transfer a file in reverse. To “put” or “get” multiple files, you can use the mput or mget command. Use help if you have forgotten a command.

There are free GUI-based SFTP applications available for Windows, such as WinSCP, which is displayed in Figure 2-8. It can be downloaded for free from winscp.net. Alternatives include FileZilla (filezilla-project.org) and Cyberduck (cyberduck.io) for Windows and Mac.

If you are using a Linux client machine, you can use the command sftp instead of psftp. Almost everything else remains the same. The SFTP client application is also installed on the BeagleBoard.org Linux distribution by default, so you can reverse the order of communication, that is, having the board act as the client and another machine as the server.

Here are some useful hints and tips with the psftp/sftp commands:

• mget -r * will perform a recursive get of a directory. This is useful if you want to transfer a folder that has several subfolders. The -r option can also be used on the get, put, and mput commands.
• dir *.txt will apply a filter to display only the .txt files in the current directory.
• mv can be used to move a file/directory on the remote machine to a new location on the remote machine.
• reget can be used to resume a download that was interrupted. The partially downloaded file must exist on the local machine.

Basic Linux Commands

When you first connect to the board with SSH, you are prompted to log in. Under Debian, you can log in with username debian and password temppwd.

login as: debian
[email protected]'s password: temppwd
Linux beaglebone 4.9.82-ti-r102 #1 SMP PREEMPT Thu Feb 22 01:16:12 UTC 
2018 armv7l The programs included with the Debian GNU/Linux system are 
free software; the exact distribution terms for each program are 
described in the individual files in /usr/share/doc/*/copyright.
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Thu Apr  5 00:08:01 2018 from 192.168.7.1
debian@beaglebone:~$ 

You are now connected to the board, and the Linux terminal is ready for your command. The $ prompt means you are logged in as a regular user account (superusers have a # prompt). For a new Linux user, this step can be quite daunting, as it is not clear what arsenal of commands is at your disposal. This section provides you with sufficient Linux skills to get by. It is written as a reference with examples so that you can come back to it when you need help. Some of the commands used are described in more detail in Chapter 3.

debian@beaglebone:~$ uname -a
Linux beaglebone 4.9.82-ti-r102 #1 SMP PREEMPT Thu Feb 22 01:16:12 UTC 
2018 armv7l GNU/Linux
debian@beaglebone:~$ cat /etc/dogtag
BeagleBoard.org Debian Image 2018-03-05 

debian@beaglebone:~$ passwd
Changing password for debian.
(current) UNIX password: temppwd
Enter new UNIX password: newpasswd
Retype new UNIX password: newpasswd
passwd: password updated successfully 

debian@beaglebone:~$ cd ~/
debian@beaglebone:~$ pwd
/home/debian
debian@beaglebone:~$ mkdir test
debian@beaglebone:~$ cd test
debian@beaglebone:~/test$ touch hello.txt
debian@beaglebone:~/test$ ls
hello.txt
debian@beaglebone:~/test$ cd ..
debian@beaglebone:~$ cp -r test /tmp
debian@beaglebone:~$ cd /tmp/test/
debian@beaglebone:/tmp/test$ ls -l
total 0
-rw-r--r-- 1 debian debian 0 Apr  5 00:50 hello.txt 

debian@beaglebone:~$ env
…
USER=debian
PWD=/home/debian
HOME=/home/debian
SSH_CLIENT=192.168.7.1 6233 22
SSH_TTY=/dev/pts/0
PATH=/home/debian/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:
/sbin:/bin:/usr/local/games:/usr/games
… 

debian@beaglebone:~$ echo $PATH
/home/debian/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
:/sbin:/bin:/usr/local/games:/usr/games
debian@beaglebone:~$ export PATH=$PATH:~/temp
debian@beaglebone:~$ echo $PATH
/home/debian/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
:/sbin:/bin:/usr/local/games:/usr/games:/home/debian/temp 

Basic File Editing

A variety of editors are available, but perhaps one of the easiest to use for new users is also one of the most powerful—the GNU nano editor. You can start up the editor by typing nano followed by the name of an existing or new filename; for example, typing nano hello.txt will display the view captured in Figure 2-9 (after the text has been entered!). Typing nano -c hello.txt will also display line numbers, which is useful when debugging program code. You can move freely around the file in the window using the arrow keys and edit or write text at the cursor location. You can see some of the nano shortcut keys listed on the bottom bar of the editor window, but there are many more, some of which are presented in Table 2-7.

What Time Is It?

A simple question like this causes more difficulty than you can imagine. If you type date at the shell prompt, you may get the following:

debian@beaglebone:~$ date
Thu Apr  5 01:06:59 UTC 2018 

which is months out-of-date in this case, even where the board is connected to the desktop PC using an internet-over-USB connection. However, it is likely that the date and time are correct if you are connected via “regular” Ethernet.

If it is wrong, why did the BeagleBoard.org team not set the clock time on your board? The answer is that they could not. Unlike a desktop PC, there is no battery backup on the board to ensure that the BIOS/UEFI settings are retained—in fact, there is no BIOS or UEFI! That topic is examined in detail in the next chapter, but for the moment you need a way to set the time, and for that you can use the Network Time Protocol (NTP). The NTP is a networking protocol for synchronizing clocks between computers. If your board has the correct time, that is only because it is obtaining it from your network. On recent Debian images this is performed by a systemd special unit.

root@beaglebone:~# systemctl status time-sync.target
• time-sync.target - System Time Synchronized
   Loaded: loaded (/lib/systemd/system/time-sync.target; static; 
   vendor preset: enabled)
   Active: active since Sun 2018-04-22 23:51:53 IST; 19min ago 

If the time is incorrect, it is most likely the case that you do not have internet access. Please see the following feature, “Internet-over-USB Network Settings.”

Once the time is correct, use the following command, which provides a text-based user interface that allows you to choose your location. The board is now set for Irish standard time (IST) in this example.

debian@beaglebone:~$ sudo dpkg-reconfigure tzdata
Current default time zone: 'Europe/Dublin'
Local time is now:      Mon Apr 23 00:06:21 IST 2018.
Universal Time is now:  Sun Apr 22 23:06:21 UTC 2018. 

Package Management

At the beginning of this chapter, a good package manager is listed as a key feature of a suitable Linux distribution. A package manager is a set of software tools that automate the process of installing, configuring, upgrading, and removing software packages from the Linux operating system. Different Linux distributions use different package managers: Ångström uses OPKG, Ubuntu and Debian use APT (Advanced Packaging Tool) over DPKG (Debian Package Management System), and Arch Linux uses Pacman. Each has its own usage syntax, but their operation is largely similar. For example, the first row in Table 2-8 lists the command for installing a package using different managers. The table also lists other package management commands that can be used.

You should update the package lists at regular intervals (the sudo password is your Debian account password) using the apt update command. A call to apt update downloads the package lists from the internet locations identified in the file /etc/apt/sources.list. This does not install new versions of the software; rather, it updates the lists of packages and their interdependencies.

debian@beaglebone:~$ sudo apt update
[sudo] password for debian:
Ign:1 http://deb.debian.org/debian stretch InRelease
…
Get:14 http://repos.rcn-ee.com/debian stretch/main armhf Packages [516 kB]
Fetched 10.7 MB in 11s (896 kB/s)
Reading package lists… Done
Building dependency tree
Reading state information… Done
75 packages can be upgraded. Run 'apt list --upgradable' to see them.
debian@beaglebone:~$ sudo apt list --upgradable
Listing… Done
apache2/stable 2.4.25-3+deb9u4 armhf [upgradable from: 2.4.25-3+deb9u3]
…  

Once this is complete, you can automatically download and install the latest versions of the available software using the apt upgrade command. Clearly, you should always perform an apt update command before an apt upgrade. Please be aware that some of these steps (upgrade in particular) can take quite some time to complete—perhaps even several hours, depending on the currency of your image and the speed of your network connection.

Wavemon is a useful tool that you can use in configuring Wi-Fi connections (see Chapter 12). If you execute the command, you will see that the package is not installed.

debian@beaglebone:~$ wavemon
-bash: wavemon: command not found 

The platform-specific (Debian in this case) package manager can be used to install the package, once you determine the package name.

debian@beaglebone:~$ apt search wavemon
Sorting… Done … Full Text Search… Done
wavemon/stable 0.8.1-1 armhf
 Wireless Device Monitoring Application
debian@beaglebone:~$ sudo apt install wavemon
Reading package lists… Done
…
Setting up wavemon (0.8.1-1) … 

The wavemon command now executes, but unfortunately it will not do anything until you configure a wireless adapter (see Chapter 12).

debian@beaglebone:~$ wavemon
wavemon: no supported wireless interfaces found! Check manpage for help. 

Beagle-Specific Commands

There are Beagle-specific tools available for configuring your board that have been developed by the BeagleBoard.org community. These tools simplify some tasks that would otherwise be quite difficult. They are located in the /opt/scripts/tools directory and are described in this section. Before you use the tools, check that you have the latest versions.

debian@beaglebone:~$ cd /opt/scripts/tools/
debian@beaglebone:/opt/scripts/tools$ git pull || true
Already up-to-date.
debian@beaglebone:/opt/scripts/tools$ ls
beaglebone-black-eMMC-flasher.sh  grow_partition.sh     update_kernel.sh
developers                        init-eMMC-flasher.sh  version.sh
dtc                               non-mmc-rootfs        wm
eMMC                              readme.txt
graphics                          software 

debian@beaglebone:~$ lsblk
NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
mmcblk0     179:0    0 29.8G  0 disk
└_mmcblk0p1 179:1    0  3.3G  0 part /
debian@beaglebone:~$ df -k
Filesystem     1K-blocks    Used Available Use% Mounted on
udev              219844       0    219844   0% /dev
tmpfs              49624    4972     44652  11% /run
/dev/mmcblk0p1   3357264 1684596   1482412  54% /
… 

debian@beaglebone:/opt/scripts/tools$ sudo ./grow_partition.sh
Media: [/dev/mmcblk0]
sfdisk: 2.26.x or greater
Disk /dev/mmcblk0: 29.8 GiB, 32010928128 bytes, 62521344 sectors
…
debian@beaglebone:/opt/scripts/tools$ sudo reboot 

debian@beaglebone:~$ lsblk
NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
mmcblk0     179:0    0 29.8G  0 disk
└_mmcblk0p1 179:1    0 29.8G  0 part /
debian@beaglebone:~$ sudo apt upgrade
debian@beaglebone:~$ df -k
Filesystem     1K-blocks    Used Available Use% Mounted on
udev              219332       0    219332   0% /dev
tmpfs              49520    5012     44508  11% /run
/dev/mmcblk0p1  30707172 1953168  27455072   7% / 

debian@beaglebone:~$ uname -a
Linux beaglebone 4.9.82-ti-r102 #1 SMP PREEMPT Thu Feb 22 01:16:12 UTC 2018
armv7l GNU/Linux
debian@beaglebone:~$ cd /opt/scripts/tools/
debian@beaglebone:/opt/scripts/tools$ sudo ./update_kernel.sh
…
Kernel version options:
-----------------------------
LTS44: --lts-4_4
LTS49: --lts-4_9
LTS414: --lts-4_14
STABLE: --stable
TESTING: --testing
info:you are running:[4.9.82-ti-r102],latest is:[4.9.88-ti-r111] updating…
debian@beaglebone:~$ sudo reboot
debian@beaglebone:~$ uname -a
Linux beaglebone 4.9.88-ti-r111 #1 SMP PREEMPT Sun Apr 22 2018 armv7l GNU/Linux 

/opt/scripts/tools$ sudo ./update_kernel.sh --ti-rt-channel --lts-4_14
/opt/scripts/tools$ sudo reboot
debian@beaglebone:~$ uname -a
Linux beaglebone 4.14.35-ti-rt-r44 #1 SMP PREEMPT RT Sun Apr 22 06:04:23  

Interacting with the On-Board LEDs

In this section, you are going to examine how you can change the behavior of the Beagle board on-board user LEDs—the four blue LEDs that are grouped together on the boards. Each LED can provide information about the board's state.

• USR0 flashes in a heartbeat sequence, indicating the board is alive.
• USR1 flashes during micro-SD card activity.
• USR2 flashes depending on the level of CPU activity.
• USR3 flashes during eMMC activity (set to do nothing by default on the PocketBeagle).

You can change the behavior of these LEDs to suit your own needs, but you will temporarily lose this useful activity information.

Sysfs is a virtual file system that is available under recent Linux kernels. It provides you with access to devices and drivers that would otherwise be accessible only within a restricted kernel space. This topic is discussed in detail in Chapter 6; however, at this point, it would be useful to briefly explore the mechanics of how sysfs can be used to alter the behavior of the user LEDs.

Using your SSH client, you can connect to the board and browse to the directory /sys/class/leds/. The output is as follows:

debian@beaglebone:~$ cd /sys/class/leds
debian@beaglebone:/sys/class/leds$ ls
beaglebone:green:usr0  beaglebone:green:usr2
beaglebone:green:usr1  beaglebone:green:usr3 

You can see the four (green!) LED sysfs mappings—usr0, usr1, usr2, and usr3. You can change the directory to alter the properties of one of these LEDs—for example, usr3 (use the Tab key to reduce typing).

debian@beaglebone:/sys/class/leds$ cd beaglebone:green:usr3
debian@beaglebone:/sys/class/leds/beaglebone:green:usr3$ ls
brightness  device  max_brightness  power  subsystem  trigger  uevent 

Here you see various different file entries that give you further information and access to settings. Please note that this section uses some commands that are explained in detail in the next chapter.

You can determine the current status of an LED by typing the following:

/sys/class/leds/beaglebone:green:usr3$ cat trigger
[none] rc-feedback rfkill-any kbd-scrolllock kbd-numlock kbd-capslock 
kbd-kanalock kbd-shiftlock kbd-altgrlock kbd-ctrllock kbd-altlock 
kbd-shiftllock kbd-shiftrlock kbd-ctrlllock kbd-ctrlrlock usb-gadget 
usb-host mmc0 timer oneshot disk-activity ide-disk mtd nand-disk 
heartbeat backlight gpio default-on panic 

where you can see that the USR3 LED is not currently configured for any particular function (i.e., [none]). If it happens to be configured on your board, you can set it to none, as follows:

/sys/class/leds/beaglebone:green:usr3$ echo none > trigger 

You can turn the USR3 LED fully on or off using this:

/sys/class/leds/beaglebone:green:usr3$ echo 1 > brightness
/sys/class/leds/beaglebone:green:usr3$ echo 0 > brightness 

You can even set the LED to flash at a time interval of your choosing. If you watch carefully, you will notice the dynamic nature of sysfs. If you perform an ls command at this point, the directory will appear as follows but will shortly change:

/sys/class/leds/beaglebone:green:usr3$ ls
brightness  device  max_brightness  power  subsystem  trigger  uevent 

To make the LED flash, you need to set the trigger to timer mode by typing echo timer > trigger. You will see the USR3 LED flash at a one-second interval. Notice that there are new delay_on and delay_off file entries in the beaglebone:green:usr3 directory, as follows:

/sys/class/leds/beaglebone:green:usr3$ echo timer > trigger
/sys/class/leds/beaglebone:green:usr3$ ls
brightness  delay_on  max_brightness  subsystem  uevent
delay_off   device    power           trigger 

The LED flash timer makes use of these new delay_on time and delay_off time file entries. You can find out more information about these values by using the concatenate (catenate) command. Here's an example:

/sys/class/leds/beaglebone:green:usr3$ cat delay_on
500 

This reports the time delay in milliseconds. To make the USR3 LED flash at 10 Hz (i.e., on for 50 ms and off for 50 ms), you can use the following:

debian@beaglebone:/sys/class/leds/beaglebone:green:usr3$ sudo -i
root@beaglebone:~# cd /sys/class/leds/beaglebone:green:usr3
root@beaglebone:/sys/class/leds/beaglebone:green:usr3# echo 50 > delay_on
root@beaglebone:/sys/class/leds/beaglebone:green:usr3# echo 50 > delay_off 

You need to use the root account to perform the preceding operation because the delay_on and delay_off entries are owned by root.

root@beaglebone:/sys/class/leds/beaglebone:green:usr3# ls -l delay*
-rw-r--r-- 1 root root 4096 Apr 24 02:08 delay_off
-rw-r--r-- 1 root root 4096 Apr 24 02:07 delay_on 

Typing echo none > trigger returns the LED to its default state on the PocketBeagle, which results in the delay_on and delay_off file entries disappearing.

Shutdown

One final issue to discuss in this section is the correct shutdown procedure for your board, as improper shutdown can potentially corrupt the ext4 file system and/or lead to increased boot times because of file system checks. Here are some important points on shutting down, rebooting, and starting your board:

• Typing sudo shutdown -h now shuts down the board correctly. You can delay this by five minutes by typing sudo shutdown -h +5.
• Typing sudo reboot will reset and reboot the board correctly.
• You can press the Power button (see Figure 1-4 and Figure 1-5) once to “soft” (as in software) shut down the board correctly.
• Holding the Power button for approximately eight seconds performs a hard system power down. This should be avoided unless the board is frozen and will not do a soft shutdown.
• Press the Power button to start the board. Try to avoid physically disconnecting and reconnecting the power jack or USB lead.

If your project design is enclosed and you need an external soft power down, it is possible to wire an external button to a GPIO input on the expansion header and write a shell script that runs on startup to poll the GPIO for an input. If that input occurs, then /sbin/shutdown -h now can be called directly.

Introduction to Node.js

Node.js is a platform for building network applications that uses the same JavaScript engine as the Google Chrome web browser. JavaScript is the programming language that is often used to create interactive interfaces within web pages. Simply put, Node.js is JavaScript on the server side. Its runtime environment and library of code enables you to run JavaScript code applications, without a browser, directly at the Linux shell prompt.

Node.js uses an event-driven, nonblocking input/output model. Event-driven programming is commonplace in user-interface programming. It essentially means that the program's flow of execution is driven by user actions or messages that are transferred from other threads or processes. Interestingly, the fact that it uses nonblocking I/O means that it is suitable for interfacing to the input/output pins on your board, safely sharing resources with other applications. As with all new languages, you should start with a “Hello World!” example. Listing 2-1 sends the string “Hello World!” to the standard output, which is typically a Linux terminal.

console.log("Hello World!"); 

Open an SSH connection to the board, create a directory to contain the HelloWorld.js file, and then enter the code from 1 using nano.

debian@beaglebone:~$ cd ~/
debian@beaglebone:~$ mkdir nodeTest
debian@beaglebone:~$ cd nodeTest/
debian@beaglebone:~/nodeTest$ nano HelloWorld.js 

To execute this code, type node HelloWorld.js in the directory containing the JavaScript file. You should see the following output:

debian@beaglebone:~/nodeTest$ ls
HelloWorld.js
debian@beaglebone:~/nodeTest$ node HelloWorld.js
Hello World! 

which should give you an idea of how you can write Node.js programs for the board. The call to the node command works because the Node.js runtime environment is preinstalled on the BeagleBoard.org Linux image.

Listing 2-2 provides a more complex Node.js example. It creates a web server that runs on the board at port 5050 and serves a simple “Hello World!” message. Write the program code in the same /nodeTest directory.

// A Simple Example Node.js Webserver Running on Port 5050
var http = require('http');  // require the http module
var server = http.createServer(
    function(req,res) {
        res.writeHead(200, {'Content-Type': 'text/plain'});
        res.end('Hello from the Beagle board!
');
    });
server.listen(5050);     
console.log('Beagle Web Server running at http://192.168.7.2:5050/'); 

The example code in Listing 2-2 begins by requiring the Node.js http module. It then calls the http.createServer() method, which returns an http.Server object. The server.listen() method is called on the http.Server object, where it causes the server to accept connections on a defined port number (i.e., 5050). This method is asynchronous, meaning it does not have to finish before the console.log() method is called on the next line. In fact, unless you kill the process on the board, the server.listen() method will listen forever. When a connection is made to port 5050, the server will call the listening function, function(req,res), to which is passed a copy of the HTTP request and response references. In this case, the function responds with a short plaintext message.

To execute this program, you type node SimpleWebServer.js in the directory containing the source code file, and you should get the following:

debian@beaglebone:~/nodeTest$ ls
HelloWorld.js  SimpleWebServer.js
debian@beaglebone:~/nodeTest$ node SimpleWebServer.js
Beagle Web Server running at http://192.168.7.2:5050/ 

where the output indicates that the server is running and listening on port 5050. You can then open a web browser and connect to this simple Node.js web server, where you will see the output, as shown in Figure 2-10. You can use Ctrl+C to kill the web server in the SSH window.

Introduction to the Cloud9 IDE

Wouldn't it be great if there were a way to integrate the development of Node.js code with the execution environment? That is where the Cloud9 IDE is useful. The Cloud9 integrated development environment (IDE) is an impressive web-based coding platform that supports many different programming languages, including JavaScript and Node.js. It enables you to write, run, and debug code directly within your web browser without installing any operating-system-specific tools or applications. If that is not impressive enough, the Cloud9 service has a low enough overhead to run directly on a Beagle board, and it comes preinstalled on the BeagleBoard.org Linux images.

To use the Cloud9 IDE, open Google Chrome or Firefox and connect to your board's address on port 3000. For example, open 192.168.7.2:3000 using the address bar, as shown in Figure 2-11. When you first open Cloud9, it provides an excellent introduction to the user interface and controls.

Rather than having to write the code on your desktop machine and transfer it to your board, the Cloud9 interface can save files directly on your board's Linux file system and can even execute them too. In Figure 2-11, a new .js file is created, which contains the code in Listing 2-2. You must save the file using File → Save. You can click the Run button to execute the application. If the Debugger window appears, click Resume. You can click the hyperlink in the output console, and the application output will be visible in the browser window that appears, as in Figure 2-11.

Remember that this SimpleWebServer.js program is running on the Beagle board itself. In fact, if you SSH into the board (or use the Cloud9 bash terminal window) and execute the following command (described in Chapter 3), you can see that the application process is running, as follows:

debian@beaglebone:~# ps aux|grep SimpleWebServer
debian 2157 0.3 2.2 … node … "/var/lib/cloud9/EBB/SimpleWebServer.js" … 

Clicking the Stop button in the Cloud9 IDE will kill this process.

Introduction to BoneScript

BoneScript is a library of Beagle-specific functionality that has been written for Node.js by BeagleBoard.org cofounder Jason Kridner. The BoneScript library provides the type of input/output functionality that would be familiar to Arduino users but with the advantage that it sits on top of the network capabilities of Node.js running on the Beagle platform. There are detailed descriptions of BoneScript and its functionality at beagleboard.org/support/bonescript.

You can use BoneScript to build a simple application to change the state of one of the system LEDs. The code in Listing 2-3 flashes the on-board USR3 LED, once every second, by utilizing the BoneScript library.

var b = require('bonescript'); // using BoneScript
var LED3Pin = "USR3";          // USR3 is D5 on the Beagle board
 
b.pinMode(LED3Pin, b.OUTPUT);  // set up LED3Pin as an output
var isOn = false;              // isOn will be a Boolean flag
setInterval(toggleLED, 500);   // each half second call toggleLED()
 
function toggleLED(){
   isOn = !isOn;              // invert the isOn state on each call
   if (isOn) b.digitalWrite(LED3Pin, 1);  // light the LED
   else b.digitalWrite(LED3Pin, 0);       // turn off the LED
   console.log('LED On is: ' + isOn);     // output the state
} 

This program requires the bonescript module, which is now referred to in the code as b—for example, by using b.someMethod(). Therefore, b.pinMode() uses the string literal "USR3" to identify the pin that is to be set to output mode. A temporary Boolean value isOn is used to retain the state of the LED in the code. The Node.js asynchronous global function setInterval() is set up to call the toggleLED() callback function every 500 ms. Each time the toggleLED() function is called, the isOn Boolean variable is inverted using the NOT operator (i.e., !true=false and !false=true). You set the LED pin to high if the value of isOn is true and to low if its value is false, and the state is outputted to the console.

This program can be executed directly within the Cloud9 IDE. However, it is important to remember that you can still run programs that include the BoneScript library calls directly at the Linux terminal prompt. Therefore, for example, executing the BlinkLED3.js code from the Cloud9 location on the Beagle board (as illustrated in Figure 2-12) will also work perfectly, flashing the USR3 LED once per second.

debian@beaglebone:/var/lib/cloud9/EBB$ ls
BlinkLED3.js  SimpleWebServer.js
debian@beaglebone:/var/lib/cloud9/EBB$ node BlinkLED3.js
LED On is: true
LED On is: false
LED On is: true
LED On is: false …

BoneScript is useful for the rapid prototyping of systems, particularly when those systems involve electronics that are to be connected to the internet. However, it is not ideal for high-performance large-scale applications—alternative languages and approaches are described throughout this book for such applications.