[Back to the Floodgap main page] Return to Floodgap Software

radioSH

radioSH (say it "radio shell") is a Mac OS X command-line controller for the venerable USB-based Griffin radioSHARK, allowing you to programmatically control its two LED notifiers and tune to arbitrary FM and AM radio stations from scripts and your shell (hence radio shell like "C-shell," "Bourne again shell," etc., get it?).

[V1 RadioShark, in use.] Sure, you could just run the Griffin radioSHARK software (which is even AppleScript-able, at least version 2), but it's officially limited to 10.6 and earlier, and much less convenient for behind-the-scenes or headless setups; radioSH adeptly covers both those use cases. Roll your own cron or background daemons for recording or automatic jobs, or use a radioSHARK to receive your local low-power transmitter as an easy way to synchronize audio between multiple sources. Or just twiddle the LEDs and use it as a status device or trouble beacon. Whatever tunes your coil, man.

radioSH happily runs on any Mac, PowerPC or Intel, from 10.4 Tiger to 10.13 High Sierra. It is offered as a 32-bit Universal binary, with source code available. Both the white version 1 RadioSHARK and the black version 2 radioSHARK are supported. Because it is an unsigned executable, 10.7+ users may need to temporarily adjust their Gatekeeper settings.

Using radioSH

Basic usage summary:

% radiosh 
Usage: radiosh [-v] [-b#] [-p#] [-r#] [-a#] [-f#]
    -v    Verbosity/display detected device version.
    -b    Set the blue light brightness, values are 0 (off) to 127.
    -p    Set the blue light pulse speed, values are 0 (off) to 127 (slow).
    -r    Set the red light brightness, values are 0 (off) to 127.
    -a    Set the radio to AM and tune to frequency in kHz (0=radio off).
    -f    Set the radio to FM and tune to frequency in MHz (0=radio off).
Any combination can be specified at once.

Copyright (C) 2018 Cameron Kaiser, Quentin D. Carnicelli,
Michael Rolig, Justin Yunke and Hisaaki Shibata. All rights reserved.
http://www.floodgap.com/software/radiosh/ -- version 1.0
The radioSHARK is a somewhat complex device under the hood fin. It exposes the LED and radio tuner functionality as a HID (on its third interface, #2) and sends the audio either analogue through a 3.5mm stereo headphone jack or digitally via USB audio (on the other two interfaces). Your headphones can act as an antenna and audio output can go to both endpoints simultaneously.

To use radioSH, just have your radioSHARK plugged in and then pass it the appropriate options (such as radiosh -a640 to tune the radio to 640kHz AM, or radiosh -f99.9 to tune to 99.9MHz FM). For tips on improving radio reception, see below.

The executable automatically detects if you have a v1 (white) or v2 (black) device; to see which one it detected, add the -v option. Options you don't set are left undisturbed, or you can set multiple options at once (see below for LEDs), though if you specify both AM and FM tuning only the last option is used. Specifying an option multiple times just replaces the option with the next one. To turn the radio off, tune either AM or FM to "0".

Once the radio is tuned, any utility that can playthru USB audio will play the stream on your Mac. No third-party driver is required. QuickTime Player can do this with a New Audio Recording, using the radioSHARK as the source, or you can use a tool like LineIn (free, PowerPC compatible) or SoundSource (not free, not PowerPC compatible), or, if you prefer something open source, the Audio Monitor app in the MTCoreAudio framework package. (Here is some example source code using MTCoreAudio.) Or just hook it up to some speakers or headphones, or your Mac's line input.

If you have multiple radioSHARKs connected (!), the system's behaviour is undefined. The first one the Mac detects is used; if you have both v1 and v2 devices connected, the v1 devices take precedence.

[V2 RadioShark, as a housewide AM receiver in the attic.]

Notes on the LEDs

One of the radioSHARK's most interesting features are its programmable LEDs. These were intended to show the state of the software recorder, but you can use radioSH to make them into a handy annunciator for any sort of purpose.

There are two LED banks in both v1 and v2 devices, a blue set (the one that appears when you first plug it in) and a red set. The blue set originally indicated the software was passively listening and the red set indicated that the software was recording audio. Both can be turned on at the same time to yield a third "magenta" colour.

The blue LED's brightness (-b) is adjustable between 0 and 127, with -b0 being off and -b127 being brightest. On v1 devices, you can also set an automatic pulse rate (-p) with 1 being the fastest, 127 being the slowest, and 0 disabling the LED blinking. However, the LED pulse feature doesn't appear to be supported on v2 devices and you will receive an error if you try.

The red LED accepts brightness options (-r) between 0 and 127, but only 0 and 127 are defined (0 off, 127 on). The v1 treats any non-zero value as on, but the v2 treats any non-127 value as off.

If both LEDs are on, the blue LED can be adjusted to yield any of 127 shades of magenta by changing its brightness.

To turn both LEDs off, pass -b0 -r0 (any blink will also stop).

Tuning the radio seems to turn the red LED off automatically.

Notes on Radio Reception and v1 and v2 Differences

The v1 and v2 devices have almost completely different internals despite exposing similar functionality. The biggest difference in the v2 is its substantially improved reception capability: the v1 radio receiver tends to pick up some carrier hum, which is much reduced in the v2, and the v2 does a better job with antennas (a whip antenna was included with the v2 package). On the other hand, the LEDs are weaker in the v2 and it apparently lacks the v1's LED pulse feature.

Both the v1 and v2 devices are rather worse at AM reception than FM reception, though the v1 is definitely inferior to the v2 particularly with distant stations. FM reception can be improved by lengthening and/or coiling the USB cable, and/or connecting headphones or a whip antenna with a 3.5mm plug, but AM reception can only be improved by repositioning or rotating the unit.

From a software perspective, the v2's different controller is immediately obvious. It takes HID commands of a different length and has different control opcodes. They can be distinguished programmatically by either looking at the version (0x0001 for v1, 0x0010 for v2), which is how radioSH determines the device in use, or the USB product string, which is RadioSHARK for the v1 and radioSHARK for the v2 (note the initial lowercase R).

Overall, the v2 is worth looking for if you care about audio quality; it is noticeably better-sounding than the v1, even with AM reception, which is neither device's strong suit. Unfortunately, very few v2s were made. Allegedly there are some white radioSHARKs that have the v2 receiver, but of the three white units I own, they're all the v1 chipset. My personal house broadcaster uses a v2 radioSHARK as a repeater source, pictured at left. It sits in the attic with a really long USB cable to get an AM station about 80 miles away.

On the other hand, if you just want to use it as an inexpensive LED annunciator device, the v1 is the device to grab because there's a lot more of them.

Download

Download the binary (8K). Decompress it and chmod +x to make it executable. The binary is unsigned.

Download the source code (includes binary, 26K). To build for OS X requires Xcode 2.5 and Tiger 10.4, which is the only tested configuration (though Xcode 3 with the 10.4 SDK should work). You may need to modify the Makefile for later versions of Xcode that cannot build the PowerPC version. To build, just type make. It is provided to you under a BSD license.

As a bonus, the source code archive includes the tools on which radioSH was based: rslight (Mac OS X), shark (Linux with libusb and libhid) and shark2 (ditto). These are merely included in the interest of preserving them for educational purposes. I don't support them and I don't even guarantee they work or will build on a current OS.


Cameron Kaiser