NAME

Audio::Radio::Sirius - Control a Sirius satellite radio tuner

VERSION

Version 0.03

SYNOPSIS

Sirius satellite radio (http://www.sirius.com) is a US based satellite radio serice. While none of the tuners they make have serial or USB connectors, it has been found that generation 2.5 tuners (Sportster, Starmate, * Replay, Sirius Connect, and others) have a common tuner module. Furthermore this tuner module generally has a serial interface. Presently only one commercial site is offering a modification for adding a serial port to a Sirius tuner: http://www.rush2112.net. Google should reveal schematics and parts needed for adding ports to other tuners.

Once your tuner is connected to your system and accessible via a serial port like device, you can use this module to access it:

  use Audio::Radio::Sirius;
  use Win32::SerialPort; # or Device::SerialPort on Linux

  my $serial = new Win32::SerialPort('com1');
  my $tuner = new Audio::Radio::Sirius;

  $tuner->connect($serial);
  $tuner->power(1);
  $tuner->channel(184); # tune in the preview channel

CONSTRUCTOR

new

Call new to create an instance of the Sirius radio object. Once the object is created, you will probably want to connect to it.

OBJECT METHODS

connect (serialport object)

Connect establishes a connection between the tuner object and the SerialPort object. The SerialPort object must be a Win32::SerialPort or a Device::SerialPort.

  require Win32::SerialPort;
  
  my $serial_port = new Win32::SerialPort('com1');

  $tuner->connect($serial_port);

power (state)

Use to turn the radio on (1) or off (0). Returns true if succeeded.

  $tuner->power(1); # Power on tuner.

gain (db)

Gain ranges from -9db to 0db. It defaults to 0. When called with a parameter, gain returns false on failure and true on success. When called without a parameter, gain returns the current gain setting.

  $tuner->gain(-6); # Mom's on the phone, turn down Howard Stern

  my $current_gain = $tuner->gain;

mute (mute setting)

When called with a parameter, you can set it to 1 to mute and 0 to unmute. Called without a parameter retrieves the current setting.

  my $result = $tuner->mute(0); # Unmute the tuner

  my $muted = $tuner->mute;

channel (channel number, offset)

Can be used without a parameter to get the current channel number or with a parameter to change channels. When used with a parameter, returns true on success and false on failure. Offset is -1 to select the channel before the specified number, 1 to select the channel above the specified number, or 0 (default) to simply go to the specified channel.

  my $current_channel = $tuner->channel;

  my $result = $tuner->channel(6, 1); # Tune to channel 7

  $tuner->channel(100); # Tune directly to channel 100

monitor (cycles)

Monitor is called to watch for updates from the tuner. The Sirius tuner is pretty chatty and sends relevant data, such as Artist/Title updates, PIDs, signal strength, and other information. Calling monitor initiates reads of this data.

Reads happen automatically when commands are executed (for example changing the channel or muting the tuner). Still, monitor generally needs to be called as often as possible to gather the latest data from the Tuner.

A monitor cycle will take a minimum of one second. If data is received, this timer resets. In other words, monitor may take longer than you anticipate. The amount of time monitor takes will depend on the verbosity of the tuner.

If no number of cycles is specified, monitor runs one cycle.

Note: As of version 0.02, the cycle parameter is no longer a true count of the number of cycles. The number specified is multiplied by 20. Each cycle now sleeps 50 msec so the result is roughly the same, although this may increase the drift of cycles vs. seconds even more.

  $tuner->monitor(5); # spin 5 times

set_callback (callback type, function reference)

When the tuner sends an update, such as new artist/title information on the current channel, it may be helpful to execute some code which handles this event. To accomidate this, you may define function callbacks activated when each event occurs. Note that some of the parameters below are marked with an asterisk. This indicates that they may be undefined when your function is called. You should account for this in your callback function.

channel_update (channel, *pid, *artist, *title, *composer)

 $tuner->set_callback ('channel_update', \&channel);

 sub channel {
        my ($channel, $pid, $artist, $title, $composer) = @_;
        print "Channel $channel is now playing $title.\n";
 }

signal_update

Not yet implemented.

time_update

Not yet implemented.

status_update

Not yet implemented.

verbosity (level)

Not to be confused with debug, verbosity changes the updates the tuner sends. By default, the tuner only sends updates for artist/title/PID on the current channel. The Generation 2.5 tuners can send artist/title on all channels, the current time, signal strength, and PID information on all channels.

Internally the tuner treats verbosity as a bitmap allowing you to control each type of update you are interested in. For now, this module treats it as a boolean. 0 (default) requests that no updates be sent. 1 requests that all of the following updates are sent:

• Artist/Title information for every channel

• PID information for every channel

• Signal strength

• Current time

  $tuner->verbosity(1); #request all of these updates
  $current_verbosity=$tuner->verbosity;

DEPENDENCIES

None yet.

AUTHOR

Jamie Tatum, http://thelightness.blogspot.com, <jtatum@gmail.com>

BUGS

• You should be able to submit a function reference to be called when the various updates (channel info, time, signal, pid) occur. This is not yet implemented.

• The power system needs to be revisited. Currently connect turns the radio off - it should probably preserve state between sessions.

• The channel property isn't being set (correctly anyway).

• Various public properties need to be documented.

Please report any bugs or feature requests to bug-audio-radio-sirius@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Audio-Radio-Sirius. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS

Thanks to Mitch and Dale at http://rush2112.net Thanks to everyone who reversed a little bit of the tuner protocol - too many to list. :) You know who you are.

COPYRIGHT & LICENSE

Copyright 2005 Jamie Tatum, all rights reserved.

Sirius and related marks are trademarks of SIRIUS Satellite Radio Inc. Use of this module is at your own risk and may be subject to the SIRIUS terms and conditions located at http://www.sirius.com/serviceterms.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Audio::Radio::Sirius

perl -MCPAN -e shell
install Audio::Radio::Sirius