A Perl script to send Caller ID popups from Asterisk to computers running Notify OSD (such as Ubuntu Linux) or any command-line invoked notification system

 

Important
This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog.

This is basically an update to my article, A Perl script to send Caller ID popups from Asterisk to computers running Growl under OS X on a Mac or Growl for Windows, and you should still use that article if you are sending notifications to a computer on your local network that runs Growl or Growl for Windows as the notification system.

I wanted to find a way to send Caller ID popups to a Ubuntu Linux box, and in the process I discovered a different method of sending such notifications.  There are pros and cons to using the new method, so let me explain those first:

Pros:

  • Can send notifications to any computer that supports command line generated notifications (so it could also be used with Growl, if you can use growlnotify from a command prompt to generate a notification).
  • Can send notifications to any computer that you can SSH into, provided you have it set up to use public/private key authentication rather than password authentication.

Cons:

  • Notifications typically display a couple of seconds later than under the previous method.  I suspect this is due to the SSH authentication taking a second or two.
  • It’s a little bit more complicated to set this up, though not horribly so.
  • Because this uses SSH and requires that Asterisk be granted permission to establish an SSH connection as the super user (by using sudo), there may be unforeseen security risks.

Read that last point again, and please understand that as with all projects on this site, I offer this for experimental purposes only.  I explicitly do not warrant this method as being 100% secure, nor will I tell you that it could not be exploited to do bad things on your system.  I don’t think it can (and feel free to leave a comment if you think I’m wrong), but I just don’t know that for sure.  So, if you decide to use anything in this article, you agree to assume all risks. If you’re the type that likes to sue other people when something goes wrong, then you do not have permission to use this code.  We’re all experimenters here, so no guarantees!

As with the previous method, you must have the Perl language installed on your Asterisk server, and you must have the Asterisk::AGI module installed (I’m going to assume you know how to install a Perl module from the CPAN repository – if you have Webmin installed, it can be done from within Webmin). Chances are you already have Asterisk::AGI installed, unless you built your Asterisk server “from scratch” and never installed it.

There’s one additional thing you must do on the Asterisk server before this will run, and that’s allow Asterisk to run the ssh command as root. So, add this to your /etc/sudoers file (probably at the very end, but in any case it should be obvious where to add this because it will be in a section where Asterisk is granted similar privileges with regard to other programs):

asterisk ALL = NOPASSWD: /usr/bin/ssh

Next you want to copy and paste the following Perl script to the filename /var/lib/asterisk/agi-bin/notifysend.agi on your Asterisk server (to create a non-existent file, you can use the touch command, and after that you can edit it in Midnight Commander or by using the text editor of your choice). If this code looks somewhat familiar, it’s because it’s adapted from some code that originally appeared in a FreePBX How-To, which I have modified.

#!/usr/bin/perl
use strict;
use warnings;
use Asterisk::AGI;
my $agi = new Asterisk::AGI;
my %input = $agi->ReadParse();

# Next two lines fork the process so Asterisk can get on with handling the call
open STDOUT, '>/dev/null';
fork and exit;

my $num = $input{'callerid'};
my $name = $input{'calleridname'};
my $ext = $input{'extension'};
my $user = $ARGV[0];
my $ip = $ARGV[1];

if ( $ip =~ /^([0-9a-f]{2}(:|$)){6}$/i ) {
    $ip = $agi->database_get('growlsend',uc($ip));
}

# OMIT this section if you don't want IP address
# checking (e.g. you want to use foo.bar.com)
unless ( $ip =~ /^(d+).(d+).(d+).(d+)$/ ) {
    exit;
}

if ( $ARGV[2] ne "" ) {
 $ext = $ARGV[2];
}

my @months = (
    "January", "February", "March", "April", "May", "June",
    "July", "August", "September", "October", "November", "December"
);
my @weekdays = (
    "Sunday", "Monday", "Tuesday", "Wednesday",
    "Thursday", "Friday", "Saturday"
);
my (
    $sec,  $min,  $hour, $mday, $mon,
    $year, $wday, $yday, $isdst
) = localtime(time);
my $ampm = "AM";
if ( $hour > 12 ) {
    $ampm = "PM";
    $hour = ( $hour - 12 );
}
elsif ( $hour eq 12 ) { $ampm = "PM"; }
elsif ( $hour eq 0 )  { $hour = "12"; }
if ( $min < 10 ) { $min = "0" . $min; }
$year += 1900;
my $fulldate =
"$hour:$min $ampm on $weekdays[$wday], $months[$mon] $mday, $year";

# Next two lines normalize NANP numbers, probably not wanted outside of U.S.A./Canada/other NANP places
$num =~ s/^([2-9])(d{2})([2-9])(d{2})(d{4})$/$1$2-$3$4-$5/;
$num =~ s/^(1)([2-9])(d{2})([2-9])(d{2})(d{4})$/$1-$2$3-$4$5-$6/;

my $cmd = qq(./remotenotify.sh "$name" "$num calling $ext at $fulldate");
$cmd = "sudo ssh $user@$ip '$cmd'";
exec "$cmd";

Also, if you want to be able to specify computers that you wish to send notifications to using MAC addresses rather than IP addresses (in case computers on your network get their addresses via DHCP, and therefore the IP address of the target computer can change from time to time), then you must in addition install the following Perl script (if you have not already done so when using the previous method). Note that if you have a mix of computers on your network and you are using both the new and old methods, you only need to do this once — it works with both methods (hence the reference to “growlsend” in the database and “gshelper” as the name of this script). Call it /var/lib/asterisk/agi-bin/gshelper.agi and note that there is a line within it that you may need to change to reflect the scope of your local network:

#!/usr/bin/perl
use strict;
use warnings;
my ($prev, @mac, @ip);
# Change the 192.168.0.0/24 in the following line to reflect the scope of your local network, if necessary
my @nmap = `nmap -sP 192.168.0.0/24|grep -B 1 MAC`;
foreach (@nmap) {
    if (index($_, "MAC Address:") >= 0) {
        @mac = split(" ");
        @ip = split(" ",$prev);
        `/usr/sbin/asterisk -rx "database put growlsend $mac[2] $ip[1]"`;
    }
    $prev=$_;
}

Make sure to modify the permissions on both scripts to make them the same as other scripts in that directory (owner and group should be asterisk, and the file should be executable), and if you use the gshelper script, make sure to set up a cron job to run it every so often (I would suggest once per hour, but it’s up to you).

Now go to this page and search for the paragraph starting with, “After you have created that file, check the ownership and permissions” (it’s right under a code block, just a bit more than halfway down the page) and if you are using FreePBX follow the instructions from there on out (if you are not using FreePBX then just read that section of the page so you understand how this works, and in any case ignore the top half of the page, it’s talking about a different notification system entirely). However, note that the syntax used in extensions_custom.conf differs from what is shown there, depending on whether you are specifying an IP address or a MAC address to identify the target computer.

First, if you are specifying the IP address of the target computer, then instead of using this syntax:

exten => ****525,1,AGI(growlsend.agi,192.168.0.123,GrowlPassWord,525)

You will need to use this:

exten => ****525,1,AGI(notifysend.agi,username,192.168.0.123,525)

Note that username is the account name you use when doing an ssh login into the destination system, and it should also be the desktop user on the system (not root!). Let’s say that the system is currently at IP address 192.168.0.123. In order for this to work, you need to be able to ssh into your Ubuntu box from your Asterisk server, using the following command from the Asterisk server’s command line:

ssh username@192.168.0.123

If it asks for a password, then you need to follow the instructions at Stop entering passwords: How to set up ssh public/private key authentication for connections to a remote server, and get it set up so that it will not ask for a password (if you don’t like my article, maybe this one will make it clearer).

It’s probably easiest to configure each computer that is to receive notifications to use a static IP address. But note that if you use the above code and have the gshelper.agi program running as a cron job, then after the first time it has run while the computer to receive the notifications is online you should be able to use a computer’s MAC address instead of the IP address. This only works if you’ve used the modified script on this page, not the one shown in the FreePBX How-To. As an example, instead of

exten => ****525,1,AGI(growlsend.agi,192.168.0.123,GrowlPassWord,525)

as shown in the example there, you could use

exten => ****525,1,AGI(notifysend.agi,username,01:23:45:AB:CD:EF,525)

(the above is all one line) where 01:23:45:AB:CD:EF is the MAC address of the computer you want to send the notification to. Once again, just in case you missed it the first time I said it, this won’t work until the gshelper.agi script has been run at least once while the computer to receive the notifications was online. If for some reason it still doesn’t appear to work, run the nmap command (from gshelper.agi) including everything between the two backticks (`) directly from a Linux command prompt and see if it’s finding the computer (depending on the size of your network, it might be several seconds before you see any output, which is why I don’t try to run this in real time while a call is coming in).

If you are NOT running FreePBX, but instead writing your Asterisk dial plans by hand, then you will have to insert a line similar to one of the above examples into your dial plan, except that you don’t need the four asterisks (****) in front of the extension number, and if it’s not the first line in the context, you’ll probably want to use n rather than 1 for the line designator (and, you won’t be putting the line into extensions_custom.conf because you probably don’t have such a file; instead you’ll just put it right in the appropriate section of your dial plan). In other words, something like this (using extension 525 as an example):

exten => 525,n,AGI(notifysend.agi,username,192.168.0.123,525)

This line should go before the line that actually connects the call through to extension 525. I do not write Asterisk dial plans by hand, so that’s about all the help I can give you. And if you don’t write your dial plans by hand, but you aren’t using FreePBX, then I’m afraid you’ll have to ask for help in whatever forum you use for advice on the particular software that you do use to generate dial plans, because I can’t tell you how to insert the above line (or something like it) into your dial plan.

Now is where it gets just a bit more complicated than in the original method. If you have followed the above instructions, you’ll be able to send the notifications to the remote system using SSH, but there will be nothing there to receive them. So we have to create a small script on the receiving system to do something with the received notifications. That script will vary depending on the receiving system, but it must be named remotenotify.sh and it must be placed in the destination user’s home directory, and don’t forget to make it executable! Here’s one that will work in most Ubuntu installations that have Notify OSD installed:

export DISPLAY=:0
notify-send --urgency="critical" --icon="phone" "$1" "$2"

Those two lines are all you need. On a different type of system (or if you have multiple displays) you may need to or wish to do something different. For example, as I mentioned above, if the destination system is running Growl then your remotenotify.sh script will need to call growlnotify, but beyond that I wouldn’t know what to use there (EDIT: But if the target system is a Mac that is running OS X, a pretty good guess would probably be that you’d only need one line, something like this:

growlnotify -s -p 1 -a Telephone -m "$2" $1

In this case it should make the notification sticky until dismissed by the user, give it a priority of 1 — the default is 0 — and use the application icon from the “Telephone” application if you have it installed. Instead of -a to specify an application’s icon you could use -I followed by a path to an .icns file that contains an icon you want to use.  Type growlnotify –help to see all the growlnotify options.  Oh, and before you can make an SSH connection to a Mac you have to go into System Preferences | Sharing and turn on Remote Login).

The beauty of this approach is that you can make the remotenotify.sh script as simple or as complicated as you need — you could even make it forward a notification to other devices if you wish, but figuring out how to do that is up to you (if you come up with something good, please leave a comment and tell us about it!).

If you’re running Ubuntu on the target system, here’s a few articles you may wish to use to help you get your notifications to look the way you want them to appear:

Tweak The NotifyOSD Notifications In Ubuntu 10.10 Maverick Meerkat [Patched NotifyOSD PPA Updated]
Get Notifications With A Close Button In Ubuntu
Configurable NotifyOSD Bubbles For Ubuntu 11.04: Move, Close On Click, Change Colors And More

If you want to be able to review missed notifications, you may be able to use this (as a side note, why don’t they have something like this for Growl?):

Never Miss A NotifyOSD Notification With “Recent Notifications” GNOME Applet

The idea behind the shell script that runs on the target system was found in a comment on the following article, which may be of special interest to MythTV users:

Send OSD notification messages to all systems on a network

There are links to other original sources throughout the article, so feel free to follow those if you want more in-depth commentary.

How to change the format of the time and date in Ubuntu’s clock applet

 

Important
This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog. Also this article is obsolete since recent Ubuntu versions now use the Gnome desktop, and to change the way the date and time are displayed in Gnome you would use a Gnome shell extension such as Panel Date Format (here’s How to install Gnome Shell Extensions on Ubuntu 20.04 Focal Fossa Linux Desktop). Then, if using the Panel Date Format extension, to set the format of the date and time you use a dconf command from the Linux terminal, for example:

dconf write /org/gnome/shell/extensions/panel-date-format/format "'%A, %B %e, %Y  %l:%M:%S %p %Z'"

This is a quick-and-dirty post because it took me a long time to find this but in the end it was simple to do.  Note the graphic below – this is the top menu bar (part of it anyway) and the gconf-editor, which you can get to by entering the program name in a terminal window (in later versions of Ubuntu this appears to have been replaced by dconf Editor, which you may need to first install from the Ubuntu Software Center, then use the second screenshot below).  The important parts are highlighted.  First note the time display in the top menu bar, then note the highlighted settings that were changed to make it that way:

Screenshot of top menu bar and gconf-editor program

When in the gconf-editor, you need to go to /apps/panel/applets/clock_screen0/prefs and then change the custom_format and format parameters as shown (double-click on a parameter name to change the value). The original information was found in this thread.

Note this was done in Ubuntu Karmic, and may or may not be applicable to some newer versions. In more recent versions of Ubuntu that use dconf Editor, this is where the settings are:

Screenshot of dconf Editor program in Ubuntu 12.04

When in the dconf Editor, you need to go to /com/canonical/indicator/appmenu/datetime and then change the custom-time-format and time-format parameters as shown (double-click on a parameter name to change the value — time-format is not highlighted in this screenshot, but you do need to change it to custom).

My custom (time) format string is:

%A, %B %e, %Y  %l:%M:%S %p %Z

If the seconds don’t change (that is, if they always stay at 00) then scroll down (if necessary) in the prefs list and make sure the show_seconds or show-seconds box is checked.

If you don’t like my format and want to create your own, you can find the codes for the various parts of the date format here.

Note that if you are using the XFCE desktop, you need only right-click on the time, select “Properties” from the dropdown, and when the Clock Options come up, select “Custom Format” from the dropdown and then enter your custom format in the text box just below the dropdown.

A Perl script to send Caller ID popups from Asterisk to computers running Growl under OS X on a Mac or Growl for Windows

 

Important
This is an edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog.
Notice
EDIT March, 2014 and August 2020: If you are running OS X Mavericks or later, or any version of MacOS we recommend that you do NOT use the script shown here, but instead send notifications to a XMPP/Jabber account and use either Apple’s Messages app (formerly iChat) or a third party messaging program such as Adium to receive them, since the message will then display in the Notifications Center and you do not need Growl. See How to send various types of notifications on an incoming call in FreePBX for more information. You may also find this thread on the RasPBX forum useful.

What follows will probably not work on ANY currently supported version of MacOS and is left here as a historical reference only.

Quite some time ago, I wrote a post explaining how you could poll a Linksys or Sipura VoIP adapter or phone once per second, and whenever there was an incoming call, generate a notification popup on your computer, if you have the Growl notification service installed.  However, that method doesn’t work if you’re not using a Linksys or Sipura phone or device.

If you are running Asterisk, there’s another way to do it, and that’s to get Asterisk to send the notifications directly. In order for this to work, the computer on which you want to receive the notifications has to be running Growl (under Mac OS X) or Growl for Windows. You must also configure Growl to receive network notifications. I will note here that if you are using a Mac and have never done that before, you may want to make sure that Growl network notifications work before proceeding, because it appears that under OS X, it’s pretty much a crap shoot whether Growl network notifications will work at all, and when they don’t the Growl folks apparently have no clue as to why they don’t. It seems to be a machine-specific thing – on some Macs they work fine, while on others they don’t work at all.

You must have the Perl language installed on your Asterisk server, and you must have the Net::Growl and Asterisk::AGI modules installed (I’m going to assume you know how to install a Perl module from the CPAN repository – if you have Webmin installed, it can be done from within Webmin). Chances are you already have Asterisk::AGI installed, unless you built your Asterisk server “from scratch” and never installed it, but if you’ve never installed Net::Growl you’ll need to do that first.

Next you want to copy and paste the following Perl script to the filename /var/lib/asterisk/agi-bin/growlsend.agi on your Asterisk server (to create a non-existent file, you can use the touch command, and after that you can edit it in Midnight Commander or by using the text editor of your choice). If this code looks somewhat familiar, it’s because it’s adapted from some code that originally appeared in a FreePBX How-To, which I modified.

#!/usr/bin/perl
use strict;
use warnings;
use Net::Growl;
use Asterisk::AGI;
my $agi = new Asterisk::AGI;
my %input = $agi->ReadParse();
my $num = $input{'callerid'};
my $name = $input{'calleridname'};
my $ext = $input{'extension'};
my $ip = $ARGV[0];

if ( $ip =~ /^([0-9a-f]{2}(:|$)){6}$/i ) {
    $ip = $agi->database_get('growlsend',uc($ip));
}

unless ( $ip =~ /^(d+).(d+).(d+).(d+)$/ ) {
    exit;
}

open STDOUT, '>/dev/null';
fork and exit;

if ( $ARGV[2] ne "" ) {
    $ext = $ARGV[2];
}

# Define months and weekdays in English

my @months = (
    "January", "February", "March", "April", "May", "June",
    "July", "August", "September", "October", "November", "December"
);
my @weekdays = (
    "Sunday", "Monday", "Tuesday", "Wednesday",
    "Thursday", "Friday", "Saturday"
);

# Construct date/time string

my (
    $sec, $min, $hour, $mday, $mon,
    $year, $wday, $yday, $isdst
) = localtime(time);
my $ampm = "AM";
if ( $hour > 12 ) {
    $ampm = "PM";
    $hour = ( $hour - 12 );
}
elsif ( $hour eq 12 ) { $ampm = "PM"; }
elsif ( $hour eq 0 ) { $hour = "12"; }
if ( $min < 10 ) { $min = "0" . $min; }
$year += 1900;

my $fulldate =
"$hour:$min $ampm on $weekdays[$wday], $months[$mon] $mday, $year";

# Next two lines normalize NANP numbers, probably not wanted outside of U.S.A./Canada/other NANP places
$num =~ s/^([2-9])(d{2})([2-9])(d{2})(d{4})$/$1$2-$3$4-$5/;
$num =~ s/^(1)([2-9])(d{2})([2-9])(d{2})(d{4})$/$1-$2$3-$4$5-$6/;

register(host => "$ip",
    application=>"Incoming Call",
    password=>"$ARGV[1]", );
notify(host => "$ip",
    application=>"Incoming Call",
    title=>"$name",
    description=>"$numnfor $extn$fulldate",
    priority=>1,
    sticky=>'True',
    password=>"$ARGV[1]",
    );

Also, if you want to be able to specify computers that you wish to send notifications to using MAC addresses rather than IP addresses (in case computers on your network get their addresses via DHCP, and therefore the IP address of the target computer can change from time to time), then you must in addition install the following Perl script. It requires a command-line utility caller arp-scan so install that if you need to – I used to use nmap for this but they changed the output format, making it harder to parse, and arp-scan is much faster anyway. Call it /var/lib/asterisk/agi-bin/gshelper.agi and note that there are two references to 192.168.0… within it that you may need to change to reflect the scope of your local network, if your network’s IP addresses don’t start with 192.168.0.:

#!/usr/bin/perl
use strict;
use warnings;
my @mac;
# Change the following lines to reflect the scope of your local network, if necessary
my @arp = `arp-scan --quiet --interface=eth0 192.168.0.0/24`;
foreach (@arp) {
        if (index($_, "192.168.0.") == 0) {
                @mac = split(" ");
                `/usr/sbin/asterisk -rx "database put growlsend \U$mac[1] $mac[0]"`;
        }
}

Make sure to modify the permissions on both scripts to make them the same as other scripts in that directory (owner and group should be asterisk, and the file should be executable), and also, if you use the gshelper script, make sure to set up a cron job to run it every so often (I would suggest once per hour, but it’s up to you).

Now go to this page and search for the paragraph starting with, “After you have created that file, check the ownership and permissions” (it’s right under a code block, just a bit more than halfway down the page) and if you are using FreePBX follow the instructions from there on out (if you are not using FreePBX then just read that section of the page so you understand how this works, and in any case ignore the top half of the page, it’s talking about a different notification system entirely).  But note that if you use the above code and have the gshelper.agi program running as a cron job, then after the first time it has run while the computer to receive the notifications is online you should be able to use a computer’s MAC address instead of the IP address.  This only works if you’ve used the modified script on this page, not the one shown in the FreePBX How-To.  As an example, instead of

exten => ****525,1,AGI(growlsend.agi,192.168.0.123,GrowlPassWord,525)

as shown in the example there, you could use

exten => ****525,1,AGI(growlsend.agi,01:23:45:AB:CD:EF,GrowlPassWord,525)

(the above is all one line) where 01:23:45:AB:CD:EF is the MAC address of the computer you want to send the notification to.  Once again, just in case you missed it the first time I said it, this won’t work until the gshelper.agi script has been run at least once while the computer to receive the notifications was online.  If for some reason it still doesn’t appear to work, run the nmap command including everything between the two backticks (`) directly from a Linux command prompt and see if it’s finding the computer (depending on the size of your network, it might be several seconds before you see any output, which is why I don’t try to run this in real time while a call is coming in).

If you are NOT running FreePBX, but instead writing your Asterisk dial plans by hand, then you will have to insert a line similar to one of the above examples into your dial plan, except that you don’t need the four asterisks (****) in front of the extension number, and if it’s not the first line in the context, you’ll probably want to use n rather than 1 for the line designator (and, you won’t be putting the line into extensions_custom.conf because you probably don’t have such a file; instead you’ll just put it right in the appropriate section of your dial plan).  In other words, something like this (using extension 525 as an example):

exten => 525,n,AGI(growlsend.agi,192.168.0.123,GrowlPassWord,525)

This line should go before the line that actually connects the call through to extension 525.  I do not write Asterisk dial plans by hand, so that’s about all the help I can give you. And if you don’t write your dial plans by hand, but you aren’t using FreePBX, then I’m afraid you’ll have to ask for help in whatever forum you use for advice on the particular software that you do use to generate dial plans, because I can’t tell you how to insert the above line (or something like it) into your dial plan.

Virtually everything in this article has already been published in one place or another, but I wanted to get it into an article with a relevant title and cut out some of the extraneous explanations and such.  There are links to all the original sources throughout the article, so feel free to follow those if you want more in-depth commentary.

Some notes on creating a home theater PC using the Acer Aspire Revo

 

Important
This is a heavily edited version of a post that originally appeared on a blog called The Michigan Telephone Blog, which was written by a friend before he decided to stop blogging. It is reposted with his permission. Comments dated before the year 2013 were originally posted to his blog.

This article was originally published in January, 2010. Things have changed considerably since then, and most of what was shown in the original article is no longer necessary. You install Ubuntu, then you install XBMC, and it pretty much just works. And if you want an even better experience, you might want to look into installing XBMCbuntu. There may be a few hints in this article that are still applicable but you are very likely going to find that most things just work. One thing you may (or may not) need to do is completely uninstall and then reinstall lirc, because it may not show you the window that lets you select your remote (assuming you have purchased an infrared remote that has a receiver that connects to the USB port), and on the re-install of LIRC you should see the selection window and be able to pick your correct remote.  Or, better yet, you can skip the removal/reinstall by running dpkg-reconfigure lirc from a terminal prompt (which will bring up the remote control selection window).

Another thing that you might want to do is consider using Linux Mint rather than Ubuntu, particularly if you hate the new Unity interface.

The original genesis of this installation was an article at the Lifehacker site entitled Build a Silent, Standalone XBMC Media Center On the Cheap. While that article is probably outdated, you may still want to read it first, then come back here.

The first thing you need to know is that there are several different models of the Acer Aspire Revo out there.  You want the highest powered model you can get, and in particular, the most memory and highest number of processors.  Even the high-end ones are very reasonably priced if you shop around, and even moreso if you can score a good, gently-used unit.  Note that you CAN buy an Acer Aspire Revo with some version of Windows installed, but it will cost you more and (especially in the higher end models) and for a standalone media center, Linux works better anyway, so why pay extra for an operating system you may never use?

You’ll need a wireless or USB keyboard and mouse during the setup phase.  Some Revo sellers include a wireless keyboard and mouse, while others don’t, so just be aware of that when ordering. Read specifications VERY carefully and know what you are buying! Also consider, if you get a defective keyboard (we did), will it cost more to ship it back than what you’d spend to buy a replacement locally (probably yes, if you buy from an overseas seller)? Don’t overlook pre-owned Revo’s — as long as they are still in good working condition and have a model number in the 3000 series or above, they should be fine (the main thing to make sure of is that they have the maximum amount of memory). Be aware that some early models did not have a digital audio output, so if that’s important to you (and it probably is in this application), be careful what you buy.

Also, the Lifehacker article wants you to install the operating system from a thumb drive.  If you have an external CD or DVD drive (that connects using a USB port) do yourself a favor and use that (just install from the distribution CD). By the way, speaking of USB ports, at least some Revo models have a sixth (hidden) USB port. It’s right next to the power switch, on the narrowest part of the case — if you see a small, rubbery insert with a USB logo on it, you can peel that off with your fingernail to reveal the hidden USB port (not that you’d want to unless you really need the sixth port).

Probably the most important thing in that Lifehacker article is the BIOS tweaks. Note that most newer Revos don’t seem to have the “Boot to RevoBoot” option, so if you can’t find that setting, don’t worry about it. Also, if you get a newer, higher end unit with more memory, set the iGPU Frame Buffer Size to 512MB, not the 256MB that the article suggested for the low-end unit that Lifehacker used for their build.

Installing Ubuntu is easy; you basically answer the few questions asked during the installation, and stay with the defaults when you are not sure how to answer. You probably do want it to take over the entire hard drive, so make sure you have saved anything you might want from that drive before you begin the install. We strongly recommend using a 32 bit version of Ubuntu – even though the Revo technically supports a 64 bit operating system, we have found that many things simply don’t work right with the 64 bit OS. If you insist on trying the 64 bit version, you’l probably at the very least need to work through several issues.

If you’re totally inexperienced with Linux, you probably should grab the latest full install disk image of Ubuntu and burn it to a CD, or if you really want to try installing it from a USB memory stick, a visit to the Pen Drive Linux site may help you get the image onto the USB stick in the first place. We used the Ubuntu Minimal CD Image for the install, to save time downloading a huge CD image that is mostly replaced during the software update process. If you go that route, be sure to read the instructions on that page carefully, or you’ll be scratching your head wondering why it’s not working! When you type “tasksel” to select the system to install as instructed, you’ll want to install the standard Ubuntu Desktop but there may be other options you’ll want to install as well, such as an ssh server and/or samba server (those might already be present in the Ubuntu desktop install, but it won’t install anything twice, so I just checked those to be on the safe side).

If you do as most users probably will, and download an ISO file, burn it to a CD, and install from that (using an external CD or DVD drive), just be sure that you check any boxes to install additional codecs or to use additional repositories, if offered any such options.

After installing the operating system, if the nVidia drivers were not installed (very unlikely unless for some reason your video hardware wasn’t detected properly), the next task is to install them.  The system should offer to do this automatically (look for an icon in the top panel).

You can install Software using the Ubuntu Software Center, but not all available software is available there. You can also install Synaptic if you wish, from the Ubuntu Software Center or using apt-get install synaptic from a terminal window. When I mention installing software, I suggest you try the Ubuntu Software Center first, and if you don’t find it there, then try Synaptic or apt-get.

You might want to start by installing mc (Midnight Commander) – I wouldn’t have a Linux box without it, but that’s just me.

In newer versions of Ubuntu you may also want to consider installing ClassicMenu Indicator, which is a notification area applet (application indicator) for the top panel of Ubuntu’s Unity desktop environment. It provides a simple way to get a classic GNOME-style application menu for those who prefer this over the Unity dash menu. Like the classic GNOME menu, it includes Wine games and applications if you have those installed. It looks like this:

ClassicMenu Indicator
ClassicMenu Indicator

If you want to be able to access your HTPC from other computers on your local network using SSH, install openssh (you don’t need to do this if you installed an ssh server using the minimal install, or if you find that ssh already works) and (optionally) sshguard.  Then edit /etc/ssh/sshd_config and change the PermitRootLogin value from “yes” to “no” (for the sake of system security).

Another thing you want to do is make sure that the system time be kept synchronized with Internet servers.  Right click on the clock applet in the top panel, then select Time & Date Settings, and make sure everything looks right there (especially that the option to set the time “Automatically from the Internet” is selected).

Now it’s time to install XBMC.  If you don’t find it in any of the standard repositories or want to make sure you get the latest release version, then do this from the terminal window:

sudo add-apt-repository ppa:team-xbmc
sudo apt-get update
sudo apt-get install xbmc
sudo apt-get update

You might also want to install MythTV, or at least a MythTV frontend. See Links: A complete guide for setting up MythTV from start to finish for more information on that. Note that MythTV can be installed from the Ubuntu Software Center, and that’s the only recommended method, since they tend to offer a more stable version.

If you happen to have a Wii remote control, see the document Building an ION powered HTPC with XBMC and in particular, Module 6 : Using a Wii remote control. The following notes on an IR remote do not apply if you are using a Wii remote!

If you have an infrared remote control and infrared receiver (these generally come together as part of a package; check the XBMC forums to see which are recommended), run XBMC at least once and then run dpkg-reconfigure lirc from a command prompt (terminal window) to select your particular model of remote control.

You will likely want to be able to launch XBMC using the remote.  As a PRELIMINARY way to accomplish this, we opened or created (can’t recall which) a file called .lircrc (note the leading dot character) in the user home directory and put the following lines in:

begin
 prog = irexec
 button = KEY_BLUE
 config = xbmc --standalone &
 repeat = 0
end

begin
 prog = irexec
 button = KEY_POWER
 config = /usr/bin/gnome-session
 repeat = 0
end

begin
 prog = irexec
 button = teletext
 config = sudo shutdown -r now
 repeat = 0
end

This starts XBMC if you push the blue button on the remote.  It also returns to the desktop if you push the power button (however, it may leave whatever program you were in running in the background), and reboots the system if you push the teletext button, but for the latter to work, you must add the following line to the end of your /etc/sudoers file:

%admin ALL = NOPASSWD: /sbin/shutdown

EDIT:  In later versions of Ubuntu the above line does not always work as shown, however, substituting the user name for %admin apparently does.  So for example, if you had users named larry, moe, and curly on your system, you could do this (if you wanted all of them to be able to use the remote button to reboot the system):

larry ALL = NOPASSWD: /sbin/shutdown
moe ALL = NOPASSWD: /sbin/shutdown
curly ALL = NOPASSWD: /sbin/shutdown

Note that this is just to get you started — you can do more complex operations by running an external script rather than the selected program directly, to make your remote work the way you want it to.

By the way, the irexec program must be running for the above to work, so you can use the Ubuntu Startup Applications program to make it run at startup. You should run it with the -d option, e.g. irexec -d in order to make it run as a background process.  Note that you need to do this even in newer versions of Ubuntu.

Startup Applications — Add Startup Program
Startup Applications — Add Startup Program

You will probably want to set up one or more shared folders on your system so you can move videos, etc. into those folders. Be aware that you do have to enable file sharing for each folder you want to share.  This is pretty straightforward in Ubuntu — select the folder you want to share, right click on the folder icon, click on “Sharing Options”, and then give the share a name and check the appropriate boxes:

Folder Sharing options
Folder Sharing options

Check “Share this folder” and give the share a name (I called this one “shared”). Check “Allow others to create and delete files in this folder” even if you are going to require a valid login to do so, otherwise even you will not be able to copy files to that folder or delete existing ones from a remote location.  Check “Guest access” if you want anyone on your local network to have access without the need to supply a user name and password.

If you are trying to get VNC screen sharing (in Ubuntu it’s called Desktop Sharing, but it’s actually VNC) to work, when setting up Desktop Sharing Preferences, make sure that “You must confirm each access to this machine” is UNchecked (it is checked by default).

Desktop Sharing Preferences - UNCHECK "You must confirm each access to this machine"
Desktop Sharing Preferences – UNCHECK “You must confirm each access to this machine”

Then, use the CompizConfig Settings Manager (see How To Change The Settings Of Ubuntu Unity With CompizConfig Settings Manager) and uncheck all the options under “Effects” (except that “Window Decoration” is okay to keep). Apparently, the use of any visual effects is enough to make the remote desktop non-functional:

CompizConfig Settings Manager — Effects
CompizConfig Settings Manager — Effects

The nice thing about this is that even if you have the overscan issue discussed below, when you access the shared Desktop you see the full screen including the top and bottom panels, so you don’t have to guess where you’re clicking! In theory, you could disconnect the keyboard and mouse from the Revo, and just use the Remote Desktop when you need to do system maintenance work, or whatever.

One major issue you may encounter when using a HDTV as the display device is something called “overscan” – that means the desktop is actually larger than the area shown by the HDTV display, meaning you can’t actually see your top panel, etc.  While XBMC has a ways to correct for overscan, it’s better to correct it for the entire system.  In recent Ubuntu versions, the NVidia drivers are installed when Ubuntu is installed (probably only if the installer detects you have NVidia graphics hardware), and the newer drivers do sometimes expose an Overscan Compensation slider that can be used to correct the problem:

NVIDIA X Server Settings (Overscan Compensation slider near bottom)

This slider doesn’t always appear for some reason, and even when it does, you really should try NOT to use it (except, perhaps, during initial setup and configuration) because if set to anything other that “0” it WILL degrade picture quality somewhat.  The proper place to cure overscan is at the HDTV itself.  Most HDTV sets have a setting that will fix overscan, but the problem is that there is no standard name for this setting — I’ve seen it called things like pixel-to-pixel, dot-to-dot, 1:1 display, exact image, etc.  It’s often buried a submenu or two deep (remember that owner’s manual you got with your TV?  Now might be a good time to dig it out!). I’ve found that if you look hard enough, most newer TV’s have this setting, although some do a pretty good job of hiding it (the Sharp LC-42SB45U being an extreme case – it won’t even display the option unless the timing of the signal you send meets certain specifications!).  You really should try very hard to find this option, because it’s much better to correct the problem at the hardware end than by using any software method (that includes the software overscan correction built into XBMC) – you’ll get a sharper picture and quite likely fewer issues with video flickering, etc.  Even if you have to resort to building an xorg.conf file to make it work, that’s better than trying to do software overscan compensation in the video driver or XBMC — use that method only as a last resort.

If your TV set just doesn’t have a setting such as the one mentioned above — and some don’t — there is a page of instructions to help fix the overscan problem here.  We originally wanted this for the aforementioned Sharp LC-42SB45U TV and wasted a huge amount of time trying to find an overscan fix, and you can read what we finally came up with for that particular make and model TV only here: An overscan fix for the Sharp LC-42SB45U television set when connected to a computer with a Linux operating system (Ubuntu, etc.) (and if you have that model TV, it’s preferable to use the xorg.conf file given at that link rather than the Overscan Compensation slider). No matter what, you can see the full screen if you use the VNC/Desktop Sharing service mentioned above, and some have even resorted to using a little workaround to make the overscan less annoying, assuming you don’t find the workaround more annoying than the original problem! And for the more technically astute, it’s always possible to tinker with the ModeLine in xorg.conf (which, again, is preferable to using the Overscan Compensation slider).

Note that the following few paragraphs (up to, but not including, the one about HDMI audio issues) were applicable at the time this article was originally written, but are likely no longer valid due to updates in the nVidia driver and in Kodi (the new name for XBMC).

Irregardless of whether you have overscan issues, if (and ONLY if) you can see any flickering or “tearing” or other weirdness during video playback, it would probably be a good idea to follow the instructions one of these three posts: Either Howto achieve judder free perfectly synced playback at 23.97/59.94 Hz, XBMC and fixing the 24p issue, or HOW-TO setup XBMC and Linux with correct resolution (xorg.conf) (and I’d recommend them in that order — start with the first, and only go on to the second or third if you still have unresolved issues, except that if after trying the technique in the first link, you still see a bit of flicker during the playback of video files then I’d jump right to the third link — that’s the one that fixed it for us on one installation) — in those articles they tell you to modify /etc/X11/xorg.conf and add a couple of lines. I’d suggest a few additional modifications there, if not already mentioned in whichever article you used — under Section “Device” add one or both of these lines

Option "HWCursor" "false"
Option "DynamicTwinView" "false"

The first of those lines is a “blinking cursor fix” and it’s supposed to help if you find an unwanted blinking cursor you can’t get rid of (I haven’t encountered that particular problem yet). The second line enables 1080p 24Hz mode for smoother playback of certain videos (probably most of them, actually). That line can actually go in either “Device” or “Screen” section – I added it to both just to be safe, but that’s probably overkill. Also, at the bottom of the xorg.conf file, add this:

Section "Extensions"
     Option         "Composite" "Disable"
EndSection

That’s supposed to provide better H264 acceleration.

If you added the “DynamicTwinView” “false” option as shown above, and you know for a fact that your monitor supports 1920 x 1080 @ 60 Hz (you should be able to determine that if you followed the instructions in the aforementioned post) then that mode should become available in XBMC — in the XBMC GUI, go to Settings | System | Video Output to select your desired output mode, and see if that mode is available. If, for some reason it is still not available, you might be able to force the issue (you really should not need to do this if you started with the posts linked above, but I’ll leave this information here anyway in case someone needs it) – in order to do that, open a terminal window and do this:

cd /etc/X11/Xsession.d
sudo touch 45custom_xrandr-settings
sudo nano 45custom_xrandr-settings

Paste into this file the following lines, but take the parameters for the first line from the Modeline you created in the previous step, except use “1920x1080_60.00” instead of “1920×1080”.  The first line below is an example (do not copy it verbatim, use the settings from your Modeline) but the second and third can be copied and used as is:

xrandr --newmode "1920x1080_60.00" 173.00 1920 2048 2248 2576 1080 1083 1088 1120 -hsync +vsync
xrandr --addmode default 1920x1080_60.00
xrandr --output default --mode 1920x1080_60.00

One other thing that might improve the video quality in XBMC is to go to Settings | Video | Playback settings and change the setting Adjust display refresh rate to match video to On start/stop (you could also try Always). This fix may be of particular help if you are trying to watch Live TV, or recorded TV from a PVR backend, and the picture doesn’t appear quite as sharp as it should. Leave Pause during refresh rate change set to Off. Obviously, this would be most noticeable if you are trying to view a 1080p source. In some areas you may need to play with the de-interlacing options as well, but that is beyond the scope of this article, and we didn’t find a need to do that.

If you are having audio issues when trying to send audio via HDMI, first of all open a terminal window and enter alsamixer and when it comes up press F6 to select your sound card (most likely HDA nVidia) and then make sure that none of the S/PDIF outputs are muted (this will me indicated by “MM” whereas an unmuted one will show “00”). Pay particular attention to S/PDIF 1 as it is often the culprit – use the arrow keys to select it and then press M to unmute it, then ESC to exit. I know this doesn’t make sense since you are trying to send audio out the HDMI port and not the optical audio port, but trust me, you need to do this. Then, if you are finding that audio is coming from the wrong speakers (center and LFE channels are mixed up with left and right surround channels) go to this page: HOW-TO:Remap HDMI audio on Gen 1 ION – Linux – I suggest using the settings under “1.3.1 ALSA Configuration” and below, but read the entire page first to get the full overview. Note that after following the instructions on that page, if you are also running the MythTV frontend you may have to set the audio to use ALSA:hdmi_direct and that this will NOT appear in the dropdown – you should first select one of the other compatible HDMI card options and then edit the Audio Output Device field to show ALSA:hdmi_direct. This is all necessary because the NVIDIA MCP79/7A HDMI hardware has incorrect channel mapping. This problem does NOT appear when using the S/PDIF (optical) output.

If you want to use a web browser to view videos that require the Flash plugin (such as many YouTube videos), particularly if you will be trying to view them in fullscreen mode, you should know that the Flash plugin will not use the Revo’s onboard nVidia graphics unless you tell it to. But, if you don’t do that the videos will most likely be too jerky to watch. So here is what you need to do from a Linux command prompt:

sudo mkdir /etc/adobe/
sudo nano /etc/adobe/mms.cfg

Now insert the following two lines into the file you’ve just opened:

EnableLinuxHWVideoDecode=1
OverrideGPUValidation=true

Then press CTRL+X followed by Enter to save the new file.

Note that this fix does not work absolutely perfectly, so you might still see some video issues now and then, and it might not work on all sites or in all browsers (it does work in Firefox, however). In many cases the video will be far more watchable than without the fix, but on some systems this fix could cause browser crashes and if those become frequent you may need to try removing the /etc/adobe/mms.cfg file. Also, note that this fix will only improve videos played using the Flash plugin.

If you need to (re)format a hard drive to use with your system, and you don’t want any wasted space on the drive, be sure to read this: Free Disk Space by Reducing Reserved Blocks

If you want your system to have a fixed IP address on your local network, click on the networking icon in the top panel (up and down arrows side by side), then Edit Connections, then find the connection you are using and edit it appropriately. For example, under the Wired tab I see Wired Connection 1, and if I click on that and then click the Edit button, I can then select the IPv4 Settings tab, change the method to Manual, and then enter the appropriate settings for my local network.

You may find that you need to go to the “Misc” section of /etc/samba/smb.conf and set domain master = no — otherwise you may find that certain network shares randomly disappear from other computers on your network. If you don’t have the problem of shares disappearing from other computers on your network, or if you don’t have any other servers or computers that are also trying to assert themselves as a master browser, then this may not be an issue for you.

If you have Macs on your local network and would like to use AFP (Apple File Protocol) to move files around, see How to set up AFP filesharing on Ubuntu.

If you hate typing in a password each time you ssh into your Revo, see Stop entering passwords: How to set up ssh public/private key authentication for connections to a remote server.

If you want to reduce startup time when using Ubuntu or Mint (and you do not have more than one operating system installed), do this:

sudo nano /etc/default/grub

Then look for this line:

GRUB_TIMEOUT="10"

Change this line to read:

GRUB_TIMEOUT=0

Then follow the instructions at the top of the file: “If you change this file, run ‘update-grub’ afterwards to update.” This also must be done as root, so after you save the file and exit nano, do this:

sudo update-grub

If you allow the Update Manager to install certain types of updates (particularly nVidia driver updates) — and you should update your software when updates are available — you may find that XBMC won’t start up, but instead displays a message that stats with the words, “XBMC needs hardware accelerated OpenGL rendering.” Typically, simply rebooting the system will fix that issue.

If you are using the Perl script we posted a couple of years ago that monitors a Linksys or Sipura VoIP device and provides Caller ID popups when a call comes in, you may be interested to know that by adding one line to the Perl script and making some minor configuration modifications, you can also have Caller ID popups in XBMC. See our article BETA Perl script for Caller ID popups when using Linksys/Sipura devices for information. Alternately, if you have an Asterisk server, you can send Caller Id information to XBMC by adjusting the XBMC configuration as in the aforementioned article, and then adding a line to your Asterisk dial plan in the form:

exten => extension-number,n,TrySystem(wget -b -O /dev/null -o /dev/null "http://HTPC-IP-address:8080/xbmcCmds/xbmcHttp?command=ExecBuiltIn&parameter=XBMC.Notification(Call%20from%20%22${URIENCODE(${CALLERID(name)})}%22%2C${CALLERID(number)}%20calling%20extension-number%2C15000%2C%2Fhome%2Fusername%2Fphone.png)")

Note that is all one line, and be sure to change the bold, italicized values to something appropriate for your configuration, and also be sure to see the aforementioned articles for XBMC configuration information and to get the phone.png icon.

If you would like to occasionally play music without the need to have the TV running, you might want to install a program called Audacious. The nice thing about Audacious is that it offers a LIRC plugin (under the General plugins section) and if you enable that, and then add a section to your .lircrc file (for an example, follow this link and then scroll down to the section “Configure Audacious(2) to use Lirc“), you can control the program using your remote.

Audacious Preferences

If you set Audacious to “Continue playback on startup” (under the Playback section of the preferences), and then create a .lircrc entry to start Audacious, you could use your remote to turn on Audacious and resume wherever it left off on your playlist.  This is really beyond the scope of this article, but I just thought I’m mention it for those who have your Revo hooked up to a receiver and would like to be able to play audio without wasting electricity running a TV you’re not watching.

Addendum for those who wish to use Boxee under Ubuntu 12.04:

Boxee has discontinued support for desktop platforms, but you might be able to install the last Linux desktop version by following the instructions on this page to install Boxee (note particularly the unmet dependency that must also be installed), and then if you are using a MCE remote, you must also follow the instructions in this post to make the remote work correctly with Boxee.