You're reading from BeagleBone: Creative Projects for Hobbyists Build amazing BeagleBone projects and maximize your skills with projects that walk, talk, and fly!

Product type Course

Published in Jul 2017

Publisher Packt

ISBN-13 9781788395656

Length 1020 pages

Edition 1st Edition

Languages

JavaScript

Tools

BeagleBone

Concepts

Robotics

Authors (3):

Rodolfo Giometti

Charles A. Hamilton

Richard Grimmett

View More author details

Table of Contents (6) Chapters

Preface

1. Module 1 FREE CHAPTER

2. Module 2

3. Module 3

Bibliography

Index

Chapter 7. Applied Recipes – Sound, Picture, and Video

In this chapter, we will cover the following recipes:

Wiring up a mini amp and speakers
Creating a high-quality audio platform with Volumio
Using videos and displays in projects
Testing a mini LCD cape
Making a video chat client prototype using Linphone

Introduction

We need to get a little dirtier. So far, we played it safe with physical computing recipes. But how far can you go by just plugging in some wires into a breadboard? To make the BBB a really useful tool, we have to heat up the iron—the soldering iron—and make some nice, shiny joints. Many great add-ons, such as PCBs, sensors, headers, and peripheral devices arrive at your doorstep unsoldered, full of fiddly bits, or just downright unsuitable out of the box. So, soldering is a must on the microcomputing landscape.

However, this is only one part of the picture for this chapter on picture, sound, and video. We will also explore different advanced methods to add a range of capes, PCB add-ons, and some USB devices for more complex recipes using digital sound, pictures, and video and look at the following:

Wiring up a mini sound amplifier and speakers
Creating a high-quality audio platform with Volumio
Using videos and displays in projects that include these devices:
- OLED PCB
- Mini LCD cape
Making a video chat client

Here's the truth about BeagleBone Black: when it comes to audio and video, the BBB is not for the faint-hearted. Other than a single USB port (which is obligatory for all kinds of reasons beyond just audio or video add-ons), the BBB is a tough system to learn for hardware and Linux newcomers. There is no onboard camera port; you have to piggyback on USB or buy a dedicated cape. There is no onboard audio I/O pin, USB device, or dedicated cape required either. So, if you are looking for a quick and easy, media-rich development box, then dare I say it: Raspberry Pi might be a better choice.

As a result of this difference, the BBB is often criticized for not being better at Rich Media. However, the difference is intentional; RPi's engineers intended to make an educational, hobbyist board with a desktop-like experience to encompass Rich Media use cases. On the other hand, the BBB's engineers designed their platform to create advanced prototypes for embedded applications where high-end graphics and sound are not commonly required.

With these caveats, BeagleBone Black still remains more than up to the challenge of delivering sound and picture in many, very useful scenarios, including streaming music and videos.

Bringing audio onto BeagleBone Black

The absence of onboard audio output or input is a real pain when it comes to the BBB. Yet, there are several methods of attacking this challenge. Firstly, you can go cheap and easy with a simple USB sound dongle; two varieties are shown in the following picture attached to a powered USB port:

Secondly, you can add a dedicated audio cape (as we did in Chapter 5, Basic Programming Recipes with the Linux Kernel). Thirdly, you can do it the hard(ish) way using a dedicated PCB and by piggybacking on the GPIO pins. Why bother with the latter? This is because using USB is often inadequate for certain applications. When you require faster, more RT-style performance, running audio packets across USB can be disappointing. We also want to stretch our limbs and add some complexity so that you have more types of technologies to draw upon in future projects and prototypes.

Wiring up a mini amp and speakers

To get some rocking audio going, we thought about wiring a BeagleBone Black up to a personal favorite device of ours: a c. 1960 Gruntal amplifier and radio:

We then thought better of it and decided to go with something a wee bit smaller for our recipe: the TPA2016 PCB, which contains a Texas Instruments chipset and is packaged as a final product by Adafruit:

It doesn't pack quite the volume as an ancient tube-based amp, but this surface-mount PCB amp is a heck of a lot handier and easier to use than our antique beauty. Also, it delivers nearly 3W of power for our tunes, plenty of volume for many situations. Additionally, its I2C interface allows us to control audio gain via software instead of using jumpers, switches, or other physical hardware.

In this recipe, you will learn how to set up and test the device on a breadboard with speakers and BeagleBone Black. Afterwards, in a later recipe, we'll use it as part of our kit to set up a listening library on the BBB.

I2C background and usage

I2C (pronounced "eye-squared-C" or "eye-two-see") is a hardware bus intended for motherboards and daughterboards to communicate easily. It is frequently leveraged in embedded applications and typically used in accelerometers, magnetometers, and other sensors, as well as other add-ons requiring low voltage. In our case, we will use it to run a very small audio amplifier.

Other than its power leads, the bus only uses two wires to communicate: SCL and SDA. The first one is the clock line, SCL, which is used to sync any data passing over the bus. The second line, SDA, carries the actual data. I2C also utilizes a simple master/slave relationship between devices, with the bus allowing the roles to be interchangeable. I2C is also good at noise filtering, which is a relevant feature for our recipe.

Working with I2C pins on the BBB is pretty straightforward. There are three I2C buses implemented on the BBB, but only one of these is easy to use:

I2C0: This is used for some onboard components, such as HDMI, EEPROM, and power management. If we disable it, it will interfere with these components, so it is typically not used unless needed.
I2C1: This is available for use but requires enabling.
I2C2: This is usable out of the box (Expansion port P9; refer to table 11 in the SRM). These are the pins that we will use.

Note

I2S bus

I2C should not be confused with Integrated Interchip Sound (I2S), another serial bus available on the BBB. Unlike I2C, which is bidirectional, I2S only handles data in one direction. Coincidentally, I2S is typically used as an interface to communicate PCM audio data between devices, commonly with a Digital to Analog Converter (DAC) audio device, though we will not use it in our audio recipes. There are several helpful tutorials on making a DAC, interface with I2S and connecting it to the BBB, such as the one at http://bit.ly/1HQMc1N.

Getting ready

Here are the materials we need:

PCB amp kit: This can be TPA2016 or similar. Adafruit has several choices, which you can access at https://www.adafruit.com/search?q=amplifier.
Speakers: You can use any set of speakers that take mono or stereo mini connector cables.
Audio input jack: Either one of the following two methods will work:
- 3.5mm Stereo Headphone Jack (breadboard-ready): This is very cheap and available at Sparkfun (https://www.sparkfun.com/products/8032) or Adafruit (https://www.adafruit.com/product/1699) for around USD $1.00.
- 3.5mm stereo plug to "pigtail" cable: This is basically a simple stereo mini cable using a standard plug on one end and a left and right speaker with wire-stripped "tinned" leads on the other. The leads break out, so you can plug them into a breadboard easily. It is cheap and available at Adafruit (https://www.adafruit.com/product/1700) for USD $1.95.
Mp3 or portable music player: This can be an iPod or smartphone with 3.5mm audio jack output and containing sample music or audio files.
2-plug (male) audio cable: A standard 3.5mm cable that you likely already have around the house.
Soldering iron
Lead-free solder
Mini Philips head screwdriver
Jumper wires
Breadboard

How to do it…

To prep the PCB amp, we followed some of the guidance provided by Adafruit's tutorial to work with their board (https://learn.adafruit.com/adafruit-tpa2016-2-8w-agc-stereo-audio-amplifier). Perform the following steps:

Your tasks begin with soldering an 8-pin header strip to the 8-holed side of the PCB amp and then soldering the speaker terminal blocks into the marked slots along the opposite side of the board. This is shown for you in the following image:
Note
This recipe is not a general how-to on soldering. If you have never soldered a wire or joint on a PCB, consult the following excellent tutorials:
How to Solder—Through-hole Soldering: https://learn.sparkfun.com/tutorials/how-to-solder---through-hole-soldering/
NYU's ITP soldering lesson: https://itp.nyu.edu/physcomp/Labs/Soldering
Adafruit's excellent guide to soldering: https://learn.adafruit.com/adafruit-guide-excellent-soldering
Instructable secrets of good soldering: http://www.instructables.com/id/How-to-solder-the-secrets-of-good-soldering/
After this, you can begin by inserting the long pins of a header strip with 8 pins into the breadboard, short pins sticking up, as shown in the following picture:
As it is important to get your PCB amp mounted on an even plane, the easiest way to do this is by using the leftover pins to support the board on the opposite edge. To clarify, these pins will not be soldered; they are only there for temporary support.
You then need to solder up the headers on the PCB amp, as you can see on the left-hand side in this picture. We used lead-free solder; so, when finished, the joints will look dull instead of the typically shiny cast from a well-poured leaded joint.
Solder the speaker terminal blocks to the PCB amp. Verify that your connections are solid. You may notice that the blocks don't sit neatly parallel to one another. This appears to be due to a slight design imperfection in the PCB amp, but there's nothing to worry about functionally.
Snip off the white connector that comes already attached to the ends of the speaker wires:
Following this, with a wire stripper, cut away the wire ends, as you can see in the following image:
Next, attach the finished PCB amp to a breadboard. Then, insert the speaker wires into the speaker terminal blocks. The black wires go into the (-) ground connectors, and the white wires into the (+) power connectors. Use a small Philips head screwdriver to first release tension in the block. Finish by tightening it after the wires are inserted. The end result is shown in this image:
Since we plan to use sound in this recipe—which is what an audio amplifier is good for—we need to also add some means for sound input. You can use either the breadboard-ready headphone jack, which you will see in the next picture, or the pigtail cable, as described at the beginning of this recipe.
Hook up your audio player to the other end of the audio cable. In our case, we used an old iPod that we had in a drawer. If you refer closely to the following image, it shows how all the parts should fit together before you have hooked it up to your BBB:
Choose an audio track on your player and press Play. Now that we know we have solid audio output with all hardware soldered, snipped, breadboarded, and wired properly, we will run an audio test using Python.

Now, we want to wire the amp up to our BeagleBone Black, following the Fritzing diagram. Although it looks like a thicket of mini jumper wires, the scheme is really simple. In fact, you will notice that on the BBB's GPIO pins, there are only two pins in use other than power and ground.

In case there is any uncertainty from the diagram, here is a table clarifying how to wire it up:

FUNCTION	BeagleBone Black	TPA2016 amplifier	Breadboard component
Power	P9_5 (5V) or P9_3 (3.3V)—5V for full capacity of the amp	VDD
Ground	P9_1	GND
I2C	P9_19 (SCL)	SCL
I2C	P9_20 (SDA)	SDA
Audio input—left speaker		L+	L+ on 3.5mm headphone jack
Audio input—right speaker		R+	R+ on 3.5mm headphone jack
Audio ground		L- to R-
Audio ground		R-	R- on 3.5mm headphone jack

Let's get programming! To start, open up the BoneScript IDE and create a new .py file called audio-amp-test1.py.
Download the Python script from our Github repo with following command:
```
$ git clone https://github.com/HudsonWerks/audio-amplifier.git
```
Browser to the audio-amplifier directory created and open up the python script in a nano window:
```
$ $ cd audio-amplifier
$ sudo nano audio-amp-test1.py
```
Now, copy and paste the code into the Cloud9 IDE window.
Restart a music track on your media player that, in our case, is an iPod. You should be able to hear the track playing through the speakers.
Now, click on the Run button on the Cloud9 IDE to test the script. Audio levels should shift up and down as you input the (+) or (-) sign at the command prompt.

Success (we hope)! Give yourself a high-five for getting dirtier with your board and adding some PCB add-ons to the mix.

Getting ready

Here are the materials we need:

PCB amp kit: This can be TPA2016 or similar. Adafruit has several choices, which you can access at https://www.adafruit.com/search?q=amplifier.
Speakers: You can use any set of speakers that take mono or stereo mini connector cables.
Audio input jack: Either one of the following two methods will work:
- 3.5mm Stereo Headphone Jack (breadboard-ready): This is very cheap and available at Sparkfun (https://www.sparkfun.com/products/8032) or Adafruit (https://www.adafruit.com/product/1699) for around USD $1.00.
- 3.5mm stereo plug to "pigtail" cable: This is basically a simple stereo mini cable using a standard plug on one end and a left and right speaker with wire-stripped "tinned" leads on the other. The leads break out, so you can plug them into a breadboard easily. It is cheap and available at Adafruit (https://www.adafruit.com/product/1700) for USD $1.95.
Mp3 or portable music player: This can be an iPod or smartphone with 3.5mm audio jack output and containing sample music or audio files.
2-plug (male) audio cable: A standard 3.5mm cable that you likely already have around the house.
Soldering iron
Lead-free solder
Mini Philips head screwdriver
Jumper wires
Breadboard

How to do it…

Your tasks begin with soldering an 8-pin header strip to the 8-holed side of the PCB amp and then soldering the speaker terminal blocks into the marked slots along the opposite side of the board. This is shown for you in the following image:
Note
This recipe is not a general how-to on soldering. If you have never soldered a wire or joint on a PCB, consult the following excellent tutorials:
How to Solder—Through-hole Soldering: https://learn.sparkfun.com/tutorials/how-to-solder---through-hole-soldering/
NYU's ITP soldering lesson: https://itp.nyu.edu/physcomp/Labs/Soldering
Adafruit's excellent guide to soldering: https://learn.adafruit.com/adafruit-guide-excellent-soldering
Instructable secrets of good soldering: http://www.instructables.com/id/How-to-solder-the-secrets-of-good-soldering/
After this, you can begin by inserting the long pins of a header strip with 8 pins into the breadboard, short pins sticking up, as shown in the following picture:
As it is important to get your PCB amp mounted on an even plane, the easiest way to do this is by using the leftover pins to support the board on the opposite edge. To clarify, these pins will not be soldered; they are only there for temporary support.
You then need to solder up the headers on the PCB amp, as you can see on the left-hand side in this picture. We used lead-free solder; so, when finished, the joints will look dull instead of the typically shiny cast from a well-poured leaded joint.
Solder the speaker terminal blocks to the PCB amp. Verify that your connections are solid. You may notice that the blocks don't sit neatly parallel to one another. This appears to be due to a slight design imperfection in the PCB amp, but there's nothing to worry about functionally.
Snip off the white connector that comes already attached to the ends of the speaker wires:
Following this, with a wire stripper, cut away the wire ends, as you can see in the following image:
Next, attach the finished PCB amp to a breadboard. Then, insert the speaker wires into the speaker terminal blocks. The black wires go into the (-) ground connectors, and the white wires into the (+) power connectors. Use a small Philips head screwdriver to first release tension in the block. Finish by tightening it after the wires are inserted. The end result is shown in this image:
Since we plan to use sound in this recipe—which is what an audio amplifier is good for—we need to also add some means for sound input. You can use either the breadboard-ready headphone jack, which you will see in the next picture, or the pigtail cable, as described at the beginning of this recipe.
Hook up your audio player to the other end of the audio cable. In our case, we used an old iPod that we had in a drawer. If you refer closely to the following image, it shows how all the parts should fit together before you have hooked it up to your BBB:
Choose an audio track on your player and press Play. Now that we know we have solid audio output with all hardware soldered, snipped, breadboarded, and wired properly, we will run an audio test using Python.

In case there is any uncertainty from the diagram, here is a table clarifying how to wire it up:

FUNCTION	BeagleBone Black	TPA2016 amplifier	Breadboard component
Power	P9_5 (5V) or P9_3 (3.3V)—5V for full capacity of the amp	VDD
Ground	P9_1	GND
I2C	P9_19 (SCL)	SCL
I2C	P9_20 (SDA)	SDA
Audio input—left speaker		L+	L+ on 3.5mm headphone jack
Audio input—right speaker		R+	R+ on 3.5mm headphone jack
Audio ground		L- to R-
Audio ground		R-	R- on 3.5mm headphone jack

Let's get programming! To start, open up the BoneScript IDE and create a new .py file called audio-amp-test1.py.
Download the Python script from our Github repo with following command:
```
$ git clone https://github.com/HudsonWerks/audio-amplifier.git
```
Browser to the audio-amplifier directory created and open up the python script in a nano window:
```
$ $ cd audio-amplifier
$ sudo nano audio-amp-test1.py
```
Now, copy and paste the code into the Cloud9 IDE window.
Restart a music track on your media player that, in our case, is an iPod. You should be able to hear the track playing through the speakers.
Now, click on the Run button on the Cloud9 IDE to test the script. Audio levels should shift up and down as you input the (+) or (-) sign at the command prompt.

Success (we hope)! Give yourself a high-five for getting dirtier with your board and adding some PCB add-ons to the mix.

How to do it…

Your tasks begin with soldering an 8-pin header strip to the 8-holed side of the PCB amp and then soldering the speaker terminal blocks into the marked slots along the opposite side of the board. This is shown for you in the following image:
Note
This recipe is not a general how-to on soldering. If you have never soldered a wire or joint on a PCB, consult the following excellent tutorials:
How to Solder—Through-hole Soldering: https://learn.sparkfun.com/tutorials/how-to-solder---through-hole-soldering/
NYU's ITP soldering lesson: https://itp.nyu.edu/physcomp/Labs/Soldering
Adafruit's excellent guide to soldering: https://learn.adafruit.com/adafruit-guide-excellent-soldering
Instructable secrets of good soldering: http://www.instructables.com/id/How-to-solder-the-secrets-of-good-soldering/
After this, you can begin by inserting the long pins of a header strip with 8 pins into the breadboard, short pins sticking up, as shown in the following picture:
As it is important to get your PCB amp mounted on an even plane, the easiest way to do this is by using the leftover pins to support the board on the opposite edge. To clarify, these pins will not be soldered; they are only there for temporary support.
You then need to solder up the headers on the PCB amp, as you can see on the left-hand side in this picture. We used lead-free solder; so, when finished, the joints will look dull instead of the typically shiny cast from a well-poured leaded joint.
Solder the speaker terminal blocks to the PCB amp. Verify that your connections are solid. You may notice that the blocks don't sit neatly parallel to one another. This appears to be due to a slight design imperfection in the PCB amp, but there's nothing to worry about functionally.
Snip off the white connector that comes already attached to the ends of the speaker wires:
Following this, with a wire stripper, cut away the wire ends, as you can see in the following image:
Next, attach the finished PCB amp to a breadboard. Then, insert the speaker wires into the speaker terminal blocks. The black wires go into the (-) ground connectors, and the white wires into the (+) power connectors. Use a small Philips head screwdriver to first release tension in the block. Finish by tightening it after the wires are inserted. The end result is shown in this image:
Since we plan to use sound in this recipe—which is what an audio amplifier is good for—we need to also add some means for sound input. You can use either the breadboard-ready headphone jack, which you will see in the next picture, or the pigtail cable, as described at the beginning of this recipe.
Hook up your audio player to the other end of the audio cable. In our case, we used an old iPod that we had in a drawer. If you refer closely to the following image, it shows how all the parts should fit together before you have hooked it up to your BBB:
Choose an audio track on your player and press Play. Now that we know we have solid audio output with all hardware soldered, snipped, breadboarded, and wired properly, we will run an audio test using Python.

In case there is any uncertainty from the diagram, here is a table clarifying how to wire it up:

FUNCTION	BeagleBone Black	TPA2016 amplifier	Breadboard component
Power	P9_5 (5V) or P9_3 (3.3V)—5V for full capacity of the amp	VDD
Ground	P9_1	GND
I2C	P9_19 (SCL)	SCL
I2C	P9_20 (SDA)	SDA
Audio input—left speaker		L+	L+ on 3.5mm headphone jack
Audio input—right speaker		R+	R+ on 3.5mm headphone jack
Audio ground		L- to R-
Audio ground		R-	R- on 3.5mm headphone jack

Let's get programming! To start, open up the BoneScript IDE and create a new .py file called audio-amp-test1.py.
Download the Python script from our Github repo with following command:
```
$ git clone https://github.com/HudsonWerks/audio-amplifier.git
```
Browser to the audio-amplifier directory created and open up the python script in a nano window:
```
$ $ cd audio-amplifier
$ sudo nano audio-amp-test1.py
```
Now, copy and paste the code into the Cloud9 IDE window.
Restart a music track on your media player that, in our case, is an iPod. You should be able to hear the track playing through the speakers.
Now, click on the Run button on the Cloud9 IDE to test the script. Audio levels should shift up and down as you input the (+) or (-) sign at the command prompt.

Success (we hope)! Give yourself a high-five for getting dirtier with your board and adding some PCB add-ons to the mix.

Creating a high-quality audio platform with Volumio

Volumio is a wonderful open source alternative to the iTunes straightjacket. For audiophile geeks who happen to be microcomputer or electronic geeks (you know who you are!) and RPi enthusiasts in particular, Volumio is well-known for its fastidiousness at serving up high-quality audio, be it web-based radio or high-resolution audio files. The system has now been ported to the BBB from its earlier incarnation as RaspyFi.

Essentially, Volumio leverages a Linux music server called Music Player Daemon (MPD). MPD provides a client environment with a web-centric GUI (sans plugins) and a robust networking architecture to serve your audio files.

One of the many appealing aspects of Volumio is that it is (nearly) file-agnostic, so you can play virtually any audio file type within the environment. For now, this includes FLAC, WAV, MP3, AAC, ALAC, M4A, and playlist (PLS) files.

Each new version of Volumio seems to leap forward in stability and ease of use. However, it does come with caveats as no open source tool is ever "finished." Volumio, in some respects, typifies the pleasures and perils of open source tools and bending them to your will on microcomputers. There's no out of the box perfection. Some of the recipes in this chapter use a number of "prepackaged" toolsets to get you where you want to be faster, and Volumio is still, technically, a beta release.

For example, other than a perfunctory setting up and installing procedure, developers do not have a nice handy set of obvious instructions. Instead, you have to spend a fair amount of time perusing their forum (volumio.org/forum/) to find answers to common questions.

Examples include: how do I SSH into Volumio? What's the password for remote login? How do I add a new internet radio station? Why is my external hard drive, which is chock-full with music files, not recognized by Volumio? How do I gracefully shut down my BBB if Volumio crashes? These are burning questions, indeed. Thankfully, you bought this book, so the answers to these questions are right here.

Getting ready

To get Volumio up and running, you need the following:

A USB-powered hub: As we need several USB devices to get the system operating reliably, you will need to add a powered hub to your configuration.
A keyboard: Plug one into the USB hub. We will use it for terminal access in case we lose or cannot get a remote SSH session and want to do a graceful shutdown of the system. However, we only need it temporarily and can disconnect it later.
An LCD Monitor: You need one of these plugged into the HDMI port. As with the keyboard, the monitor is only necessary for first boot and system tweaking.
Connectivity: We will first use an Ethernet cable plugged into the BBB for setup. After we've got a confirmed ping and stable setup, we will remove the cable and use a USB Wi-Fi dongle in our powered hub to establish a wireless environment.
Audio out: For output audio in this recipe, you can use three different methods—easy, intermediate, or advanced, which are as follows:
- Easy method—the USB audio dongle: There are numerous flavors of these devices in the wild. Unless you feel compelled to use an expensive one, they can be purchased cheaply; the kind pictured at the beginning of this chapter came for roughly USD $10.00. You should use a powered hub to supply power to the dongle instead of through the BBB's USB port.
- Intermediate method—the RevB audio cape: Although slightly more complex, using the audio cape that we already used in Chapter 4, Exploring GNU/Linux Recipes Using Bash, Autotools, Debugger, and systemd, is a more robust and elegant setup than using the USB audio dongle. Refer to the same chapter for cape setup and audio testing.
- Advanced method—the PCB audio amplifier (daughterboard): If you were with us in the previous section, we just did a recipe with this, and now, we can use it for real. Refer to the recipe mentioned before to set up this configuration, including the images and the Fritzing diagram.
Note
For audiophiles, one of the attractive features of Volumio is that it supports the use of DAC boxes. Although sexy, useful, and powerful, DAC boxes can be quite expensive. We don't have one, so we're not including the hookup methodology in this recipe. At Volumio's support forum (http://volumio.org/forum/), you will find ample discussion around using DAC boxes.
Speakers: Connect the speakers that you used in the prior recipe or use the audio out jack on a USB audio dongle.
Speaker cable: You can use mono or stereo jacks
Media storage: Audio files can be served from a variety of storage devices, such as USB, NAS, and so on. Since we had it on hand, we used a powered USB hard drive.

How to do it…

Now that you're ready, let's begin:

Start by downloading the Volumio BeagleBone Black disk image on your client machine (not your BBB). The current version is available at http://volumio.org/get-started/.
Following the download, extract the downloaded archive. You should end up with a .img file on your local box.
Insert an SD card reader with a minimum 4 GB microSD card installed. As Volumio claims to require a very minimal install (piggybacking on Debian Wheezy), you may be able to get away with a smaller amount of storage than 4 GB.
Flash the .img file to your SD card. As we are using a Mac box, we will use our trusty tool, PiFiller, which we used and explained in prior chapters. On a Windows box, you can use Win32DiskImager.
Confirm that you have adequate storage remaining on your SD card. To do this, run the check from a terminal window on your client machine with the following command:
```
$ df -ah
```
Your output should show somewhere around 22 percent capacity used.
From the preceding Getting ready section, you should have all the required hardware connected. Remove the SD card from your client machine, insert it in the BBB, and boot.
I have seen some flaky performances on first boot, so you may need to reboot again to get the login screen to appear. If you have used Volumio on Raspberry Pi, you will find booting up on the BBB considerably faster.
You now need to set up terminal access, first directly on the BBB and then remotely.
Technically, neither is a requirement to run Volumio as there's a lovely web-based GUI to control the tool; we'll get to that next. However, you will inevitably need to troubleshoot various issues, and terminal access is really the best way to do so. So, first type the following command on the BBB:
```
# user: root
pw: Volumio
```
You should now see the following screen output; date and version may vary, of course:
Now, repeat the previous step on your client desktop box for SSH access with the same user (root) and password (volumio) credentials:
```
$ ssh volumio@xxx.xxx.xx.xxx
```
If you have any problems logging in and you are on your own local LAN, you can also do the following:
```
$ ssh root@volumio.local
```
Check that you have a solid internet connection (from either your SSH remote session or directly on the BBB) by typing in:
```
# ping www.google.com
```
Your screen output should show stable ping responses. If it does not, you may need to reboot and repeat steps 7 through 10.
To quit the ping command, remember to press Ctrl + C on your keyboard.
We are not quite ready to play your fabulous music library, but we can do a test to get a quick feel-good hit. So, open up a browser on your desktop client and type in the address, http://volumio.local.
Voila! A fancy GUI with all kinds of knobs, buttons, and sliders appears!
Tip
One of the appealing things about Volumio is that its main controller is a web-based open source UI and not a bloated proprietary piece of software. This means that with a touch of HTML and a dash of jQuery, you can mod your own controller UI.
In the GUI, click on Browse | WEBRADIO. You will see a list of streaming radio stations that came preloaded with the install. Let's choose one that has a reliably consistent streaming URL: "the Beeb", which is also known as BBC World Radio.
After clicking twice on the link, the mellifluous sounds of a British newscaster will pour from your speakers.
Note
You may find that many of the preloaded WEBRADIO stations have outdated or nonfunctioning links, leading you to believe that your installation is not working properly. However, this is not the case; you simply need to fix or update the links manually.
Under the Playback tab, you will see a volume control akin to an iPod's "click wheel." Fiddle with it a bit, and you will notice that the volume level of the output doesn't change. Frustrating, right? This means that adjusting sound levels requires another tweak.
If you connected your system to DAC, ignore this step as you will have hardware controls to adjust the volume. Otherwise, go to MENU | SETTINGS, click on the dropdown for Volume Control, and select Software.
Following this, reboot using a terminal command or via the GUI underneath the MENU | SYSTEM tab.
Once rebooted, let's push the recipe a bit further by grabbing a couple of files remotely and loading them into Volumio. We will use the familiar wget command:
```
# wget http://hudsonwerks.com/beaglebone-black-recipes/downloads/volumio-sample-media.tar.gz
```
Untar the archived files with the following command:
```
# tar -zxvf volumio-sample-media.tar.gz
```

Use this command line to put the files in the correct Volumio directory:

# mv Space-Oddity-Hadfield-CLIP.m4a /var/lib/mpd/music/USB

Then, run the following:

# mv wbgo_jazzFM_NJ.pls /var/lib/mpd/music/WEBRADIO/

The media library now needs to be updated to reflect the new additions. So, via the Volumio web GUI on your desktop client, go to http://volumio.local.
Then, navigate to MENU | LIBRARY and click on the UPDATE LIBRARY button. At this point, if you have the media from this simple recipe, the update will take only a few seconds.
It's time to test our files; we will begin by using the m4a file. Again, on the web GUI, go to the Browse | USB tab. Then, click on Space-Oddity-Hadfield-CLIP twice.
You should hear a brief sample of a remix of David Bowie's song, "Major Tom", from the album, Space Oddity. In this case, it will be sung by US astronaut Chris Hadfield on board the International Space Station. It is a remake of a classic, but the astronaut does a great job of it.
Note
We would have preferred using the whole track, but we limited the length of the clip to conform to the Fair Use legal restrictions. For a longer version of the song, the video is available online at https://youtu.be/KaOC9danxNo.
Now, let's test our newly downloaded web radio station playlist. On the web interface, go to Browse | WEBRADIO. Then, click on wbgo_jazzFM_NJ.
With a nearly finished setup, we can cut the Ethernet cord and run Volumio via Wi-Fi. Go to Menu | Network and input your network's name and password in the appropriate fields. Then, click on Save Changes, and Volumio will reset the web interface.
Next, remove the Ethernet cable. If you do not already have it open, type in the Volumio server address, http://volumio.local, again on your desktop client browser.
You should be able to control Volumio fluidly now without the Ethernet connection.
Assuming you have a smartphone, pull it out and open up a browser to the same address that you just entered on your desktop: volumio.local.
Voila! You are now freed from the desktop and have remote control of your media library from any smartphone:
Although the Volumio interface can be a bit crowded on small smartphone screens, you should see a tighter, highly usable design on tablet clients.
Next, we need to check the version of Volumio. Doing this will output the compatible file types that the software can play:
```
# mpd --version
```
Tip
The screen output should yield not only the usual copyright boilerplate, but an extensive list of the audio file types that are playable with Volumio. Check that your music library's file types are in the list, particularly in the very lengthy [ffmpeg] section.
Next, you need to update the MPD database so that it catalogues all files on your attached storage drive. You can use the Volumio GUI for this; navigate to MENU | Library | Update MDB database. You can also do the same thing with the following command line:
```
# sudo service mpd restart
```
Depending on the size of your library and regardless of the method you use, the database update may take a while. So, get a cold drink, a sandwich, or go for a jog—a long one.
If all went as planned, your music library should now be catalogued. Go to Library, select the your USB music directory, and verify that everything's visible.
We also have a potential bug fix. Depending on your version of Volumio, this is where you may encounter some quirks. Because of a lingering bug in the in the last few versions of the MPD server environment (which is not Volumio's fault), many file types compatible with FFMPEG are disabled by default.
This means that the GUI-based update MDB database function that we just executed may capture some of the metadata for a music file, including its name, but not the actual media data itself. So, let's fix this in the command line as follows:
```
# nano /etc/mpd.conf
```
Scroll down to the FFMEG = disable line and change disable to enable. Following this, save the mpd.conf file and close it.
Now, let's test our media files via the GUI; go to Browse | USB, select your album or music track, and choose a favorite music file. (Note that it doesn't have to be a David Bowie track).

With all this done, we are left with one thing to do: turn it up to 11!

There's more…

Here is some supplementary information about playlists, which you can use to extend this recipe. As in most music library environments, Volumio uses playlists (.pls files) as a means to categorize or organize your media into custom play sequences. Here are two basic methods of adding playlists to Volumio:

The drag and drop method: With any .pls files you may have, simply drag and drop the file into your WEBRADIO folder.
Manual method: You may have already found that some of the default web radio stations listed don't work. There is a good chance that the problem is not your in hardware; it's more likely that the station's URL has changed, which is one of the vagaries of web radio. So, you will need to tweak the address in the playlist file. Here's what we do:
1. Open up a .pls file in a text editor. You can do this on your BBB or locally on your media library drive. The drive is connected to the server as a shared drive, so you should see it appear on your client box desktop. Here is what you should see when you open the file:
```
[playlist]
File1=http://xxx.yyy.zzz:port
Title1=station name
Length1=-1
Numberofentries=1
Version=2
```
2. We will typically modify two items in this file. First, we will use the following command to modify the web radio address:
```
File1=http://xxx.yyy.zzz:port
```
In this line, insert the URL of the stream you are adding; the port setting is optional. Here's an example:
```
File1=http:/ http://xstream1.somafm.com:8000
```
Then, we want the name of the station to appear in the Volumio player while the audio is streaming:
```
Title1=station name
```
For example, if we wanted to call our station Space Station Soma, we would run the following line:
```
Title1=Space Station Soma
```

Getting ready

To get Volumio up and running, you need the following:

A USB-powered hub: As we need several USB devices to get the system operating reliably, you will need to add a powered hub to your configuration.
A keyboard: Plug one into the USB hub. We will use it for terminal access in case we lose or cannot get a remote SSH session and want to do a graceful shutdown of the system. However, we only need it temporarily and can disconnect it later.
An LCD Monitor: You need one of these plugged into the HDMI port. As with the keyboard, the monitor is only necessary for first boot and system tweaking.
Connectivity: We will first use an Ethernet cable plugged into the BBB for setup. After we've got a confirmed ping and stable setup, we will remove the cable and use a USB Wi-Fi dongle in our powered hub to establish a wireless environment.
Audio out: For output audio in this recipe, you can use three different methods—easy, intermediate, or advanced, which are as follows:
- Easy method—the USB audio dongle: There are numerous flavors of these devices in the wild. Unless you feel compelled to use an expensive one, they can be purchased cheaply; the kind pictured at the beginning of this chapter came for roughly USD $10.00. You should use a powered hub to supply power to the dongle instead of through the BBB's USB port.
- Intermediate method—the RevB audio cape: Although slightly more complex, using the audio cape that we already used in Chapter 4, Exploring GNU/Linux Recipes Using Bash, Autotools, Debugger, and systemd, is a more robust and elegant setup than using the USB audio dongle. Refer to the same chapter for cape setup and audio testing.
- Advanced method—the PCB audio amplifier (daughterboard): If you were with us in the previous section, we just did a recipe with this, and now, we can use it for real. Refer to the recipe mentioned before to set up this configuration, including the images and the Fritzing diagram.
Note
For audiophiles, one of the attractive features of Volumio is that it supports the use of DAC boxes. Although sexy, useful, and powerful, DAC boxes can be quite expensive. We don't have one, so we're not including the hookup methodology in this recipe. At Volumio's support forum (http://volumio.org/forum/), you will find ample discussion around using DAC boxes.
Speakers: Connect the speakers that you used in the prior recipe or use the audio out jack on a USB audio dongle.
Speaker cable: You can use mono or stereo jacks
Media storage: Audio files can be served from a variety of storage devices, such as USB, NAS, and so on. Since we had it on hand, we used a powered USB hard drive.

How to do it…

Now that you're ready, let's begin:

Start by downloading the Volumio BeagleBone Black disk image on your client machine (not your BBB). The current version is available at http://volumio.org/get-started/.
Following the download, extract the downloaded archive. You should end up with a .img file on your local box.
Insert an SD card reader with a minimum 4 GB microSD card installed. As Volumio claims to require a very minimal install (piggybacking on Debian Wheezy), you may be able to get away with a smaller amount of storage than 4 GB.
Flash the .img file to your SD card. As we are using a Mac box, we will use our trusty tool, PiFiller, which we used and explained in prior chapters. On a Windows box, you can use Win32DiskImager.
Confirm that you have adequate storage remaining on your SD card. To do this, run the check from a terminal window on your client machine with the following command:
```
$ df -ah
```
Your output should show somewhere around 22 percent capacity used.
From the preceding Getting ready section, you should have all the required hardware connected. Remove the SD card from your client machine, insert it in the BBB, and boot.
I have seen some flaky performances on first boot, so you may need to reboot again to get the login screen to appear. If you have used Volumio on Raspberry Pi, you will find booting up on the BBB considerably faster.
You now need to set up terminal access, first directly on the BBB and then remotely.
Technically, neither is a requirement to run Volumio as there's a lovely web-based GUI to control the tool; we'll get to that next. However, you will inevitably need to troubleshoot various issues, and terminal access is really the best way to do so. So, first type the following command on the BBB:
```
# user: root
pw: Volumio
```
You should now see the following screen output; date and version may vary, of course:
Now, repeat the previous step on your client desktop box for SSH access with the same user (root) and password (volumio) credentials:
```
$ ssh volumio@xxx.xxx.xx.xxx
```
If you have any problems logging in and you are on your own local LAN, you can also do the following:
```
$ ssh root@volumio.local
```
Check that you have a solid internet connection (from either your SSH remote session or directly on the BBB) by typing in:
```
# ping www.google.com
```
Your screen output should show stable ping responses. If it does not, you may need to reboot and repeat steps 7 through 10.
To quit the ping command, remember to press Ctrl + C on your keyboard.
We are not quite ready to play your fabulous music library, but we can do a test to get a quick feel-good hit. So, open up a browser on your desktop client and type in the address, http://volumio.local.
Voila! A fancy GUI with all kinds of knobs, buttons, and sliders appears!
Tip
One of the appealing things about Volumio is that its main controller is a web-based open source UI and not a bloated proprietary piece of software. This means that with a touch of HTML and a dash of jQuery, you can mod your own controller UI.
In the GUI, click on Browse | WEBRADIO. You will see a list of streaming radio stations that came preloaded with the install. Let's choose one that has a reliably consistent streaming URL: "the Beeb", which is also known as BBC World Radio.
After clicking twice on the link, the mellifluous sounds of a British newscaster will pour from your speakers.
Note
You may find that many of the preloaded WEBRADIO stations have outdated or nonfunctioning links, leading you to believe that your installation is not working properly. However, this is not the case; you simply need to fix or update the links manually.
Under the Playback tab, you will see a volume control akin to an iPod's "click wheel." Fiddle with it a bit, and you will notice that the volume level of the output doesn't change. Frustrating, right? This means that adjusting sound levels requires another tweak.
If you connected your system to DAC, ignore this step as you will have hardware controls to adjust the volume. Otherwise, go to MENU | SETTINGS, click on the dropdown for Volume Control, and select Software.
Following this, reboot using a terminal command or via the GUI underneath the MENU | SYSTEM tab.
Once rebooted, let's push the recipe a bit further by grabbing a couple of files remotely and loading them into Volumio. We will use the familiar wget command:
```
# wget http://hudsonwerks.com/beaglebone-black-recipes/downloads/volumio-sample-media.tar.gz
```
Untar the archived files with the following command:
```
# tar -zxvf volumio-sample-media.tar.gz
```

Use this command line to put the files in the correct Volumio directory:

# mv Space-Oddity-Hadfield-CLIP.m4a /var/lib/mpd/music/USB

Then, run the following:

# mv wbgo_jazzFM_NJ.pls /var/lib/mpd/music/WEBRADIO/

The media library now needs to be updated to reflect the new additions. So, via the Volumio web GUI on your desktop client, go to http://volumio.local.
Then, navigate to MENU | LIBRARY and click on the UPDATE LIBRARY button. At this point, if you have the media from this simple recipe, the update will take only a few seconds.
It's time to test our files; we will begin by using the m4a file. Again, on the web GUI, go to the Browse | USB tab. Then, click on Space-Oddity-Hadfield-CLIP twice.
You should hear a brief sample of a remix of David Bowie's song, "Major Tom", from the album, Space Oddity. In this case, it will be sung by US astronaut Chris Hadfield on board the International Space Station. It is a remake of a classic, but the astronaut does a great job of it.
Note
We would have preferred using the whole track, but we limited the length of the clip to conform to the Fair Use legal restrictions. For a longer version of the song, the video is available online at https://youtu.be/KaOC9danxNo.
Now, let's test our newly downloaded web radio station playlist. On the web interface, go to Browse | WEBRADIO. Then, click on wbgo_jazzFM_NJ.
With a nearly finished setup, we can cut the Ethernet cord and run Volumio via Wi-Fi. Go to Menu | Network and input your network's name and password in the appropriate fields. Then, click on Save Changes, and Volumio will reset the web interface.
Next, remove the Ethernet cable. If you do not already have it open, type in the Volumio server address, http://volumio.local, again on your desktop client browser.
You should be able to control Volumio fluidly now without the Ethernet connection.
Assuming you have a smartphone, pull it out and open up a browser to the same address that you just entered on your desktop: volumio.local.
Voila! You are now freed from the desktop and have remote control of your media library from any smartphone:
Although the Volumio interface can be a bit crowded on small smartphone screens, you should see a tighter, highly usable design on tablet clients.
Next, we need to check the version of Volumio. Doing this will output the compatible file types that the software can play:
```
# mpd --version
```
Tip
The screen output should yield not only the usual copyright boilerplate, but an extensive list of the audio file types that are playable with Volumio. Check that your music library's file types are in the list, particularly in the very lengthy [ffmpeg] section.
Next, you need to update the MPD database so that it catalogues all files on your attached storage drive. You can use the Volumio GUI for this; navigate to MENU | Library | Update MDB database. You can also do the same thing with the following command line:
```
# sudo service mpd restart
```
Depending on the size of your library and regardless of the method you use, the database update may take a while. So, get a cold drink, a sandwich, or go for a jog—a long one.
If all went as planned, your music library should now be catalogued. Go to Library, select the your USB music directory, and verify that everything's visible.
We also have a potential bug fix. Depending on your version of Volumio, this is where you may encounter some quirks. Because of a lingering bug in the in the last few versions of the MPD server environment (which is not Volumio's fault), many file types compatible with FFMPEG are disabled by default.
This means that the GUI-based update MDB database function that we just executed may capture some of the metadata for a music file, including its name, but not the actual media data itself. So, let's fix this in the command line as follows:
```
# nano /etc/mpd.conf
```
Scroll down to the FFMEG = disable line and change disable to enable. Following this, save the mpd.conf file and close it.
Now, let's test our media files via the GUI; go to Browse | USB, select your album or music track, and choose a favorite music file. (Note that it doesn't have to be a David Bowie track).

With all this done, we are left with one thing to do: turn it up to 11!

There's more…

The drag and drop method: With any .pls files you may have, simply drag and drop the file into your WEBRADIO folder.
Manual method: You may have already found that some of the default web radio stations listed don't work. There is a good chance that the problem is not your in hardware; it's more likely that the station's URL has changed, which is one of the vagaries of web radio. So, you will need to tweak the address in the playlist file. Here's what we do:
1. Open up a .pls file in a text editor. You can do this on your BBB or locally on your media library drive. The drive is connected to the server as a shared drive, so you should see it appear on your client box desktop. Here is what you should see when you open the file:
```
[playlist]
File1=http://xxx.yyy.zzz:port
Title1=station name
Length1=-1
Numberofentries=1
Version=2
```
2. We will typically modify two items in this file. First, we will use the following command to modify the web radio address:
```
File1=http://xxx.yyy.zzz:port
```
In this line, insert the URL of the stream you are adding; the port setting is optional. Here's an example:
```
File1=http:/ http://xstream1.somafm.com:8000
```
Then, we want the name of the station to appear in the Volumio player while the audio is streaming:
```
Title1=station name
```
For example, if we wanted to call our station Space Station Soma, we would run the following line:
```
Title1=Space Station Soma
```

How to do it…

Now that you're ready, let's begin:

Start by downloading the Volumio BeagleBone Black disk image on your client machine (not your BBB). The current version is available at http://volumio.org/get-started/.
Following the download, extract the downloaded archive. You should end up with a .img file on your local box.
Insert an SD card reader with a minimum 4 GB microSD card installed. As Volumio claims to require a very minimal install (piggybacking on Debian Wheezy), you may be able to get away with a smaller amount of storage than 4 GB.
Flash the .img file to your SD card. As we are using a Mac box, we will use our trusty tool, PiFiller, which we used and explained in prior chapters. On a Windows box, you can use Win32DiskImager.
Confirm that you have adequate storage remaining on your SD card. To do this, run the check from a terminal window on your client machine with the following command:
```
$ df -ah
```
Your output should show somewhere around 22 percent capacity used.
From the preceding Getting ready section, you should have all the required hardware connected. Remove the SD card from your client machine, insert it in the BBB, and boot.
I have seen some flaky performances on first boot, so you may need to reboot again to get the login screen to appear. If you have used Volumio on Raspberry Pi, you will find booting up on the BBB considerably faster.
You now need to set up terminal access, first directly on the BBB and then remotely.
Technically, neither is a requirement to run Volumio as there's a lovely web-based GUI to control the tool; we'll get to that next. However, you will inevitably need to troubleshoot various issues, and terminal access is really the best way to do so. So, first type the following command on the BBB:
```
# user: root
pw: Volumio
```
You should now see the following screen output; date and version may vary, of course:
Now, repeat the previous step on your client desktop box for SSH access with the same user (root) and password (volumio) credentials:
```
$ ssh volumio@xxx.xxx.xx.xxx
```
If you have any problems logging in and you are on your own local LAN, you can also do the following:
```
$ ssh root@volumio.local
```
Check that you have a solid internet connection (from either your SSH remote session or directly on the BBB) by typing in:
```
# ping www.google.com
```
Your screen output should show stable ping responses. If it does not, you may need to reboot and repeat steps 7 through 10.
To quit the ping command, remember to press Ctrl + C on your keyboard.
We are not quite ready to play your fabulous music library, but we can do a test to get a quick feel-good hit. So, open up a browser on your desktop client and type in the address, http://volumio.local.
Voila! A fancy GUI with all kinds of knobs, buttons, and sliders appears!
Tip
One of the appealing things about Volumio is that its main controller is a web-based open source UI and not a bloated proprietary piece of software. This means that with a touch of HTML and a dash of jQuery, you can mod your own controller UI.
In the GUI, click on Browse | WEBRADIO. You will see a list of streaming radio stations that came preloaded with the install. Let's choose one that has a reliably consistent streaming URL: "the Beeb", which is also known as BBC World Radio.
After clicking twice on the link, the mellifluous sounds of a British newscaster will pour from your speakers.
Note
You may find that many of the preloaded WEBRADIO stations have outdated or nonfunctioning links, leading you to believe that your installation is not working properly. However, this is not the case; you simply need to fix or update the links manually.
Under the Playback tab, you will see a volume control akin to an iPod's "click wheel." Fiddle with it a bit, and you will notice that the volume level of the output doesn't change. Frustrating, right? This means that adjusting sound levels requires another tweak.
If you connected your system to DAC, ignore this step as you will have hardware controls to adjust the volume. Otherwise, go to MENU | SETTINGS, click on the dropdown for Volume Control, and select Software.
Following this, reboot using a terminal command or via the GUI underneath the MENU | SYSTEM tab.
Once rebooted, let's push the recipe a bit further by grabbing a couple of files remotely and loading them into Volumio. We will use the familiar wget command:
```
# wget http://hudsonwerks.com/beaglebone-black-recipes/downloads/volumio-sample-media.tar.gz
```
Untar the archived files with the following command:
```
# tar -zxvf volumio-sample-media.tar.gz
```

Use this command line to put the files in the correct Volumio directory:

# mv Space-Oddity-Hadfield-CLIP.m4a /var/lib/mpd/music/USB

Then, run the following:

# mv wbgo_jazzFM_NJ.pls /var/lib/mpd/music/WEBRADIO/

The media library now needs to be updated to reflect the new additions. So, via the Volumio web GUI on your desktop client, go to http://volumio.local.
Then, navigate to MENU | LIBRARY and click on the UPDATE LIBRARY button. At this point, if you have the media from this simple recipe, the update will take only a few seconds.
It's time to test our files; we will begin by using the m4a file. Again, on the web GUI, go to the Browse | USB tab. Then, click on Space-Oddity-Hadfield-CLIP twice.
You should hear a brief sample of a remix of David Bowie's song, "Major Tom", from the album, Space Oddity. In this case, it will be sung by US astronaut Chris Hadfield on board the International Space Station. It is a remake of a classic, but the astronaut does a great job of it.
Note
We would have preferred using the whole track, but we limited the length of the clip to conform to the Fair Use legal restrictions. For a longer version of the song, the video is available online at https://youtu.be/KaOC9danxNo.
Now, let's test our newly downloaded web radio station playlist. On the web interface, go to Browse | WEBRADIO. Then, click on wbgo_jazzFM_NJ.
With a nearly finished setup, we can cut the Ethernet cord and run Volumio via Wi-Fi. Go to Menu | Network and input your network's name and password in the appropriate fields. Then, click on Save Changes, and Volumio will reset the web interface.
Next, remove the Ethernet cable. If you do not already have it open, type in the Volumio server address, http://volumio.local, again on your desktop client browser.
You should be able to control Volumio fluidly now without the Ethernet connection.
Assuming you have a smartphone, pull it out and open up a browser to the same address that you just entered on your desktop: volumio.local.
Voila! You are now freed from the desktop and have remote control of your media library from any smartphone:
Although the Volumio interface can be a bit crowded on small smartphone screens, you should see a tighter, highly usable design on tablet clients.
Next, we need to check the version of Volumio. Doing this will output the compatible file types that the software can play:
```
# mpd --version
```
Tip
The screen output should yield not only the usual copyright boilerplate, but an extensive list of the audio file types that are playable with Volumio. Check that your music library's file types are in the list, particularly in the very lengthy [ffmpeg] section.
Next, you need to update the MPD database so that it catalogues all files on your attached storage drive. You can use the Volumio GUI for this; navigate to MENU | Library | Update MDB database. You can also do the same thing with the following command line:
```
# sudo service mpd restart
```
Depending on the size of your library and regardless of the method you use, the database update may take a while. So, get a cold drink, a sandwich, or go for a jog—a long one.
If all went as planned, your music library should now be catalogued. Go to Library, select the your USB music directory, and verify that everything's visible.
We also have a potential bug fix. Depending on your version of Volumio, this is where you may encounter some quirks. Because of a lingering bug in the in the last few versions of the MPD server environment (which is not Volumio's fault), many file types compatible with FFMPEG are disabled by default.
This means that the GUI-based update MDB database function that we just executed may capture some of the metadata for a music file, including its name, but not the actual media data itself. So, let's fix this in the command line as follows:
```
# nano /etc/mpd.conf
```
Scroll down to the FFMEG = disable line and change disable to enable. Following this, save the mpd.conf file and close it.
Now, let's test our media files via the GUI; go to Browse | USB, select your album or music track, and choose a favorite music file. (Note that it doesn't have to be a David Bowie track).

With all this done, we are left with one thing to do: turn it up to 11!

There's more…

The drag and drop method: With any .pls files you may have, simply drag and drop the file into your WEBRADIO folder.
Manual method: You may have already found that some of the default web radio stations listed don't work. There is a good chance that the problem is not your in hardware; it's more likely that the station's URL has changed, which is one of the vagaries of web radio. So, you will need to tweak the address in the playlist file. Here's what we do:
1. Open up a .pls file in a text editor. You can do this on your BBB or locally on your media library drive. The drive is connected to the server as a shared drive, so you should see it appear on your client box desktop. Here is what you should see when you open the file:
```
[playlist]
File1=http://xxx.yyy.zzz:port
Title1=station name
Length1=-1
Numberofentries=1
Version=2
```
2. We will typically modify two items in this file. First, we will use the following command to modify the web radio address:
```
File1=http://xxx.yyy.zzz:port
```
In this line, insert the URL of the stream you are adding; the port setting is optional. Here's an example:
```
File1=http:/ http://xstream1.somafm.com:8000
```
Then, we want the name of the station to appear in the Volumio player while the audio is streaming:
```
Title1=station name
```
For example, if we wanted to call our station Space Station Soma, we would run the following line:
```
Title1=Space Station Soma
```

There's more…

The drag and drop method: With any .pls files you may have, simply drag and drop the file into your WEBRADIO folder.
Manual method: You may have already found that some of the default web radio stations listed don't work. There is a good chance that the problem is not your in hardware; it's more likely that the station's URL has changed, which is one of the vagaries of web radio. So, you will need to tweak the address in the playlist file. Here's what we do:
1. Open up a .pls file in a text editor. You can do this on your BBB or locally on your media library drive. The drive is connected to the server as a shared drive, so you should see it appear on your client box desktop. Here is what you should see when you open the file:
```
[playlist]
File1=http://xxx.yyy.zzz:port
Title1=station name
Length1=-1
Numberofentries=1
Version=2
```
2. We will typically modify two items in this file. First, we will use the following command to modify the web radio address:
```
File1=http://xxx.yyy.zzz:port
```
In this line, insert the URL of the stream you are adding; the port setting is optional. Here's an example:
```
File1=http:/ http://xstream1.somafm.com:8000
```
Then, we want the name of the station to appear in the Volumio player while the audio is streaming:
```
Title1=station name
```
For example, if we wanted to call our station Space Station Soma, we would run the following line:
```
Title1=Space Station Soma
```

Using videos and displays in projects

It's one thing to just plug an HDMI monitor into the mini HDMI port on your BBB and get a picture. In many cases, this is may be all you care about for a project. However, for bona fide embedded or mobile scenarios where you need a display, using the HDMI option can be overkill; your needs are low power, small form factor, and just enough display to convey basic information.

In this section, we will take a look at two other options for display: a mini OLED display available as a breadboard-able PCB and a custom BBB cape designed with a very small LCD panel.

Hooking up a mini OLED

In this recipe, we will take a look at a very small 1.3 inch OLED display with a resolution of 128 x 64 pixels. It has a monochrome screen, which means that we will not be watching Lawrence of Arabia on this device. Instead, we will explore some methods for basic control and input and take a preliminary peek at typical design choices for embedded devices.

The nice thing about experimenting with a device like this is that we can make use of another set of pins available on BeagleBone Black: the Serial Peripheral Interface or SPI pins. The BBB packs two SPI ports, and we will use one of these. Some of the advantages of this interface include higher throughout and lower power consumption than I2C, which we used in an earlier recipe in this chapter.

Tip

To be clear, this recipe will not result in an alternative desktop display. Instead, it is the basis for building a more robust—albeit considerably smaller—low-powered display option for your customized prototyping requirements and tests. To demo the screen, we will run Python scripts as they are an easier entrée into the hardware.

Getting ready

You'll need the following items:

OLED PCB: We will use the SSD1306 driver chip version, which is available (mostly) preassembled at Adafruit https://www.adafruit.com/product/938). The board requires only a minor soldering job to attach the pins and costs around USD $25.00.
The BBB, both powered and remote SSH called, via the USB cable: Let's go headless… no cheating! There's also a practical reason to eschew an external monitor in this recipe: we will be disabling the HDMI port, so you would lose the signal anyway.
6x jumper wires
A breadboard

Adafruit's OLED comes with its own tutorial and Python example scripts. Although we will rely on the Adafruit Python BBIO library, we will actually use an additional Python library developed by Guy Carpenter and modified by Ethan Zonca along with our own custom example code.

How to do it…

Now that you're ready, let's get started:

Wire up your board and breadboard in the following manner:

To be clear, here is the hookup in table form:

OLED Screen	BBB pin	Function
GND	GND: P9_1	Ground
VIN	VDD_3V3: P9_3	Power
CS	CSO: P9_28	Slave connector
RST	GPIO: P9_24	Reset display
DC	GPIO: P9_16
CLK	P9_31	Clock
Data	P9_30

In order to use SPI pins, we need to enable a Device Tree overlay, which is easy to do as it is already compiled on the system and most efficient to load at bootup. So, first call SSH into your BBB, open a terminal window, and then browse to the following directory:
```
$ cd /boot
```
Now, open the file, uEnv.txt:
```
$ sudo nano uEnv.txt
```

Then, add the following lines at the very end of the document:

##This line added to enable device tree overlay for SPIDEV
optargs=capemgr.enable_partno=BB-SPIDEV1

Save and close the file, and then reboot your BBB as follows:
```
# reboot 
```
Log back in as the root user and confirm that the /dev/spidev1.0 and /dev/spidev1.1 files are visible, indicating that the SPI drivers are available for access:
```
$ sudo -i
# ls -l /dev/spidev*
```
You should get an output similar to this:
```
  crw-rw---T 1 root spi 153, 1 Mar  1 20:46 /dev/spidev1.0
  crw-rw---T 1 root spi 153, 0 Mar  1 20:46 /dev/spidev1.1
```
Next, we need to install a number of Python libraries and their dependencies. Some of them may already be available on your system, but run the following commands just to be certain:
```
# apt-get update
# apt-get install build-essential python-dev python-pip python-imaging python-smbus python-dateutil
# pip install spidev
# pip install pil
# pip install Adafruit_BBIO
```
Note
You could run all the pip install commands off one line; however, for clarity's sake, we will show each individual package install.
Next, we want to actually do something with the display and all these libraries. So, download a GitHub repo with sample code:
```
# git clone https://github.com/HudsonWerks/OLED-SSD1306.git
```
Browse to a subdirectory of example in the directory of code we just downloaded and take a look at what is inside:
```
# /OLED-SSD1306/samples
# ls
```
Before looking at what is inside the code, let's run the main example to see if all of the hardware wiring is correct:
```
# python oled-test1.py
```
If all went well, you will see text cycling on the screen with messages from ground control.
We want to take a brief look at the Python code, so we will now run the following command:
```
# nano oled-test1.py
```
Finally, open up the Cloud9 IDE (http://192.168.7.2:3000/ide.html), create a new .py file called oled-test1.py, and then copy and paste the code from your nano window into the IDE file window. From here, you can begin customizing the code, starting with the messages displayed on the screen.
Once appended, save the file and click on the RUN button in the IDE. An updated scrolling text message will appear on your OLED display.

Note

Before running a Python script in the Cloud9 IDE, remember to save the document each time. Otherwise, the IDE may run a cached version that does not contain your new changes.

There's more…

The following is some supporting information:

You can dig deeper into the nuances of modifying the SPIdev pins at http://elinux.org/BeagleBone_Black_Enable_SPIDEV
You can also experiment with py-gaugette, a Python alternative to the Adafruit Python library to control SPI (and other GPIO pins), including a thorough explanation of using higher-quality fonts with the display at http://guy.carpenter.id.au/gaugette/2014/01/28/spi-ssd1306-oled-for-beaglebone-black/

Getting ready

You'll need the following items:

OLED PCB: We will use the SSD1306 driver chip version, which is available (mostly) preassembled at Adafruit https://www.adafruit.com/product/938). The board requires only a minor soldering job to attach the pins and costs around USD $25.00.
The BBB, both powered and remote SSH called, via the USB cable: Let's go headless… no cheating! There's also a practical reason to eschew an external monitor in this recipe: we will be disabling the HDMI port, so you would lose the signal anyway.
6x jumper wires
A breadboard

How to do it…

Now that you're ready, let's get started:

Wire up your board and breadboard in the following manner:

To be clear, here is the hookup in table form:

OLED Screen	BBB pin	Function
GND	GND: P9_1	Ground
VIN	VDD_3V3: P9_3	Power
CS	CSO: P9_28	Slave connector
RST	GPIO: P9_24	Reset display
DC	GPIO: P9_16
CLK	P9_31	Clock
Data	P9_30

In order to use SPI pins, we need to enable a Device Tree overlay, which is easy to do as it is already compiled on the system and most efficient to load at bootup. So, first call SSH into your BBB, open a terminal window, and then browse to the following directory:
```
$ cd /boot
```
Now, open the file, uEnv.txt:
```
$ sudo nano uEnv.txt
```

Then, add the following lines at the very end of the document:

##This line added to enable device tree overlay for SPIDEV
optargs=capemgr.enable_partno=BB-SPIDEV1

Save and close the file, and then reboot your BBB as follows:
```
# reboot 
```
Log back in as the root user and confirm that the /dev/spidev1.0 and /dev/spidev1.1 files are visible, indicating that the SPI drivers are available for access:
```
$ sudo -i
# ls -l /dev/spidev*
```
You should get an output similar to this:
```
  crw-rw---T 1 root spi 153, 1 Mar  1 20:46 /dev/spidev1.0
  crw-rw---T 1 root spi 153, 0 Mar  1 20:46 /dev/spidev1.1
```
Next, we need to install a number of Python libraries and their dependencies. Some of them may already be available on your system, but run the following commands just to be certain:
```
# apt-get update
# apt-get install build-essential python-dev python-pip python-imaging python-smbus python-dateutil
# pip install spidev
# pip install pil
# pip install Adafruit_BBIO
```
Note
You could run all the pip install commands off one line; however, for clarity's sake, we will show each individual package install.
Next, we want to actually do something with the display and all these libraries. So, download a GitHub repo with sample code:
```
# git clone https://github.com/HudsonWerks/OLED-SSD1306.git
```
Browse to a subdirectory of example in the directory of code we just downloaded and take a look at what is inside:
```
# /OLED-SSD1306/samples
# ls
```
Before looking at what is inside the code, let's run the main example to see if all of the hardware wiring is correct:
```
# python oled-test1.py
```
If all went well, you will see text cycling on the screen with messages from ground control.
We want to take a brief look at the Python code, so we will now run the following command:
```
# nano oled-test1.py
```
Finally, open up the Cloud9 IDE (http://192.168.7.2:3000/ide.html), create a new .py file called oled-test1.py, and then copy and paste the code from your nano window into the IDE file window. From here, you can begin customizing the code, starting with the messages displayed on the screen.
Once appended, save the file and click on the RUN button in the IDE. An updated scrolling text message will appear on your OLED display.

Note

Before running a Python script in the Cloud9 IDE, remember to save the document each time. Otherwise, the IDE may run a cached version that does not contain your new changes.

There's more…

The following is some supporting information:

You can dig deeper into the nuances of modifying the SPIdev pins at http://elinux.org/BeagleBone_Black_Enable_SPIDEV
You can also experiment with py-gaugette, a Python alternative to the Adafruit Python library to control SPI (and other GPIO pins), including a thorough explanation of using higher-quality fonts with the display at http://guy.carpenter.id.au/gaugette/2014/01/28/spi-ssd1306-oled-for-beaglebone-black/

How to do it…

Now that you're ready, let's get started:

Wire up your board and breadboard in the following manner:

To be clear, here is the hookup in table form:

OLED Screen	BBB pin	Function
GND	GND: P9_1	Ground
VIN	VDD_3V3: P9_3	Power
CS	CSO: P9_28	Slave connector
RST	GPIO: P9_24	Reset display
DC	GPIO: P9_16
CLK	P9_31	Clock
Data	P9_30

In order to use SPI pins, we need to enable a Device Tree overlay, which is easy to do as it is already compiled on the system and most efficient to load at bootup. So, first call SSH into your BBB, open a terminal window, and then browse to the following directory:
```
$ cd /boot
```
Now, open the file, uEnv.txt:
```
$ sudo nano uEnv.txt
```

Then, add the following lines at the very end of the document:

##This line added to enable device tree overlay for SPIDEV
optargs=capemgr.enable_partno=BB-SPIDEV1

Save and close the file, and then reboot your BBB as follows:
```
# reboot 
```
Log back in as the root user and confirm that the /dev/spidev1.0 and /dev/spidev1.1 files are visible, indicating that the SPI drivers are available for access:
```
$ sudo -i
# ls -l /dev/spidev*
```
You should get an output similar to this:
```
  crw-rw---T 1 root spi 153, 1 Mar  1 20:46 /dev/spidev1.0
  crw-rw---T 1 root spi 153, 0 Mar  1 20:46 /dev/spidev1.1
```
Next, we need to install a number of Python libraries and their dependencies. Some of them may already be available on your system, but run the following commands just to be certain:
```
# apt-get update
# apt-get install build-essential python-dev python-pip python-imaging python-smbus python-dateutil
# pip install spidev
# pip install pil
# pip install Adafruit_BBIO
```
Note
You could run all the pip install commands off one line; however, for clarity's sake, we will show each individual package install.
Next, we want to actually do something with the display and all these libraries. So, download a GitHub repo with sample code:
```
# git clone https://github.com/HudsonWerks/OLED-SSD1306.git
```
Browse to a subdirectory of example in the directory of code we just downloaded and take a look at what is inside:
```
# /OLED-SSD1306/samples
# ls
```
Before looking at what is inside the code, let's run the main example to see if all of the hardware wiring is correct:
```
# python oled-test1.py
```
If all went well, you will see text cycling on the screen with messages from ground control.
We want to take a brief look at the Python code, so we will now run the following command:
```
# nano oled-test1.py
```
Finally, open up the Cloud9 IDE (http://192.168.7.2:3000/ide.html), create a new .py file called oled-test1.py, and then copy and paste the code from your nano window into the IDE file window. From here, you can begin customizing the code, starting with the messages displayed on the screen.
Once appended, save the file and click on the RUN button in the IDE. An updated scrolling text message will appear on your OLED display.

Note

Before running a Python script in the Cloud9 IDE, remember to save the document each time. Otherwise, the IDE may run a cached version that does not contain your new changes.

There's more…

The following is some supporting information:

You can dig deeper into the nuances of modifying the SPIdev pins at http://elinux.org/BeagleBone_Black_Enable_SPIDEV
You can also experiment with py-gaugette, a Python alternative to the Adafruit Python library to control SPI (and other GPIO pins), including a thorough explanation of using higher-quality fonts with the display at http://guy.carpenter.id.au/gaugette/2014/01/28/spi-ssd1306-oled-for-beaglebone-black/

There's more…

The following is some supporting information:

You can dig deeper into the nuances of modifying the SPIdev pins at http://elinux.org/BeagleBone_Black_Enable_SPIDEV
You can also experiment with py-gaugette, a Python alternative to the Adafruit Python library to control SPI (and other GPIO pins), including a thorough explanation of using higher-quality fonts with the display at http://guy.carpenter.id.au/gaugette/2014/01/28/spi-ssd1306-oled-for-beaglebone-black/

Testing a mini LCD cape

In this section, we will cook up an introductory recipe to use the mini LCD display cape designed by CircuitCo.

With a mere 1.8 inches of screen territory, you might wonder what kind of scenarios would be relevant for an add-on such as this. You might also think that the design is a bit odd as the PCB board space dwarfs the actual screen size. Keep in mind a couple of things, though, when deciding to purchase the cape and testing it:

The BBB is an embedded computing-centric development environment, not desktop-centric as RPi is. As such, an add-on similar to this mini display cape addresses the needs of typical use cases for an embedded device. These are situations that commonly require extremely low power and minimal display, if any.
The need for fast prototyping, durability, and testing drive the design of a cape such as this results in an overall form factor much larger than the screen itself. Looking more closely at the cape, we discover a number of exciting things:
- Open source design: The cape design and its components are all open sourced, with the core element—the display itself—referenced and clearly sourced so that you can make your own mods once you've got your prototype device ready to fly or amble. Here are the design files and schematic (http://elinux.org/CircuitCo:MiniDisplay_Cape) and the component vendor's URL for the display (https://www.crystalfontz.com/product/CFAF128128B0145T).
- Low cost: At the preceding referenced source, you will see that in a high-quantity purchase of the display (not the finished cape), the price dramatically drops per unit. So, you can model a low-cost scenario for multiple final production units of your device without incurring the finishing and design costs of a third-party supplier, such as CircuitCo.

Getting ready

In this recipe, we will cook a bit more professionally so that our environment looks more like a true embedded device. Thus, our kit is minimal:

A mini LCD cape: Resolution 128 x 128 (purchased from http://boardzoo.com/index.php for around $USD 30.00).
Let's go headless again and wireless, which means we will need the following:
- A USB cable: We will just power up via a mini USB cable.
- A Wi-Fi dongle: Insert this directly into the Ethernet port on your BBB. Remote SSH calling sans an annoying Ethernet cable is the goal. Although many users would suggest you to not use a dongle without a powered USB, my tests have delivered stable connectivity without any external hub, making the whole recipe and setup much cleaner.

Tip

Note that this code is a variation of Professor Mark Yoder's code (https://github.com/MarkAYoder/BeagleBoard-exercises/tree/master/miniDisplay), which is, in turn, a modification of the CircuitCo example code (http://elinux.org/images/e/e4/Minidisplay-example.tar.gz).

How to do it…

With everything prepared, what are you waiting for?

First, carefully insert the cape into the header pin slots on the BBB. As the cape board has a recessed side to accommodate the BBB's Ethernet port, it is difficult to get the orientation wrong:
The cape fully inserted into the pins.
Tip
You may be a little tentative getting the pins footed properly as the pins are a very tight fit. Once inserted, removing the cape is a bit tricky due to the snugness, so it's best to ease it out slowly from the board headers.
With the cape fully inserted, power up your BBB via USB.
You then need to log in via SSH and then as root, with the following code:
```
debian@beaglebone:~$ sudo -i
root@beaglebone:~# 
```
Now that you're logged in and ready, you need to download and compile some sample code for the display. This code is a slight modification of an open source archived version:
```
# wget https://github.com/HudsonWerks/minidisplay-cape.git
```
Finally, navigate to the new directory created and compile the test application:
```
# cd minidisplay-cape
# make
```

The cape will need a Device Tree Overlay; however, before we take action on this, let's take a look at what cape manager shows us about what is currently loaded using the following command:

# cat /sys/devices/bone_capemgr.*/slots
0: 54:PF--- 
1: 55:PF--- 
2: 56:PF--- 
3: 57:PF--- 
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI

Next, we will run the following command to load Device Tree so that the cape is recognized. This is made considerably easier with the inclusion of universal Device Tree Overlay with the latest versions of the BBB firmware:
```
# config-pin overlay BB-SPIDEV0
```

Check that the overlay loaded as expected by executing the following command:

# cat /sys/devices/bone_capemgr.*/slots

Your output should look similar to this with the last item in the slot list your loaded overlay:
0: 54:PF--- 
1: 55:PF--- 
2: 56:PF--- 
3: 57:PF--- 
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI
7: ff:P-O-L Override Board Name,00A0,Override Manuf,BB-SPIDEV0

Now, run the test application:
```
# ./minidisplay-test
```

If all goes as planned, the display will begin with a color bar test screen and then end with an image showing Major Tom's view of Earth from the International Space Station (ISS).

Getting ready

In this recipe, we will cook a bit more professionally so that our environment looks more like a true embedded device. Thus, our kit is minimal:

A mini LCD cape: Resolution 128 x 128 (purchased from http://boardzoo.com/index.php for around $USD 30.00).
Let's go headless again and wireless, which means we will need the following:
- A USB cable: We will just power up via a mini USB cable.
- A Wi-Fi dongle: Insert this directly into the Ethernet port on your BBB. Remote SSH calling sans an annoying Ethernet cable is the goal. Although many users would suggest you to not use a dongle without a powered USB, my tests have delivered stable connectivity without any external hub, making the whole recipe and setup much cleaner.

Tip

How to do it…

With everything prepared, what are you waiting for?

First, carefully insert the cape into the header pin slots on the BBB. As the cape board has a recessed side to accommodate the BBB's Ethernet port, it is difficult to get the orientation wrong:
The cape fully inserted into the pins.
Tip
You may be a little tentative getting the pins footed properly as the pins are a very tight fit. Once inserted, removing the cape is a bit tricky due to the snugness, so it's best to ease it out slowly from the board headers.
With the cape fully inserted, power up your BBB via USB.
You then need to log in via SSH and then as root, with the following code:
```
debian@beaglebone:~$ sudo -i
root@beaglebone:~# 
```
Now that you're logged in and ready, you need to download and compile some sample code for the display. This code is a slight modification of an open source archived version:
```
# wget https://github.com/HudsonWerks/minidisplay-cape.git
```
Finally, navigate to the new directory created and compile the test application:
```
# cd minidisplay-cape
# make
```

The cape will need a Device Tree Overlay; however, before we take action on this, let's take a look at what cape manager shows us about what is currently loaded using the following command:

# cat /sys/devices/bone_capemgr.*/slots
0: 54:PF--- 
1: 55:PF--- 
2: 56:PF--- 
3: 57:PF--- 
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI

Next, we will run the following command to load Device Tree so that the cape is recognized. This is made considerably easier with the inclusion of universal Device Tree Overlay with the latest versions of the BBB firmware:
```
# config-pin overlay BB-SPIDEV0
```

Check that the overlay loaded as expected by executing the following command:

# cat /sys/devices/bone_capemgr.*/slots

Your output should look similar to this with the last item in the slot list your loaded overlay:
0: 54:PF--- 
1: 55:PF--- 
2: 56:PF--- 
3: 57:PF--- 
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI
7: ff:P-O-L Override Board Name,00A0,Override Manuf,BB-SPIDEV0

Now, run the test application:
```
# ./minidisplay-test
```

If all goes as planned, the display will begin with a color bar test screen and then end with an image showing Major Tom's view of Earth from the International Space Station (ISS).

How to do it…

With everything prepared, what are you waiting for?

First, carefully insert the cape into the header pin slots on the BBB. As the cape board has a recessed side to accommodate the BBB's Ethernet port, it is difficult to get the orientation wrong:
The cape fully inserted into the pins.
Tip
You may be a little tentative getting the pins footed properly as the pins are a very tight fit. Once inserted, removing the cape is a bit tricky due to the snugness, so it's best to ease it out slowly from the board headers.
With the cape fully inserted, power up your BBB via USB.
You then need to log in via SSH and then as root, with the following code:
```
debian@beaglebone:~$ sudo -i
root@beaglebone:~# 
```
Now that you're logged in and ready, you need to download and compile some sample code for the display. This code is a slight modification of an open source archived version:
```
# wget https://github.com/HudsonWerks/minidisplay-cape.git
```
Finally, navigate to the new directory created and compile the test application:
```
# cd minidisplay-cape
# make
```

The cape will need a Device Tree Overlay; however, before we take action on this, let's take a look at what cape manager shows us about what is currently loaded using the following command:

# cat /sys/devices/bone_capemgr.*/slots
0: 54:PF--- 
1: 55:PF--- 
2: 56:PF--- 
3: 57:PF--- 
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI

Next, we will run the following command to load Device Tree so that the cape is recognized. This is made considerably easier with the inclusion of universal Device Tree Overlay with the latest versions of the BBB firmware:
```
# config-pin overlay BB-SPIDEV0
```

Check that the overlay loaded as expected by executing the following command:

# cat /sys/devices/bone_capemgr.*/slots

Your output should look similar to this with the last item in the slot list your loaded overlay:
0: 54:PF--- 
1: 55:PF--- 
2: 56:PF--- 
3: 57:PF--- 
4: ff:P-O-L Bone-LT-eMMC-2G,00A0,Texas Instrument,BB-BONE-EMMC-2G
5: ff:P-O-L Bone-Black-HDMI,00A0,Texas Instrument,BB-BONELT-HDMI
7: ff:P-O-L Override Board Name,00A0,Override Manuf,BB-SPIDEV0

Now, run the test application:
```
# ./minidisplay-test
```

If all goes as planned, the display will begin with a color bar test screen and then end with an image showing Major Tom's view of Earth from the International Space Station (ISS).

Making a video chat client prototype using Linphone

In this recipe, we will first compile and install Linphone, a well-known open source chat client, with the assumption that we'll use both audio and video. After compiling and running, we will test and optimize the package.

Getting ready

Since we will run a more power intensive, graphics-and GUI-centric environment for the next several recipes, you will need to set up your BeagleBone Black board accordingly:

LCD: Attach an HDMI LCD to the micro HDMI port or an LCD cape if you have one. As we will be running an x-session, headless is not possible.
A powered USB hub: We will use a bushel of peripherals, so plug the powered hub into the USB port and make the BBB happy.
Keyboard and mouse: The packages we will install do not like VNC sessions, so you will need to include a USB keyboard and mouse in your powered USB hub.
USB webcam: As we are doing video chat sessions, we have to have a camera and microphone; a USB webcam is the fastest option.

How to do it…

Once ready, it's time to begin the recipe. Please note that this is split into two parts, and you need to complete them in order. The objective is to first go through the process of installing a pre-compiled version of the software. Then, based on that outcome, see how we can improve the functionality of the tool by compiling it from source files.

Part I – compiling and installing a Linphone binary from the repository

To begin this recipe, you will firstly need to compile and install the Linphone binary from the repository as follows:

Installing Linphone: This is the easy part; you can actually install the Linphone binary via apt-get, as follows:
```
$ sudo apt-get update
$ sudo apt-get install linphone
```
With this, you'll end up with the latest precompiled binary of Linphone on your BBB. So, let's check the version that we get using the following command:
```
$ dpkg -p linphone
```
Take note of the version from the screen output as we will refer to it later.
Setting up an SIP account: Open up the application under Internet | Linphone. You will be greeted with a GUI-based wizard, which includes setting up an SIP telephone number on the application. SIP is a signaling protocol that works with Voice Over IP (VOIP) telecommunications. Numerous free SIP servers are available (just Google "free SIP account"). Here, we will make it easy and use the free one offered by Linphone.org, the developers of the tool.
Doing a desktop install: We also want to install the binary on your desktop client so that we can test a two-way call connection with the BBB. Downloadable binaries for other platforms (Mac or Windows versions) are available at http://www.linphone.org/technical-corner/linphone/downloads. Follow the on screen wizard to set up an account as you just did in the previous step.
Making a video call: Once you've authenticated your new SIP telephone number and configured your account on Linphone, you can make a video call.

You probably ran into problems while running the application. Did it run slowly? Did it take up most of your CPU's resources? Could you make a connection to the desktop client and run a video chat session? When it comes to CPU hogs, such as video and audio, the BBB does not shine. However, we have a plan for this; thus, take a look at the next part of this recipe.

Part II – compiling and installing Linphone from source

Now, we will compile and install Linphone from source to note how the two versions compare.

Getting ready

If you completed the first part of this recipe, uninstall the prebuilt binary of Linphone before creating a new one and installing it from source. So, remove it completely by running:

~$ sudo dpkg --purge linphone

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

Getting ready

Since we will run a more power intensive, graphics-and GUI-centric environment for the next several recipes, you will need to set up your BeagleBone Black board accordingly:

LCD: Attach an HDMI LCD to the micro HDMI port or an LCD cape if you have one. As we will be running an x-session, headless is not possible.
A powered USB hub: We will use a bushel of peripherals, so plug the powered hub into the USB port and make the BBB happy.
Keyboard and mouse: The packages we will install do not like VNC sessions, so you will need to include a USB keyboard and mouse in your powered USB hub.
USB webcam: As we are doing video chat sessions, we have to have a camera and microphone; a USB webcam is the fastest option.

How to do it…

Part I – compiling and installing a Linphone binary from the repository

To begin this recipe, you will firstly need to compile and install the Linphone binary from the repository as follows:

Installing Linphone: This is the easy part; you can actually install the Linphone binary via apt-get, as follows:
```
$ sudo apt-get update
$ sudo apt-get install linphone
```
With this, you'll end up with the latest precompiled binary of Linphone on your BBB. So, let's check the version that we get using the following command:
```
$ dpkg -p linphone
```
Take note of the version from the screen output as we will refer to it later.
Setting up an SIP account: Open up the application under Internet | Linphone. You will be greeted with a GUI-based wizard, which includes setting up an SIP telephone number on the application. SIP is a signaling protocol that works with Voice Over IP (VOIP) telecommunications. Numerous free SIP servers are available (just Google "free SIP account"). Here, we will make it easy and use the free one offered by Linphone.org, the developers of the tool.
Doing a desktop install: We also want to install the binary on your desktop client so that we can test a two-way call connection with the BBB. Downloadable binaries for other platforms (Mac or Windows versions) are available at http://www.linphone.org/technical-corner/linphone/downloads. Follow the on screen wizard to set up an account as you just did in the previous step.
Making a video call: Once you've authenticated your new SIP telephone number and configured your account on Linphone, you can make a video call.

Part II – compiling and installing Linphone from source

Now, we will compile and install Linphone from source to note how the two versions compare.

Getting ready

If you completed the first part of this recipe, uninstall the prebuilt binary of Linphone before creating a new one and installing it from source. So, remove it completely by running:

~$ sudo dpkg --purge linphone

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

How to do it…

Part I – compiling and installing a Linphone binary from the repository

To begin this recipe, you will firstly need to compile and install the Linphone binary from the repository as follows:

Installing Linphone: This is the easy part; you can actually install the Linphone binary via apt-get, as follows:
```
$ sudo apt-get update
$ sudo apt-get install linphone
```
With this, you'll end up with the latest precompiled binary of Linphone on your BBB. So, let's check the version that we get using the following command:
```
$ dpkg -p linphone
```
Take note of the version from the screen output as we will refer to it later.
Setting up an SIP account: Open up the application under Internet | Linphone. You will be greeted with a GUI-based wizard, which includes setting up an SIP telephone number on the application. SIP is a signaling protocol that works with Voice Over IP (VOIP) telecommunications. Numerous free SIP servers are available (just Google "free SIP account"). Here, we will make it easy and use the free one offered by Linphone.org, the developers of the tool.
Doing a desktop install: We also want to install the binary on your desktop client so that we can test a two-way call connection with the BBB. Downloadable binaries for other platforms (Mac or Windows versions) are available at http://www.linphone.org/technical-corner/linphone/downloads. Follow the on screen wizard to set up an account as you just did in the previous step.
Making a video call: Once you've authenticated your new SIP telephone number and configured your account on Linphone, you can make a video call.

Part II – compiling and installing Linphone from source

Now, we will compile and install Linphone from source to note how the two versions compare.

Getting ready

If you completed the first part of this recipe, uninstall the prebuilt binary of Linphone before creating a new one and installing it from source. So, remove it completely by running:

~$ sudo dpkg --purge linphone

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

Part I – compiling and installing a Linphone binary from the repository

To begin this recipe, you will firstly need to compile and install the Linphone binary from the repository as follows:

Installing Linphone: This is the easy part; you can actually install the Linphone binary via apt-get, as follows:
```
$ sudo apt-get update
$ sudo apt-get install linphone
```
With this, you'll end up with the latest precompiled binary of Linphone on your BBB. So, let's check the version that we get using the following command:
```
$ dpkg -p linphone
```
Take note of the version from the screen output as we will refer to it later.
Setting up an SIP account: Open up the application under Internet | Linphone. You will be greeted with a GUI-based wizard, which includes setting up an SIP telephone number on the application. SIP is a signaling protocol that works with Voice Over IP (VOIP) telecommunications. Numerous free SIP servers are available (just Google "free SIP account"). Here, we will make it easy and use the free one offered by Linphone.org, the developers of the tool.
Doing a desktop install: We also want to install the binary on your desktop client so that we can test a two-way call connection with the BBB. Downloadable binaries for other platforms (Mac or Windows versions) are available at http://www.linphone.org/technical-corner/linphone/downloads. Follow the on screen wizard to set up an account as you just did in the previous step.
Making a video call: Once you've authenticated your new SIP telephone number and configured your account on Linphone, you can make a video call.

Part II – compiling and installing Linphone from source

Now, we will compile and install Linphone from source to note how the two versions compare.

Getting ready

If you completed the first part of this recipe, uninstall the prebuilt binary of Linphone before creating a new one and installing it from source. So, remove it completely by running:

~$ sudo dpkg --purge linphone

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

Part II – compiling and installing Linphone from source

Now, we will compile and install Linphone from source to note how the two versions compare.

Getting ready

If you completed the first part of this recipe, uninstall the prebuilt binary of Linphone before creating a new one and installing it from source. So, remove it completely by running:

~$ sudo dpkg --purge linphone

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

Getting ready

If you completed the first part of this recipe, uninstall the prebuilt binary of Linphone before creating a new one and installing it from source. So, remove it completely by running:

~$ sudo dpkg --purge linphone

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

How to do it…

Let's get to it:

Begin by updating and upgrading your packages and then set up a directory to keep the source files with the following commands:

$ sudo apt-get update && sudo apt-get upgrade
$ mkdir packages
$ cd packages

To be sure we have certain basic packages, install the following:

$ sudo apt-get install automake autoconf gnu-standards gettext build-essential pkg-config git libtool antlr3 libantlr3c-dev intltool

Next, we will get the essential packages by executing the following commands:

$ git clone git://git.linphone.org/polarssl
$ git clone git://git.linphone.org/belle-sip
$ git clone git://git.linphone.org/linphone --recursive

Then, we will install the latest Oracle JDK. This is a tricky but necessary set of steps because another package that we need to compile—antlr—is dependent on the correct installation of the JDK.
To start, we should first look at the version of the JDK that comes preloaded on the current Debian BBB distribution (note that your version may vary). The following command will be useful for this:
```
$ java -version
java version "1.6.0_32"
```
The output should look something similar to this:
```
OpenJDK Runtime Environment (IcedTea6 1.13.4) (6b32-1.13.4-1~deb7u1)
OpenJDK Zero VM (build 23.25-b01, mixed mode)
```
Let's move along to installing the new SDK. To do this, we will switch from pure command line interaction over to the BBB's desktop GUI. Open up the Chrome web browser in your applications menu in the lower-left corner. Browse the following Oracle site and download the current JDK for ARM devices, the hardfloat version, into your /home directory. You will need to agree to the licensing terms to get the file, which is why we cannot use wget or git to grab the file:
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-arm-downloads-2187472.html
Tip
When trying to download via your browser, you may encounter the error, Failed. Insufficient permissions. This tells us that when using the GUI's file browser window, we do not have write privileges to the /home directory by default. Change permissions this way:
```
$ sudo chown <user> /home
```
After running this command, you should no longer have read/write problems, and you will be able to download the Java archive without error.
With the permissions to access the file, go to your /home/user directory as follows:
```
$ cd /home/user
```
You should see the .gz file there.
For a sanity check, we will confirm that we are in the right directory with the output as follows:
```
$ pwd
/home/user
```
Tip
As a reminder, user will likely be debian, unless you change it to another name.
We can then confirm that our downloaded file is in the right place:
```
$ ls
Desktop  bin jdk-0a0-linux-arm-vfp-hflt.tar.gz  packages
```
You then need to unpack the Java TAR file in your /home directory with TAR. Note that you should be sure to replace the proper file name of the current version available with the following XX file names:
```
/home$ tar -zxvf jdk-8uXX-linux-arm-vfp-hflt.tar.gz
```
We can verify that our untar command did its job and created the new Java directory using:
```
$ ls
Desktop  bin  jdk-8u6-linux-arm-vfp-hflt.tar.gz  jdk1.8.0_XX packages
```
Next, we set up PATH and JAVA_HOME so that the compiled Linphone binary will know where to find the working directory for Java. We will do this by adding PATH information to the .bashrc file:
```
$ sudo nano ~/.bashrc
```
In the open nano window and at the end of the file, paste the following:
```
export PATH="/home/debian/jdk1.8.0_07/bin:$PATH"
export JAVA_HOME="/home/debian/jdk1.8.0_07"
```
Note
Reminder!
Here, /debian is the username and may be different in your case based on any earlier changes you may have made; the JDK version shown here should be replaced with the version that you downloaded and unarchived earlier.
You should then save and close the file by pressing Ctrl + X; when prompted, type Y for yes, and then press the return key (Enter).
Following this, reboot your BBB.
In the terminal, confirm that the version of the SDK you just installed is now being referenced properly through the following command:
```
$ java -version
```
Cross your fingers, and you will see an output similar to this:
```
Java version "x.y.z_00"
Java(TM) SE Runtime Environment (build x.y.z_00-xyx)
Java HotSpot(TM) Client VM (build 00.0-xyz, mixed mode)
```
If so, hurray! We can move on! If not, you need to repeat the preceding steps to install the JDK.

Next, we need to install the belle-sip and linphone dependencies, as follows:

$ sudo aptitude install libswscale-dev libavcodec-dev libv4l-dev libglew1.6-dev libxml2-dev libgsm1-dev libsqlite3-dev libupnp-dev libsdl1.2-dev

This next step is not difficult, but it will slow down the recipe as we need to both get another library (libvpx) and compile it from source files. This library, which we get from Google, installs a neon-optimized version of libvpx (an HTTP and web file management library). Use the following command for this:
```
$ git clone https://chromium.googlesource.com/webm/libvpx -b v1.3.0
```
You can then change the directory via:
```
$ cd libvpx
```

Following this, run configure with the following options:

$ CC=cc AR=ar AS=as LD=gcc CXX=g++ ./configure --enable-vp8 --target=armv7-linux-gcc --disable-examples --disable-docs --enable-error-concealment --enable-realtime-only --enable-spatial-resampling --enable-multithread --disable-vp9 --enable-pic

Now, run make with the following option and then run install. These two commands will take several minutes to complete:
```
$ make -j2
$ sudo make install
```
Now, we will go after an audio codec known to efficiently deliver high-quality audio, called speex. We will compile it with NEON optimizations enabled. Go to your packages directory and then run git clone, as follows:
```
$ cd packages
$ git clone git://git.linphone.org/speex
```
Change the directory and begin the compile process by running the following command:
```
$ cd speex && ./autogen.sh
```
You then need to run configure with the following options:
```
$ ./configure --enable-armv7neon-asm --with-pic --enable-fixed-point --disable-oggtest CFLAGS="-mfpu=neon" --disable-ogg
```
Now, go ahead with the following option and run make install. You will note that you can combine these two commands with the double ampersand (&&):
```
$ make -j2 && sudo make install
```

Next, compile and install belle-sip as follows:

$ cd packages/belle-sip
$ ./autogen.sh
$ ./configure
$ make && sudo make install

Then, compile and install linphone using the following command:
```
$ ./autogen.sh

$ ./configure --disable-x11 --enable-gtk_ui=no --disable-xv --enable-sdl

$ make V=1 CFLAGS="-Wno-error" && sudo make install
```
Note
We used the wno-error flag here because the mediastreamer dependency would otherwise keep alerting us about unused functions.

We need to relink with:

$ export LD_LIBRARY_PATH=/usr/local/lib

You can verify that linphone passes the tests via:

$ cd tester && ./liblinphone_tester

We are nearly finished. We will now set up the video output by forcing the video display to use a Simple Direct Media Layer (SDL) output, which will optimize video playback. We will do this by launching a command-line tool that comes with Linphone, called linphonec:
```
$ linphonec
```
At the prompt, type the following:
```
> quit
```
Simply executing this command transparently generates a file called linphonerc, which we now need to edit as follows:
```
$ sudo nano ~/.linphonerc
```
With this file window open, find the [video] section and type or replace the following at the end of the section:
```
displaytype=MSVideoOut 
```
We are now ready to launch Linphone. When you launch the application for the first time, you may encounter the following error or something similar:
```
liblinphone.so.6: cannot open shared object file
```
If so, you need to reset the location of the Linphone libraries as the error indicates that you have installed the package in a "nonstandard" directory on your BeagleBone Black board.
This command will help Linphone relink the shared library location:
```
$ export LD_LIBRARY_PATH=_the_path_to_your_linphone_libs
```
You can now launch Linphone from its command-line tool as follows:
```
$ linphonec
```
In the terminal window, Linphone will launch and allow you to configure the settings in the next two steps.
Setting up an SIP account: Unlike the GUI-based wizard that you experienced with the initial prepackaged install, setting up and registering is a bit more minimal. As you have already registered an SIP account, you can just register your SIP address with the following command:
```
> linphone / register <sip-address> <sip domain> <password>
```
Making a video call: To test your connection, make a call to your client box, which should already have an installed and registered version of Linphone from the first part of this recipe:
```
> linphone / call <sip-address-of-client-box>
```

Well done! It's not an easy install, but it's a good, intermediate recipe that yields a robust, sophisticated tool running on your BBB.

You're reading from BeagleBone: Creative Projects for Hobbyists Build amazing BeagleBone projects and maximize your skills with projects that walk, talk, and fly!

Table of Contents (6) Chapters

Chapter 7. Applied Recipes – Sound, Picture, and Video

Introduction

Wiring up a mini amp and speakers

Note

Getting ready

How to do it…

Note

Getting ready

How to do it…

Note

How to do it…

Note

Creating a high-quality audio platform with Volumio

Getting ready

Note

How to do it…

Tip

Note

Note

Tip

There's more…

See also

Getting ready

Note

How to do it…

Tip

Note

Note

Tip

There's more…

See also

How to do it…

Tip

Note

Note

Tip

There's more…

See also

There's more…

See also

See also

Using videos and displays in projects

Tip

Getting ready

How to do it…

Note

Note

There's more…

Getting ready

How to do it…

Note

Note

There's more…

How to do it…

Note

Note

There's more…

There's more…

Testing a mini LCD cape

Getting ready

Tip

How to do it…

Tip

Getting ready

Tip

How to do it…

Tip

How to do it…

Tip

Making a video chat client prototype using Linphone

Getting ready

How to do it…

Part I – compiling and installing a Linphone binary from the repository

Part II – compiling and installing Linphone from source

Getting ready

How to do it…

Tip

Tip