Patch Installer applet

Overview

This is a applet for Squeezebox Controller/Touch/Radio devices that make is possible to easily install third party patches of the firmware.

Installation

1. On the Squeezebox Touch, Radio or Controller goto Settings/Advanced/Applet Installer and select to install Patch Installer applet.

Providing patches

For users that likes to provide a patch this is done through <patch> element in a standard Squeezebox Server repository file.

There are two types of patches:

• A patch based on a standard diff patch file
• A patch based on a zip file which contains complete files that should be replaced

The two types can also be combined if using a zip based patch, the Patch Installer will also look for a .patch file with the same name as used in the repository xml file file in the root of the zip.

Here is a sample <patch> section for a diff patch file:

<patch name="dBVolume" target="fab4" version="1.0" minTarget="7.5" maxTarget="7.5">
    <title lang="EN">dB Volume</title>
    <desc lang="EN">Display volume as dB</desc>
    <creator>Erland Isaksson</creator>
    <url>http://erlandapplets.googlecode.com/svn/PatchInstaller/trunk/patches/dBVolume/dBVolume-1.0.patch</url>
    <sha>23f6e45bc3509ea88357c85dcddbdc3793cbfb49</sha>
</patch>

The elements used are:

• name attribute - Unique identity of the patch
• target attribute - Type of Squeezebox the patch works on, a list of the following values separated with a | character:
  • fab4 - Squeezebox Touch
  • baby - Squeezebox Radio
  • jive - Squeezebox Controller
  • squeezeplay - SqueezePlay (only Linux based SqueezePlay is supported)
• title - User friendly name that will be shown to the user
• desc - Description of the patch
• creator - Creator of the patch
• url - Web address to the patch file or zip file
• sha - Optional attribute that contains a sha checksum of the patch/zip file specified with the url element

The diff based patch file needs to contains diff paths relative to the /usr directory, this also means that anything under /usr can be patched.

A patch based on a zip file would look as follows:

<patch name="NoIR" target="baby|fab4" version="1.0" minTarget="7.5" maxTarget="7.5">
    <title lang="EN">Disable IR remote</title>
    <desc lang="EN">Disables all the standard Squeezebox IR codes</desc>
    <creator>Erland Isaksson</creator>
    <url>http://erlandapplets.googlecode.com/svn/PatchInstaller/trunk/patches/NoIR/NoIR-1.0.zip</url>
    <sha>1ae36f19aa839c6f5aa4a48cf8572255a019e099</sha>
</patch>

When installing this zip based patch, the Patch Installer applet will also look for a NoIR.patch file at the top of the zip and if it exists that diff based patch will also be installed.

Generally speaking you should choose patch types as follows:

• For patches that only changes source code or text files, the diff based patch is recommended
• For patches that only changes images or other binary files, the zip based patch is recommended
• For patches that needs to change both source code and binary files, it's recommended to use a zip based patch with a <name>.patch file in the root of the zip.

For patches that are based on a diff file, the recommendation is that you specify a maxVersion attribute equal to the latest major version of the firmware you know that the patch works with. This is just to avoid that a user installs a patch on a new major firmware version which the creator of the patch hasn't verified it on. Specifying maxVersion results in that the user will only see patches that have been tested on the firmware version he/she is using. The patches will be verified before they are installed, so it's not really needed for safety, the main reason is just to avoid confusing the user.

Usage

On the Squeezebox Touch, Radio or Controller goto Settings/Advanced/Patch Installer and select the patch you like to install.

Backup and uninstall of patches

When a patch is installed a backup is done as follows:

• For diff based patches, the actual .patch file are stored in the directory /usr/share/jive/applets/PatchInstaller.patches/
• For zip based patches, all replaced files are stored in a sub directory with the patch name under the main directory /usr/share/jive/applets/PatchInstaller.patches/

When selecting to uninstall a patch through the user interface, diff based patches will be reverted by running the .patch file backwards, zip based patches will be reverted by copying the replaced files from the backup directory under /usr/share/jive/applets/PatchInstaller.patches/. Please note that uninstalling patches can go wrong if several patches are uninstalled and affects the same files, in this case it's up to the user to uninstall them in the reverse order compared to the previous installation order.

Bugs and new features

The current list of known bugs and wishes for new features can be found here:

• http://code.google.com/p/erlandplugins/issues/list?q=label%3AApplet-PatchInstaller&can=2

If you want to encourage future development of this plugin you should also consider making a donation

• http://erland.isaksson.info/donate