Install and Recover with TFTP

Introduction

This document is designed to help you recover the Commotion software if the Install on a Ubiquiti Device instructions did not work, or if your router has malfunctioning software and needs to be installed again or updated. It contains instructions on using a protocol called Trivial File Transfer Protocol (TFTP) to install the software.

You will find instructions specific to the operating system you are running on your computer - either Windows, Mac OSX, or Linux. Please proceed to the section for your operating system below.

This process takes longer than the basic instructions. Add another half hour to an hour for the additional setup steps on these pages.

Materials + supplies needed

To recover a Commotion installation, you will need the following items on-hand:

  1. A computer with an Ethernet port.
  2. A Ubiquiti router and its Power over Ethernet (PoE) adapter and power cable.
  3. Access to a power outlet.
  4. Two Ethernet cables.
  5. The appropriate Commotion software image from the downloads page.

Proceed to the installaton instructions for your platform, below:

Instructions for Windows

Getting started

This guide should work with any version of Microsoft Windows from Windows XP on. If you aren't sure what version of Windows you have, click on the Start Menu and type winver in to the Run menu or the Search box. The most likely responses are Windows XP, Windows Vista, or Windows 7.

You can either install the Commotion software onto your router with a graphical user interface (GUI) program for TFTP, or by using the command line. We recommend the GUI option if you are new to this process. First download the TFTP2 client and install it on your computer. After this, you will prepare the router for TFTP and then load the software.

Prepare your computer for TFTP

First, configure your computer's wired connection with the address 192.168.1.254. You can do this in the Control Panel section for network connections, under the Ethernet port settings.

Next, the Ubiquiti router must be put in a special mode to load files on to it using TFTP. To set the router to recovery mode, it must be powered on with the Reset button pressed, until the status lights flash in a special order. To put your router in recovery mode:

  1. If your router is already plugged in to power, remove the Ethernet cable from the bottom of the router. The lights on the router will go off.
  2. Take a paper clip with one end bent out, and gently depress the Reset button on the underside of the wireless router, next to where the Ethernet cable plugs in.
  3. While holding the Reset button down, plug in the Ethernet cable, which will power on the router.
  4. While keeping the Reset button held down, watch the lights on the front of the unit. The lights under the triangle will do a special dance, shown below.

There are two possible sequences of lights for Ubiquiti routers. Your device will go through one of the two light progressions below.

Original Ubiquiti light sequence

First, the two middle lights - one Orange and one Green - will light for a few seconds, then go out.

Next, the lights from left to right will light up in order: Red, Orange, Green, and Green again.

Finally, the 1st and 3rd will light, then the 2nd and 4th, over and over.

 

New Ubiquiti light sequence

First, the two middle lights, One orange and one Green, will light for a few seconds, then go out. The lights will remain off for about 10 sections - be patient!

Next, all of the lights will flash on, then turn off. This will happen three times.

Finally, the 1st and 3rd will light, then the 2nd and 4th, over and over.

Once the router is in the final stage - where the two sets of lights are flashing back and forth, the unit is in TFTP mode. You can release the Reset button at this point. If 30 seconds to a minute pass and the lights do not cooperate, you may need to try again. Unplug the Ethernet cable and start the process again.

 

Recovery mode is only enabled for a short amount of time. If the router does not accept the software, you will need to restart the Reset button process. Typically you will need to restart if it has been in recovery mode for more than three minutes.

Install the software on the router

We will go through the GUI installation process first, which is recommended. If the TFTP2 program does not work for you, proceed to the command line instructions below and try those.

Using a GUI Interface

TFTP2 is a very simple TFTP client that includes only the settings necessary to install the software. Use the link in External Resources below to download and install the program before proceeding, if you haven't done that already.

  1. Enter 192.168.1.20, the router’s IP address, in the “Server” field.
  2. Leave the “Password” field blank
  3. Open the file broswer, navigate to where you downloaded the Commotion software file, and select it.
  4. Put the router in TFTP mode as described above (if it isn't already), and click “Upgrade.”
  5. If your router is ready and the IP addresses are properly configured, a blue progress bar will appear. When it is finished, you will see the message "Firmware was upgraded successfuly!" (ignore the “Retry” line).

After a minute or two, the router should reboot and start loading Commotion. Proceed to the document Configure Commotion to finish setting up the device.

Using the command line

If the TFTP2 program doesn't work for you, try using TFTP on the Windows command line. The specific instructions are slightly different for different versions of Windows, so read below for your specific version.

Windows XP

This version of Windows has a TFTP client built-in. You will just need to browse to your Command Prompt by clicking the Start Menu, selecting Run, and typing cmd.

You should get a window titled "C:\WINDOWS\system32\cmd.exe", or similar.

This program will give you a text interface to your Windows system, where we can execute the TFTP program. It should look something like:

C:\Documents and Settings\your user name>

First, we need to navigate to the folder where you saved the Commotion image file.

To do that, type in: cd "path to the folder where you saved the file" and hit Enter.

This may look something like cd Desktop or cd Downloads - or something else. If you aren't sure, you can use the Windows Explorer file browser to find the file, and then click in the top address bar. The full directory path should appear. You can then type this in to the Command Prompt after the cd command.

It should look something like this: tftp -i 192.168.1.20 put exact-name-of-file.bin

The command breaks down in to these parts:

tftp
The name of the actual program we are running

-i
Sets this to binary mode, which is required since we are sending a file and not text.

192.168.1.20
The address of the router we are working on.

put
The command to the TFTP program to send a file from the PC to the device.

exact-name-of-file.bin
The Commotion image for our hardware, as downloaded from the Commotion downloads page

Once you have executed that command, there should be some text or a progress indicator that lets you know if the file transferred to the device correctly. If there is an error message, go back and make sure you are in the correct directory, and that you typed everything in correctly.

If all goes well, after a minute or two, the router should reboot and start loading Commotion. Proceed to the document Configure Commotion to finish setting up the device.

Windows Vista and Windows 7

These versions of Windows don't come with a TFTP client by default, but it can be installed fairly easily in the "Add Windows components" menu. In order to find this menu:

  1. Click the Start Menu, then Control Panel.
  2. In the window that opens, select the "Programs" option.
  3. There should be an option to "Turn Windows features on or off", select this.
  4. A "Windows Features" menu should appear - scroll until you see the "TFTP Client" option, then select it and hit Ok or Apply.
  5. The TFTP client should install.

From here, you can use the Windows XP instructions above, since everything should work identically once the client is installed.

Instructions for Mac OSX

This guide should work with any version of Mac OSX.

Getting started

The Ubiquiti device is listening for a TFTP connection on a specific address. For your computer to connect, it will need an IP address with the following settings:

Static IP address: 192.168.1.254
Subnet mask: 255.255.255.0
Gateway: 192.168.1.1

There is a command line or a graphical user interface (GUI) option to install the Commotion software onto your router. Both methods are discussed in detail below, but we recommend following the GUI method. You can download the GUI program MacTFTP Client and install it on your computer. You can download the program from Mac Technologies.

Prepare your computer for TFTP

The Ubiquiti router must be put in a special mode to load files on to it using TFTP. To set the router to recovery mode, it must be powered on with the Reset button pressed, until the status lights flash in a special order. To put your router in recovery mode:

  1. If your router is already plugged in to power, remove the Ethernet cable from the bottom of the router. The lights on the router will go off.
  2. Take a paper clip with one end bent out, and gently depress the Reset button on the underside of the wireless router, next to where the Ethernet cable plugs in.
  3. While holding the Reset button down, plug in the Ethernet cable, which will power on the router.
  4. While keeping the Reset button held down, watch the lights on the front of the unit. The lights under the triangle will do a special dance, shown below.

There are two possible sequences of lights for Ubiquiti routers. Your device will go through one of the two light progressions below.

Original Ubiquiti light sequence

First, the two middle lights - one Orange and one Green - will light for a few seconds, then go out.

Next, the lights from left to right will light up in order: Red, Orange, Green, and Green again.

Finally, the 1st and 3rd will light, then the 2nd and 4th, over and over.

 

New Ubiquiti light sequence

First, the two middle lights, One orange and one Green, will light for a few seconds, then go out. The lights will remain off for about 10 sections - be patient!

Next, all of the lights will flash on, then turn off. This will happen three times.

Finally, the 1st and 3rd will light, then the 2nd and 4th, over and over.

Once the router is in the final stage - where the two sets of lights are flashing back and forth, the unit is in TFTP mode. You can release the Reset button at this point. If 30 seconds to a minute pass and the lights do not cooperate, you may need to try again. Unplug the Ethernet cable and start the process again.

 

Recovery mode is only enabled for a short amount of time. If the router does not accept the software, you will need to restart the Reset button process. Typically you will need to restart if it has been in recovery mode for more than three minutes.

Install the software on the router

You will now install the Commotion software using the GUI program. If it doesn't work, try using the command line method below.

Using the GUI Interface

The MacTFTP Client includes only the settings necessary to install the software on a device. You can download it from the link in External Resources and install the program, if you haven't already.

Once you have installed MacTFTP Client, make sure your computer's IP address is set correctly as mentioned above in Getting Started. Then prepare your router and open the MacTFTP Client.

  1. Make sure the “Send” button is highlighted.
  2. Enter 192.168.1.20, the router’s IP address, in the “Address” field.
  3. Leave the “Password” field blank.
  4. Open the file broswer, navigate to where you downloaded the Commotion image, and select it. Put the router in TFTP mode, and immediately after.
  5. Click “Start”

After the software loads, you should see the message "Transfer completed successfully". After a minute or two, the router should reboot and start loading Commotion. Proceed to the document Configure Commotion to finish setting up the device.

Using the command line

All versions of Macintosh OSX should have a TFTP client installed. It is accessible from the Terminal program, which is a text-based interface to the OSX system. You can find this program by navigating from the Applications folder to the Utilities folder.

From there, launch the program titled "Terminal", it should open a command line interface titled "Terminal - bash", or something similar.

The window may look different, depending on the version of OSX you are using. You should see a prompt that looks something like:

computername:~ username$

First, we need to navigate to the folder where you saved the Commotion image file. To do that, type cd "path to the folder where you saved the file" and hit Enter.

This may look something like cd Desktop or cd Downloads - or something else. If you aren't sure, you can use the Finder to browse to the file, and then hit command I. The "Get Info" dialog should appear, where you can find the full path under the General tab, labeled "Where:". You can then type this in to the Terminal after the cd command. To verify the files are in your current directory, you can type ls, which should display a listing of files.

Once you are in the proper directory, you can run the TFTP client. To do this, just type tftp at the prompt and hit enter. Your command line should change to the following:

tftp>

From here, enter these commands in sequence:

connect 192.168.1.20- Instructs the client to talk to the router.

verbose- Instructs the client to provide more detailed reports on what it is doing.

binary- Since we are transferring a file, and not text, this is required.

put exact-name-of-file.bin

You should see some numbers flash by, then a line that states something like "Sent ### bytes in ##.# seconds [### bits per second]". You can then type quit at the prompt, and your terminal will change back to the normal mode.

If there is an error message, go back and make sure you are in the correct directory, and that you typed everything in correctly. You can then proceed to Configure Commotion to finish setting up the device.

Instructions for Linux

Getting Started

Depending on your distribution of Linux, you may or may not not have a TFTP client installed by default. You can check this at the terminal, and if it turns out you do not TFTP installed, it will be possible to install a client at the terminal, then use it.

First, open the Terminal application:

  • If you use Gnome as your window manager, you should be able to find a terminal program in the main menu, under Accessories -> Terminal.
  • If you use KDE as your window manager, you should be able to access the terminal program in the KMenu, under System -> Konsole.
  • If you use another window manager, chances are you know how to access the terminal already.

If you aren't sure, or don't have a window manager, just go to a terminal by pressing ALT, CTRL and the number 1 or 2. This should bring up a full screen terminal. You will most likely have to log in using whatever credentials you first set up on the computer.

From here, you will see a prompt similar to: computername:~ $

Type: which tftp at this prompt and hit enter. This will return one of two things: the location of the tftp program if you have it installed, or it will return an error.

If you have a tftp client, the output should look like: /usr/bin/tftp

If you don't have one, the output will look something like: which: no tftp in (/path...

If you have a TFTP client installed, you can skip down a few steps. If you don't have one, you will need to install a client before moving on. How you install this is dependent on which distribution of Linux you are using. We will detail the commands to type for the few most common distributions below. The commands are shown at the normal prompt we started from above. You will need to know the administrator (root) password you set up when the system was first installed.

Ubuntu: $ sudo aptitude install tftp

Debian: $ sudo apt-get install tftp

Arch: $ sudo pacman -Ss tftp-hpa

Fedora: $ sudo rpm -i tftp

Since we can't cover every distribution of Linux, if you aren't sure how to install the TFTP client package on your computer, use Google!

After typing in the correct command for your distribution, you should see a confirmation on the screen that your package was installed. To verify, you can type which tftp at the prompt again. If you receive a single path response, as show above, you should be good to go.

Prepare your computer for TFTP

The Ubiquiti device is listening for a TFTP connection from only a single source, or computer with a specific address. You will need to set the IP address of your computer with the following settings:

Static IP address: 192.168.1.254
Subnet mask: 255.255.255.0
Gateway: 192.168.1.1

If you need help assigning a static IP address for your Linux computer, search for your specific version of linux and "static IP address".

The Ubiquiti router must be put in a special mode to load files on to it using TFTP. To set the router to recovery mode, it must be powered on with the Reset button pressed, until the status lights flash in a special order. To put your router in recovery mode:

  1. If your router is already plugged in to power, remove the Ethernet cable from the bottom of the router. The lights on the router will go off.
  2. Take a paper clip with one end bent out, and gently depress the Reset button on the underside of the wireless router, next to where the Ethernet cable plugs in.
  3. While holding the Reset button down, plug in the Ethernet cable, which will power on the router.
  4. While keeping the Reset button held down, watch the lights on the front of the unit. The lights under the triangle will do a special dance, shown below.

There are two possible sequences of lights for Ubiquiti routers. Your device will go through one of the two light progressions below.

Original Ubiquiti light sequence

First, the two middle lights - one Orange and one Green - will light for a few seconds, then go out.

Next, the lights from left to right will light up in order: Red, Orange, Green, and Green again.

Finally, the 1st and 3rd will light, then the 2nd and 4th, over and over.

 

New Ubiquiti light sequence

First, the two middle lights, One orange and one Green, will light for a few seconds, then go out. The lights will remain off for about 10 sections - be patient!

Next, all of the lights will flash on, then turn off. This will happen three times.

Finally, the 1st and 3rd will light, then the 2nd and 4th, over and over.

Once the router is in the final stage - where the two sets of lights are flashing back and forth, the unit is in TFTP mode. You can release the Reset button at this point. If 30 seconds to a minute pass and the lights do not cooperate, you may need to try again. Unplug the Ethernet cable and start the process again.

 

Recovery mode is only enabled for a short amount of time. If the router does not accept the software, you will need to restart the Reset button process. Typically you will need to restart if it has been in recovery mode for more than three minutes.

Install the software on the router

Now we need to navigate to the folder where you saved the Commotion image file for your router.

To do that, type in: cd "path to the folder where you saved the file" and hit Enter.

This may look something like cd ~/Desktop or cd ~/Downloads - or something else. If you aren't sure, you can use Nautilus in Gnome to browse to the file, and hit Control-L. This should display the path to the directory you are viewing. Using Konqueror in KDE, browse to the file, and then read the path in the top statusbar.

Once you are in the proper directory, you can run the TFTP client. To do this, just type tftp at the prompt and hit enter. Some cilents will ask you (to), at which point you put in the IP address 192.168.1.20. Your command line should change to the following:
tftp>

From here, enter these commands in sequence:

connect 192.168.1.20 - If you didn't put it in at the (to) prompt. Instructs the client to talk to the router.

verbose - Instructs the client to provide more detailed reports on what it is doing.

binary- Since we are transferring a file, and not text, this is required.

put exact-name-of-file.bin- The Commotion image for the hardware, as mentioned in the document "Installing Commotion on Wireless Nodes".

You should see some numbers flash by, then a line that states something like "Sent ### bytes in ##.# seconds [### bits per second]". You can then type quit at the prompt, and your terminal will change back to the normal mode.

If all goes well, after a minute or two, the router should reboot and start loading Commotion. Proceed to the document Configure Commotion to finish setting up the device.

Definitions

TFTP
a file transfer protocol notable for its simplicity. It is generally used for automated transfer of configuration or boot files between machines in a local environment.
Firmware
the combination of persistent memory and program code and data stored in it. In other words, a very small and basic operating system for devices like appliances, computers, digital watches, digital cameras, mobile phones, and more.

External Resources

For Graphical User Interfaces (GUIs) to help with the TFTP process:

Windows: TFTP2 from Shadow Software

Mac OSX: Mac Technologies TFTP client