Software > Mac OS X Packages > LogitechLCDTool

LogitechLCDTool

• Introduction
• Download
• Quick Start
• FAQ / Troubleshooting / Support
• Extending It
• License / Source Code
• Acknowledgements

Introduction

Logitech sells a very nice stereo USB speaker system called Z-10. It sounds great and looks very stylish. One of the speakers has a panel with some buttons and an LCD display.

This is where LogitechLCDTool comes in. It provides the missing Mac support for this panel. Logitech does not provide Mac software to enable the display or about half of the buttons. Some buttons do work out of the box because Mac OS X understands their purpose, for example mute and volume up/down are mostly OK.

Without supporting software, the remaining buttons are dead and the display shows “Z-10” permanently, which gets old pretty quickly.

Logitech’s Windows software for the Z-10 supports interactive mini-applications which display more or less useful things like iTunes track information, computer system load or the number of new email messages. The software also makes the previous/next/play/pause buttons work with your media player of choice. There is a software development kit to write such mini applications.

After I bought the speakers, I spent some time reverse-engineering the USB communications between the Windows software and the speakers and reading open source code for a similar Logitech product, the G-15 gaming keyboard.

The result of this work is LogitechLCDTool. It enables the missing features on Mac OS X computers, for example iTunes status display and iTunes track control using the buttons:

Note that LogitechLCDTool could potentially also work for a G-15 keyboard attached to the Mac. I’ll try this if I get access to such a keyboard, so if this is important for you, send me one :-)

The program actually does much more than simply mediating between iTunes and the speakers. It certainly does that well and if that’s all you need, it only takes one click to get started.

However, under the hood LogitechLCDTool provides a fully user-programmable platform based on HTML, CSS, JavaScript and AppleScript. Basically the LCD screen is a tiny web page and the buttons can execute JavaScript and AppleScript code. The default iTunes support is just an example application built upon this platform. If you’re interested to write your own scripts, see the section “Extending It” below. It’s easy and definitely a lot of (nerd) fun...

Download

LogitechLCDTool Disk Image

I recommend to enable the automatic update check, then you’ll always be up to date. I expect to release quite a few bug fix releases in the first few weeks when people start using it.

Quick Start

The software consists of one self-contained application which you can put wherever you like, the /Applications folder is probably a good idea.

After you launch it for the very first time and answer the auto-update dialog, you will see a window like this:

All you have to do is press the “Display” button. The little display preview and your Z-10 speakers should both show the iTunes status and the previous/next and Play/Pause buttons should control iTunes.

The program continuously updates the speaker display and listens for button activity so it needs to stay open, probably hidden in the background.

That’s all there is to it. If you want, you can play around with the HTML code or use the Image URL pane to send images from the web or from your local harddisk to the speaker display.

FAQ / Troubleshooting / Support

I created a user forum for LogitechLCDTool. You are encouraged to ask or answer questions or look for or share your custom scripts there. I hope that lots of useful scripts will be written and published by you :-)

Here are answers to some frequently asked questions:

Extending It

As you can see when you start the program for the first time, the display image is created using regular HTML/CSS. The display is basically a black-and-white web page with 160x43 pixels.

This means that whatever you can do in a web page, you can do on the display. The hardest part is making it look good with just 1 color and very limited space.

Predefined JavaScript Methods you can Call

You can also run JavaScript code, and this is where it gets interesting. The JavaScript environment has the special window.application object which provides some methods to get out of the web view sandbox and call back into the host application to request services and trigger interesting things.

These methods are currently:

window.application.updateDisplay()

Captures the current image of the web view and sends it to the LCD display. You would use this after dynamically updating the HTML in the web view, possibly periodically from a setInterval() timer. This method takes no arguments and returns a true/false value indicating if the display was updated successfully. Failure to update probably means that no display is available and any setInterval() timers should be cleared to prevent wasting CPU cycles. The default iTunes HTML example illustrates this.

window.application.runSystemScript(key)

Runs one of the predefined AppleScripts identified by the string key and returns the script’s result as a string. See below for a list of predefined AppleScripts.

window.application.registerUserScript(key, code)

Compiles the AppleScript code passed in the code parameter and stores it for later invocation under the given key.

window.application.runUserScript(key)

Runs the AppleScripts identified by the string key, which must have been registered previously, and returns the script’s result as a string.

window.application.getVersion()

Returns the version of the host application so your script can refuse to run if the version is too old. This is useful if you use library resources (see below). You’ll be able to enforce the first application version that shipped with the resources you use.

Predefined System AppleScripts

These are the predefined system AppleScripts keys:

iTunesCurrentTrackFullStatus

Returns an almost-JSON string with the current iTunes status. JSON means that using eval(), you can convert this returned string to a JavaScript associative array data structure which is very convenient to use. It is almost JSON because you need to fix escaped single quotes with a regex before passing the string to eval():
var itunes = eval(fullstatus.replace(/'\\''/g, "\\'"));

iTunesCurrentTrackTitle

Returns the title of the current track playing in iTunes.

iTunesCurrentTrackArtist

Returns the artist of the current track playing in iTunes.

iTunesCurrentTrackDuration

Returns the duration of the current track playing in iTunes in seconds.

iTunesPlayerPosition

Returns player position in the current track playing in iTunes, in seconds.

iTunesPreviousTrack

Skips to the previous track in iTunes. This is also hardwired to the “Previous” button on the panel.

iTunesNextTrack

Skips to the next track in iTunes. This is also hardwired to the “Next” button on the panel.

iTunesPlayPause

Toggles Play/Pause in iTunes. This is also hardwired to the “Play/Pause” button on the panel.

visitEntropyWebsite

Sends Safari to this wonderful website :-)

Predefined JavaScript Methods Called by the System

The methods listed in the previous section allow your JavaScript code to call the host application. There are also calls in the other direction, where the host application calls functions in the web view which you provide. These calls allow you to respond to external events.

Currently there is only one such function called handleButton(button, upDown). This event-handling function is called whenever the user presses one of the five application-specific touch buttons on the speaker’s panel. The application-specific buttons are “1” to “4” and “display”. The function is called with two arguments, the first one contains one of the strings “Softkey1” to “Softkey4” or “Display” to indicate which button is affected. The second argument contains the string “up” or “down” depending on whether the button was pressed or released. You are generally only interested in the “up” events.

Web Resource Library

The application ships with an embedded web resource library containing useful stuff like a default CSS file or popular JavaScript libraries such as prototype.js. You can load these resources with relative paths: <script type="text/javascript" src="js/prototype.js"></script>. The Help menu contains a new command to open the library folder so you can see which goodies are included.

Currently there are a few JavaScript libraries: prototype.js, dojo and MochiKit. A lot of the functionality won’t be applicable in a non-browser, non-interactive environment like LogitechLCDTool, but some modules like DOM manipulation will certainly help.

There is also a default CSS file (css/default.css) which you can load to set up some useful defaults for the BODY element (check out the .border class).

If there’s something you’d like to see included, send me an email and I’ll check it out and decide if it’s of general interest.

Performance Considerations

The code quality of your script has a direct impact on the system CPU load, especially if you write a script which updates continuously. It is easy to write inefficient scripts with JavaScript and AppleScript and since LogitechLCDTool tends to be used for long periods of time in the background, it is important that you check the CPU load and fix the script if it consumes too many resources. You should strive to stay under 1% CPU load as reported by the Activity Monitor utility.

If you run a timer, you shouldn't update more than once per second, i.e. the second parameter to the JavaScript setInterval() function should be at least 1000.

Possibilities

It might not be immediately obvious so it’s worth noting that with the combination of the registerUserScript() function, the AppleScript do shell script command and the JavaScript XMLHttpRequest() object, you can basically do anything, which is why this is really a platform for all kinds of mini-applications. Examples that come to mind are stock tickers, system load monitors, clocks, little games etc.

License / Source Code

The program is currently free but if I put a lot of work into it I might publish future versions as shareware. If you really like it the way it is now, you can make a donation or send me something from my wish list :-).

The Objective-C source code is available here. Once I get my repository viewer back online, you’ll be able to browse the source code online. The code combines many OS X technologies such as WebKit, JavaScript, AppleScript, USB etc. Check out my blog entry about things I found interesting or issues I encountered during development.

Acknowledgements

Thanks to...

• Andy Matuschak for his Sparkle framework for automatic updates. If you publish Cocoa Software, you need to look at this.
• The g15tools project which helped me understand the raw display bitmap format, especially to Anthony J. Mirabella and Philip Lawatsch for letting me use some conversion code.
• Quentin D. Carnicelli from rogue amoeba for some example code which helped me understand USB HID data output.

Logitech did not provide any help in the form of developer documentation upon request. Thanks for nothing, Logitech...