Raspberry Pi Chameleon: overview and tutorial

[Last update: November 2013: v.0.32 has just been released.
This tutorial will be soon updated with all the new features. This tutorial is a work-in-progress and will be updated on a regular basis as long as Chameleon gets updated; current release is 0.32]

What is Chameleon?

Chameleon is a cool Raspbian remix compiled by Carles Oriol aimed at providing Raspberry Pi users a solid platform for emulators.
Chameleon lacks X-Windows or any other graphical environment but provides its own launcher/interface written in Python.
Several well-known emulators are provided with the standard release and more can be added easily.
Although it’s only release 0.2, Carles did an excellent job at making it so easily enjoyable.

raspberry chameleon tutorial

Included emulators (current list):

  • Sinclair ZX Spectrum (FUSE and Unreal Speccy)
  • Oric 1
  • Oric Atmos
  • Apple ][
  • Commodore 64
  • Vic 20
  • ScummVM
  • DOS/Win 3.x
  • Mame
  • Amstrad CPC 464
  • Sinclair ZX81
  • Gameboy
  • SNes
  • Atari ST
  • Commodore PET
  • Atari 800

Minimal requirements

  • Raspberry Pi (RPi): mine is Version B with 512 MB of RAM,
  • SD CARD, strongly recommended a fast one, at least 8 GBytes (current version 0.21 expands to some 4,6 Gbytes)
  • Chameleon itself, which is available by clicking here via bit-torrent (it’s about 730 MB bzipped)
  • USB Keyboard
  • HDMI cables or composite video+audio cables
  • Ethernet cable
  • a good power supply (that is > 1A)
raspberry chameleon tutorial raspberry chameleon tutorial raspberry chameleon tutorial

Optionals: (more about this later)

  • USB mouse
  • USB Wi-Fi adapter
  • USB Bluetooth dongle

How to install Chameleon on an SD card

First of all, unzip the downloaded image file then follow one of the dozen of instructions about writing Linux images for RPi available online.

In a nutshell, here’s what you need to know:

What to do after installation and first boot

Update: How to obtain RPi address?

Connecting it to a TV via HDMI or composite video, logging in (same username and password as above) and typing:

sudo /etc/rc.local

The result is your RPi IP address: take note of it!

(the RPi IP address should be very close to your own PC or Mac; e.g.: 192.168.1.X may be a common IP address pool for most routers, so look for the next IP after your PCs.)

[Note: some of the following actions are my own advice, and may help you better understand Chameleon; if you just want to play, go to section “How to put games into Chameleon”]

Set up your RPi, connect all cables, even Ethernet to your LAN, and TV and switch it on: you should see the same screen as in my Youtube video.
I strongly recommend you to update it and to get in control of your newborn Chameleon.
Keep in mind that Chameleon has two built-in users:
root, with password raspberry, as usual
zx, with password spectrum (Carles really rules!!!).

This is easily done by using SSH so fire a terminal windows (Mac & Linux) or PuTTY (Windows) and do something like this:

ssh -l zx [raspberrypi-IP-address-here]

As above, pre-defined password for user zx is spectrum.

Now you can update Raspbian with these commands:

sudo apt-get update

followed by:

sudo apt-get upgrade

My advice is to do even this:

sudo apt-get autoclean

which cleans all unused files.

raspberry chameleon tutorial 4The last thing is to expand root partition to fit all SD card: it’easily done by launching raspi-config:


and select expand_rootfs.

Now you can check your SD card usage with the command:


and see that it fits completely all the SD card capacity.

How to put games into Chameleon

Chameleon comes with no ROMs or games at all, so you’ll have to provide them (or program them!); on the other hand, computer emulators are fully working.
You can access Chameleon in two ways:

  • by accessing the SMB share via LAN
  • via SSH to the RPI and then wget-ting files from Internet

SMB Share (AKA Windows Share) may become available immediately if the RPI is connected to your LAN: its network name is “rpichameleon” and you can put all games/roms/files by entering the share ROMS.
Again the username/password couple to access this is zx and spectrum respectively.
Each emulator has its own directory so you can’t go wrong.

If you’re using a Mac, you will see that the RPi shows up in the shared objects list as rpichameleon, something as in the picture below.

raspberry chameleon tutorial share network

In this directory you can find the README.txt file made by Carles himself.

Using Chameleon

raspberry chameleon tutorialQuite simple: when Chameleon gets started, what you get is a horizonally-scrolling launcher with great graphics depicting consoles and old computers.
You just move from one to another by pressing left and right cursor keys and then ENTER to run the selected emulator.
As with the ZX Spectrum, you may have two choices (in this case: Fuse or Unreal Speccy): you just press 1 or 2, as stated on screen, to launch one of the emulators.

So, this is the keymap you’ll need:

  • left and right: choose emulator
  • ENTER: run emulator
  • E: will simulate a really funny screensaver (check some very well-known screenshots!)
  • Q: quit Chameleon (that is: do a plain shutdown!)
  • T: enter terminal command-line mode (you can return to the launcher interface by typing exit)
  • ESC: will get you back to the launcher most of the time
  • F10 or F1: most emulators will use these two keys to access emulator-specific menus

Some tricks and upgrades

Adding Commodore PET

Commodore PET CBM 8032I love my own Commodore PET 8032, a real one and still working back from 1979!

Having the full VICE Commdore Emulator on Chameleon, I attempted to add this emulator to the launcher, as well as a proper image.

This is how you can add new emulators; in this case we’re going to add xPet, which is already included in the Chameleon image.

raspberry chameleon tutorial pet cbm 8032Provided the emulator is already installed, first of all get or assemble a PNG image, 600px wide, with transparent background (AKA alpha) and put it into the ROMS root directory.
Then SSH into Chameleon and move the image file with this command:

mv /home/zx/image-file.png /opt/selector/imatges/

All the relevant stuff is inside /opt/ , there you will find emulators binaries and sources and the /opt/selector/ directory where Carles put the python emlaunch.py, the shell script select.sh and machines.conf; we’ll need to edit the last two files like this:

sudo nano select.sh will get the Nano editor where you can find the CASE structure: check for the latest item, in this case it’s 15:

12) cd /opt/Oricutron_src_v09
oricutron -m atmos --fullscreen
_main ;;
13) cd /opt/sz81-2.1.7
_main ;;
_main ;;
cd /opt/caprice32-4.2.0-src/464
_main ;;

Now insert this code snippet:

16) cd ~/c64
_main ;;

Save and exit this file with CTRL-X.
Now it’s time for sudo nano machines.conf which is a simple pipe-separated list with each line representing an emulator along with some additional info (its web site, the image file).

This is the line you should append to the file:

Commodore PET|pet.png|1- PET|http://viceteam.org/|http://chameleon.enging.com/?q=commodore64|http://chameleon.enging.com/?q=vice

Again CTRL-X save & exit and, now, you’ll have a new entry in the launcher list!

Update: No longer without PET CBM games!
I found this page about Telengard on Archeogaming Blog, a really ancient PET CBM videogame, no graphics just ASCII-characters.
The author is kind enough to share the .TAP file of the game!
It’s fully working and shows what 8-bit gaming it’s really about!

Adding Atari 800

atari 800 chameleon

There’s still a huge fanbase out there looking for Atari 8-bit emulators, so next move is to include Atari 800.
Actually, the Atari800 project supports a lot more: 400, 800, 800XL, 130XE…

What’s needed:

  • usual 600-pixel-wide PNG image with alpha channel of an Atari 800 (or whatever)
  • ROM files you can find here
  • this tutorial (see above!)

atari 800 emulatorYou can do everything from Terminal so you can do it from the Raspberry Pi or from SSH, just login as zx as before.

Let’s create some space for this:
mkdir /opt/atari800
cd /opt/atari800

Now, we can download the emulator straight from Sourceforge:

wget http://sourceforge.net/projects/atari800/files/atari800/2.2.1/atari800-2.2.1.tar.gz/download

Rename the file accordingly:

cp download atari800.tgz

And prepare to compile:

tar -xvf atari800.tgz
cd src
./configure --target=sdl
make install

That’s it: you can now run atari800 and see a genuine Atari 8-bit emulator in all its glory!

Now, copy your Atari image to imatges directory and, as above, open the select.sh file and insert these lines:

_main ;;

Then append a line to machines.conf just like this:

Atari 800|atari800.png|1- Atari800|http://sourceforge.net/projects/atari800/|http://chameleon.enging.com/?q=atari800|http://chameleon.enging.com/?q=atari800

Go Atari!

There’s more work in progress about upgrading.


Have fun: there’s no other old-computers, retrocomputing, old-console platform as a Raspberry Pi plus Chameleon!


The main credit goes to Carles Oriol, for providing Chameleon: here’s the main web site.
More info about VICE Commodore Emulator, FUSE Spectrum Emulator, Stella Atari VCS Emulator to name but a few.
Last but not least, of course, Raspberry Pi Foundation!

Book advice

There are a few books worth reading I’d like to suggest:

Legal stuff

Legal stuff as usual: all products names, images and icons are trademarks of their respective holders.
Check for your local country laws about ROMs owning, downloading and playing.