Configuration

Once you have the hardware setup you're ready to configure the BeagleBone Black to use your WiFi adapter.

Kernel Upgrade

First you will want to make sure you're running the very latest version of the 3.8 series kernel.  Like mentioned in the previous page, you want to use the most recent Linux kernel to get the most recent and stable WiFi drivers.  Luckily you don't need to be a Linux expert to upgrade the kernel because a script is included with your BeagleBone Black's Debian installation to automatically upgrade to the latest stable 3.8 version kernel.

In my testing I found upgrading the BeagleBone Black's kernel was mandatory to get reliable WiFi performance.  Don't skip this step, be sure to upgrade the kernel!

Make sure your device is connected to the internet (through the ethernet port for example), power it on, and connect to the terminal with SSH.  Run the following commands to start the kernel upgrade:

cd /opt/scripts/tools/
./update_kernel.sh

You should see the script download a kernel image and perform the installation automatically.  After a few minutes the uprade will complete and tell you to reboot your device.  Follow the instructions and reboot by executing the command:

After the device reboots the kernel upgrade is complete!

WiFi Reset Service

The next step is to install a small script that will reset the WiFi interface by bringing it down and back up again automatically on boot.  With the latest 3.8 kernel I found this reset script was necessary to get reliable performance with Realtek and some Atheros WiFi adapters, so don't skip installing it!  Later kernels or more stable adapters might not require the reset service, but it can't hurt to install it for them too.

To install the service connect again to the device in a terminal with SSH and execute these commands:

cd ~
ntpdate -b -s -u pool.ntp.org
apt-get update && apt-get install git
git clone https://github.com/adafruit/wifi-reset.git
cd wifi-reset
chmod +x install.sh
./install.sh

After executing the install.sh script you should see a response like the following:

Installing wifi reset service to /opt/wifi-reset.
Installing systemd service to run at boot.
Enabling systemd service.

If you see an error message, go back and carefully check the commands above were executed.

That's all you need to do to install the wifi reset service!

Note that if you'd ever like to disable the WiFi reset service you can execute this command to do so:

systemctl disable wifi-reset.service

WiFi Configuration

Finally it's time to configure the wireless connection for your BeagleBone Black.  To start, power down the device completely and insert the WiFi adapter into the USB port.  Remember the HDMI port can cause interference so you might need to use a small extension or hub to move your adapter away from the board!

Power up your BeagleBone Black and connect to it in a terminal with SSH, then run the following command to list any wireless interfaces available:

iwconfig

You should see a response with a wlan0 name and some details about the wireless adapter's capabilities.  For example I see the following response for my adapter:

wlan0     IEEE 802.11bgn  ESSID:off/any  
          Mode:Managed  Access Point: Not-Associated   Tx-Power=0 dBm   
          Retry  long limit:7   RTS thr=2347 B   Fragment thr:off
          Encryption key:off
          Power Management:on
          
lo        no wireless extensions.

eth0      no wireless extensions.

usb0      no wireless extensions.

Note that if you see a different name than wlan0, like ra0, take note of that name as it will be used in the configuration later.

Now you'll edit the /etc/network/interfaces file to specify WiFi network connection details.  Run the following command to open the nano text editor:

nano /etc/network/interfaces

You should see a file like the following appear:

Notice there's a commented block showing a WiFi configuration example:

# WiFi Example
#auto wlan0
#iface wlan0 inet dhcp
#    wpa-ssid "essid"
#    wpa-psk  "password"

Configuring most WiFi networks is as easy as uncommenting the lines and filling in the details for your network.  For example if I were connecting to a WiFi network with name "adafruit" and password "mypassword" I would edit the configuration to look like:

# WiFi Example
auto wlan0
iface wlan0 inet dhcp
    wpa-ssid "adafruit"
    wpa-psk  "mypassword"

If you're connecting to a more complex WiFi network, such as one with a 'hidden' SSID or that needs a static IP address, you might need to add more to the configuration.  Check out the guide on setting up WiFi with a Raspberry Pi as the configuration in /etc/network/interfaces is the same on the BeagleBone Black as the Raspberry Pi.

Also be aware that if you found the iwconfig command returned a different interface name, like ra0, you should change all references from wlan0 to the appropriate interface name.

Once you've modified the file, save it by pressing Ctrl-O and Enter, then press Ctrl-X to quit nano.

Now test the connection by running the following to bring up the WiFi connection manually:

ifup wlan0

Again change wlan0 to the name of your WiFi interface if you found it differed with the iwconfig command.

If the WiFi connection is made with your network you should see an IP address acquired with DHCP:

Internet Systems Consortium DHCP Client 4.2.2
Copyright 2004-2011 Internet Systems Consortium.
All rights reserved.
For info, please visit https://www.isc.org/software/dhcp/

Listening on LPF/wlan0/e8:de:27:11:62:7c
Sending on   LPF/wlan0/e8:de:27:11:62:7c
Sending on   Socket/fallback
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6
DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 9
DHCPREQUEST on wlan0 to 255.255.255.255 port 67
DHCPOFFER from 192.168.1.1
DHCPACK from 192.168.1.1
bound to 192.168.1.127 -- renewal in 36491 seconds.

The exact response might differ, but the important thing is that you receive a DHCPOFFER response and are assigned an IP address.  

You can also confirm the BeagleBone Black is connected to the network by running the following command to list network details:

ifconfig wlan0

If your device is connected to the network it should show connection details with an IP address (192.168.1.127 in my case) like:

wlan0     Link encap:Ethernet  HWaddr e8:de:27:11:62:7c  
          inet addr:192.168.1.127  Bcast:192.168.1.255  Mask:255.255.255.0
          inet6 addr: fe80::eade:27ff:fe11:627c/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:15413 errors:0 dropped:0 overruns:0 frame:0
          TX packets:3301 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:21575587 (20.5 MiB)  TX bytes:323282 (315.7 KiB)

Finally you can test internet access by trying to ping a website such as adafruit.com by executing:

ping adafruit.com

You should see successful ping responses such as:

PING adafruit.com (207.58.139.247) 56(84) bytes of data.
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=1 ttl=52 time=86.1 ms
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=2 ttl=52 time=85.8 ms
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=3 ttl=52 time=87.0 ms
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=4 ttl=52 time=87.8 ms
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=5 ttl=52 time=86.1 ms
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=6 ttl=52 time=86.7 ms
64 bytes from vps3.ladyada.net (207.58.139.247): icmp_req=7 ttl=52 time=86.5 ms

Press Ctrl-C to quit the ping application.

If any of the checks above fail or indicate no network access, carefully check the details in the /etc/network/interfaces file are correct for your wireless network and try again.

Now the final test is to reboot your BeagleBone Black to verify the wireless connection is made automatically.  Execute the following to reboot the device:

Once the device has rebooted, connect to it in an SSH session and run the network connection tests above again.  If they show you're connected to the network, congratulations you've successfully configured your BeagleBone Black to work with WiFi!

If the device fails to connect on boot, try running the following to manually reset the WiFi connection:

ifdown wlan0
ifup wlan0

Again changing wlan0 to match the name of the interface you found earlier.

If the ifup command fails to get an IP address, go back and check the WiFi network details in /etc/network/interfaces are correct for your network and try again.  If you still can't get a connection to work, try posting details about the WiFi adapter you're using and the error or issue you're hitting on the BeagleBone Black support group or the Adafruit forums.

This guide was first published on Aug 27, 2014. It was last updated on Sep 19, 2018. This page (Configuration) was last updated on May 04, 2015.