Individual Computers Turbo Chameleon 64 User manual

Turbo Chameleon 64
User Manual
Draft Version (Beta 9i)
19/04/19

Contents
1. Contents
1. Contents..........................................................................................................................................2
2. Getting started...............................................................................................................................4
2 1 What's in the Box? 5
2 1 1 Chameleon v1 5
2 1 2 Chameleon v2 6
2 2 Operation in standalone mode 7
2 2 1 Using the docking station 9
2 3 Operation in cartridge mode 11
2 3 1 Operation on a C64 11
2 4 Sound output 12
3. Updating the Chameleon............................................................................................................13
3 1 Updating using update prg 13
3 2 Updating via USB 14
3 2 1 Preparations 14
3 2 2 Using the flasher program 14
3 2 3 Using ChaCo 14
4. First Aid - If something goes wrong...........................................................................................15
5. O er iew.......................................................................................................................................16
5 1 Flash memory organization 16
5 2 Using disk images 17
5 2 1 Disk slot organization 17
5 2 2 Mounting images 17
5 2 3 Unmounting images 17
5 3 Using cartridges 18
5 3 1 Cartridge slot organization 18
5 3 2 Mounting cartridge images 19
5 3 3 some notes on specific cartridges 20
5 4 using custom ROM images 21
6. Chameleon Menu System............................................................................................................22
6 1 Boot Loader 22
6 1 1 Hotkeys during boot process 23
6 1 2 Limitations of the boot-loader 23
6 2 Keys 24
6 3 Main Menu 25
6 4 Options 26
6 4 1 CPU Turbo 26
6 4 2 Emulated drives 27
6 4 3 Cartridges and Memory Expansions 28
6 4 4 Input devices 28
6 4 5 VGA output 29
6 4 6 Emulation settings 29
6 4 7 RTC 30
6 4 8 Boot-loader settings 30
6 4 9 Button settings 30
6 4 10 File Browser and Menu settings 30
6 4 11 Load and Save the settings 31
6 4 12 Buttons 32
6 5 File Browser 34
6 5 1 Keys 34
6 5 2 User / File menu 36
6 5 3 File-Action menu 37
6 5 4 Supported File types 38
6 5 5 Plugins 39
2

Contents
6 5 6 Limitations of the file-browser 41
6 6 ML Monitor 42
6 6 1 Features 42
6 6 2 Number formats 42
6 6 3 Converting values 43
6 6 4 Commands 43
6 7 Online Help 45
6 7 1 Keys 45
6 8 System Info 46
7. ChaCo, the Chameleon Control Software.................................................................................47
7 1 Preparations 47
7 1 1 Linux / macOS 47
7 2 Linux notes 47
7 3 macOS notes 47
7 4 Overview 48
7 4 1 Slot Management 49
7 4 2 Memory Access 49
7 4 3 Debugging 49
7 4 4 Status display 49
7 5 Examples 50
7 5 1 Starting a core 50
7 5 2 Flashing a Core 51
7 5 3 Accessing memory 52
7 6 Command-line options 55
7 7 chacocmd 56
7 7 1 examples 56
8. Frequently asked questions.........................................................................................................57
9. known Bugs and Limitations......................................................................................................57
10. Reporting Bugs..........................................................................................................................57
11. De eloper information...............................................................................................................58
12. Related projects.........................................................................................................................59
13. Appendix.....................................................................................................................................60
13 1 PS/2 Keyboard Key Assignment 60
13 2 PS/2 Keyboard Joystick Assignment 61
13 3 CDTV Remote Control Key Assignment 62
13 4 supported Cartridge types 63
13 5 Opening the Cartridge 64
13 5 1 Chameleon v1 64
13 5 2 Chameleon v2 65
13 6 Re-programming the USB micro-controller 66
13 6 1 Chameleon v1 66
13 6 2 Chameleon v2 68
13 6 3 Linux 71
13 7 configuring Quartus for JTAG 72
13 8 Chameleon breakout-cable pinout (Chameleon v1) 79
13 9 mini IEC cable pinout (Chameleon v2) 81
13 10 Technical Data 82
13 10 1 Turbo Chameleon FPGA Core 82
14. Credits.........................................................................................................................................83
15. Fine print....................................................................................................................................84
3

Getting started
2. Getting started
Thank you for purchasing an Individual Computers product The Chameleon is one of the most
complex projects that we've ever made for any computer, and it will take much more than this user
manual to explain all the features and possibilities of this cartridge Take your time to read all of this
document
You've been made aware a number of times that the current state of the firmware is beta, and we
appreciate that you've bought the unit anyway If you find any bugs, please report them in our
forum:
http://forum.icomp.de
This is where the developers meet, and where your questions will be answered by the people who
made the cartridge We will also make important announcements on that list, so even if you don't
have anything to report, please subscribe to that list
Please download the latest version of the FPGA Core and ChaCo, the Chameleon Control software,
from:
http://wiki.icomp.de/wiki/Chameleon
4

Getting started
2.1. What's in the Box?
2.1.1. Chameleon v1
•upper left corner: mini USB cable (for data transfers, 180cm)
•middle bottom: Turbo Chameleon 64 :-)
•upper right corner: breakout cable with connectors for USB (power supply, 80cm), keyboard
and mouse (both PS/2, 20cm), IEC (DIN, 20cm)
•a short user manual (which you do not need any more now that you have found this one)
A battery (CR-1220) required to make use of the RTC feature is not included and must be supplied
by the user See page 63, 13 5 Opening the Cartridge
5

Getting started
2.1.2. Chameleon v2
•Turbo Chameleon 64 :-)
•a short user manual (which you do not need any more now that you have found this one)
A battery (CR-1220) required to make use of the RTC feature is not included and must be supplied
by the user See page 63, 13 5 Opening the Cartridge
Also not included is a mini USB cable, since most customers already own more of them than they
need Should this not be the case just buy one at your local consumer electronics store
6

Getting started
2.2. Operation in standalone mode
In stand-alone mode, you will need at least the breakout cable to connect to Chameleon, because it
will provide power to the cartridge With the second version of the Chameleon, please use the mini
USB connector at the bottom/left for power:
Make sure that the power supply can deliver at least the 2 5W (5V and 500mA) that's specified for a
USB connection The Chameleon hardware will take about 2 Watts of power, so make sure that
your keyboard and mouse don't overload the power supply! Most PCs don't have any trouble
supplying Chameleon with power Note that some PCs don't provide power without a data
connection on a USB port In that case, please use a separate power supply
Connect your monitor to the VGA output By default the Turbo Chameleon 64 FPGA core uses a
standard 800x600 mode with a refresh rate of 72Hz Some monitors don't support this high
frequency Please consult your monitor's manual if you have any trouble with Chameleon's VGA
output
7

Getting started
Connect your keyboard to the purple PS/2 connector, and your mouse to the green PS/2 connector
The IEC connector can be left open If you want to use ChaCo with the cartridge, you also need to
connect the mini-USB cable to that PC (see chapter 7 ChaCo, the Chameleon Control Software)
For the second version of the chameleon you need a mini IEC cable, which is available separately,
to connect IEC-bus devices It is not required if you only use the floppy drive emulation
8

Getting started
2.2.1. Using the docking station
The Chameleon docking station extends the available ports of your Chameleon by the following:
–four joystick ports
–one C64 keyboard connector
–one Amiga 500 keyboard connector
Both keyboard connectors are keyed, which means that they have a missing pin in order to help you
finding the correct orientation of the connector However, the A500 keyboard connector is not
always keyed, so you have to take a close look at the colours The black wire of the A500 keyboard
is marked next to the connector Wrong connection may destroy both, the docking station and the
keyboard! Better double-check before you apply power to the unit
All C64 keyboards that we have encountered have been keyed There is no danger when plugging in
the keyboard the wrong way round – you will just observe funny behaviour Caution: This only
applies to the Chameleon docking station! You may actually destroy a C64 if you connect the
keyboard the wrong way round!
Please download and install Chameleon core Beta-7 or higher before you use the docking station
It's available from http://wiki.icomp.de/wiki/Chameleon Older cores will not support
the docking station, and the ports won't be of any use to you For flashing, please disconnect all
external hardware: Remove the mouse, remove the PS/2 keyboard and remove the SD card from the
slot Do not connect the docking station to Chameleon when you're updating the flash!
9

Getting started
There is only one way that Chameleon fits the docking station: It's with the button side up Slide the
cartridge all the way in until the black connector is at least covered half by the Chameleon Make
sure that there's proper contact between the docking station and the Chameleon – the cartridge may
not be tilted at all
Connect the breakout cable and supply power to the whole setup through the USB connector of the
breakout cable (first version of the chameleon) or the mini USB connector at the bottom/left
(second version of the chameleon) Make sure that your power supply is strong enough! With the
docking station, we recommend to use a 5V/1000mA power supply If available, use a
5 2V/1000mA power supply, but ne er use any higher voltage than 5 2V Only use regulated power
supplies
The pinout of the joystick ports follow the common “Atari standard”:
Pin Function
1 /Up
2 /Down
3 /Left
4 /Right
5 /Button 3 (POTY on C-64 and Amiga)
6 /Button 1
7 VCC (+5V)
8 GND
9 /Button 2 (POTX on C-64 and Amiga)
Note: Unlike the POT lines of a real C-64, Pin 5 and 9 must be pulled to GND instead of VCC
For details see http://wiki.icomp.de/wiki/DB9-Joystick
10

Getting started
2.3. Operation in cartridge mode
WARNING: Chameleon is a C64 cartridge It does not work in the C128. Don't even try, as this
might cause damage to the computer, the cartridge or both. Don't experiment, it can not work
and you risk damage to valuable equipment that's not covered by warranty
WARNING: Also, Chameleon does not work in cartridge port expanders – neither as the only
cartridge, nor together with other cartridges It will only work if it's plugged directly to the C64
Don't experiment with combinations of cartridges! It cannot work, and you risk damage to
valuable equipment that's not covered by warranty
2.3.1. Operation on a C64
Remove the protective plastic from the Chameleon expansion connector Just push it in and rotate it
until it comes out – be gentle, there's no force required! The brown rubber is glued in place Don't
try to peel it out, it is required if you want to put the protection back in The rubber will not conflict
with the C64's expansion port
11

Getting started
Now insert the cartridge into the C64 expansion port with the buttons facing up Connect your VGA
monitor to the VGA output of Chameleon At this point, we recommend to also connect your old
15kHz screen, so you can compare the output of Chameleon against the output of the original VIC
chip
Use of the breakout cable is optional on the C64 If you want to use a PS/2 keyboard or mouse,
you'll need it (first version of the chameleon only)
If you want to use the ChaCo software with this setup, you also need to connect a mini-USB cable
to your PC (see chapter 7 ChaCo, the Chameleon Control Software)
Note for SX- 4 users
•If for some reason the Chameleon fails to start the menu system, power-cycle the computer
and hold "2" during power-on This will make the menu use a fail safe configuration (skips
booting from SD card and copying ROMs from C64)
•There seems to be a timing problem that makes copying ROMs from the C64 fail on some
SX-64s, this will result in a crash when exiting the menu system If this is the case, disable
the "copy ROMs from C64" option (see chapter 6 4 Options), write options and power-cycle
the computer Optionally you can enable "boot from SD card" and put a SX-64 kernal (or
whatever else you want to use) ROM image on it (see chapter 6 1 Boot Loader)
2.4. Sound output
Chameleon and C64 each have their own audio outputs, the Chameleon doesn't get the audio from
the C64 and the C64 doesn't get the audio from the Chameleon so each must be connected
seperately
The Chameleon has a stereo output (it can emulate 2 SIDs) You connect it to your speakers with an
3 5 mm stereo-audio plug similar what portable players and many laptops have You need speakers
with build-in amplifier (or separate amplifier as Chameleon doesn't have one)
12

Updating the Chameleon
3. Updating the Chameleon
Each release archive contains a combined ChaCo, core and software update The two files needed
to update manually (* rbf for the core and * bin for the menu and ROMs) can be found in the
UPDATE directory The CHAM64 directory contains files used by the menu system, such as the
online help Just copy the entire directory to the root of your SD card
Updates are made available at http://wiki.icomp.de/wiki/Chameleon on a regular basis
Please make sure that you are running the latest firmware and are using the latest version of ChaCo
before reporting problems
3.1. Updating using update.prg
Copy the UPD TE directory and UPD TE.PRG to the root of your SD card (or simply unpack the
entire release archive to it), insert the SD card and power-cycle the Chameleon (If you are updating
from beta-7a or earlier, run UPD TE.PRG from the file-browser ) You can do this either in
standalone mode or leave the Chameleon connected to your C-64
In addition to the files contained in the release archive, the UPD TE directory may contain the
following custom ROM files:
•“B SIC.ROM" - C64 basic ROM
•"KERN L.ROM" - C64 kernal ROM
•"CH RGEN.ROM" - C64 character ROM
•"MMC64.ROM" - MMC64 BIOS ROM
•"SLOT1.ROM" - Cartridge slot 1 ROM (*1)
•"SLOT2.ROM" - Cartridge slot 2 ROM (*1)
•"DRIVE.ROM" - 1541 drive ROM
*1) Cartridge ROMs must be plain binaries (without load address), NOT crt files Files in proper
format can be created by the ROM saver (see chapter 6 5 2 User / File menu ) Cartridges which are
bigger than 64k can not be used in slot 1 and 2, see chapter 13 4 supported Cartridge types for
details To make cartridges readily available for use, the respective cartridge type must be
configured in the settings first (see chapter 6 4 Options)
It is highly recommended to first test custom ROM files by loading them from SD card (see 6 1
Boot Loader) before flashing them permanently Flashing broken ROM files may render the C64
unusable (you will have to fix it by updating the chameleon via USB in that case)
13

Updating the Chameleon
3.2. Updating via USB
3.2.1. Preparations
Before updating your Chameleon, please make sure that it has sufficient power Any and all trouble
that has been reported so far was related to power problems that were caused by external power
draining To be safe, please:
•disconnect the Chameleon docking station
•disconnect the PS2 keyboard
•disconnect the PS2 mouse
•you MUST remove the SD/MMC card from the card slot (else you will get an error message
and can not update)
You may provide power via the USB breakout cable (first version of the Chameleon) or the mini
USB connector at the bottom/left (second version of the Chameleon), or leave the Chameleon
plugged into your C-64
If you are using a USB charger as your power supply, please make sure it's a 1000mA type
Although Chameleon takes just over 400mA of power, many 500mA types are already at their limit
with a Chameleon If possible, use a 5 2V/1000mA type instead of 5V/1000mA However, do not
go over 5 2V for supply voltage!
3.2.2. Using the flasher program
Windows users just double-click the asher.exe file in Windows explorer and follow the
instructions on screen In Windows 8 and above use right mouse click and choose "Run as
Administrator" (on asher.exe)
Linux users may run the respective flasher program from a terminal Since the executable bit of the
binary is not preserved in the archive, you will have to set it manually first like this:
$ sudo chmod +x ./asher-linux64
After that run the flasher as root:
$ sudo ./asher-linux64
In addition to the files contained in the release archive, the UPD TE directory may contain custom
ROM files as described in Updating using update prg above
3.2.3. Using ChaCo
You may also update the Chameleon manually using ChaCo or chacocmd, you can find the required
files in the UPDATE directory (See chapter 7 5 2 Flashing a Core)
14

First Aid - If something goes wrong
4. First id - If something goes wrong
First, don't panic :)
There is no way to “brick” the Chameleon by updating, installing an additional core, or wrong
programming The Chameleon might not start, but it can always be fixed by updating with a valid
FPGA core image In case updating using UPDATE PRG failed (please report this), re-try updating
via USB (see 3 2 Updating via USB above)
If you have trouble flashing, try again Before a re-try:
•Double check that you have sufficient power Maybe try another USB port
•If the USB connection seems unstable and stops working randomly make sure to power the
Chameleon from the same PC/Hub the USB data cable is connected to
•Make sure to select the correct files (when updating manually) Note that the first hardware
version (with breakout cable) requires a different core file than the second hardware version
(without breakout cable)
•PLEASE POWER-CYCLE YOUR CHAMELEON It may then give an error-blink on the
red LED, but there's nothing to worry about Updating will fix it
If the Chameleon does not start correctly, please try the following:
•Disconnect all peripherials except the monitor from the Chameleon In many cases it will
now start properly again To narrow down the problem, proceed as follows:
•Make sure that “shift lock” is not active If that is the case, the bootloader will indicate it by
showing “waiting for keys released” If you are using a PS/2 keyboard and the problem
persists, the keyboard might be defective
•Check that at a connected joystick “auto fire” is disabled – a typical symptom for that is
when the chameleon will leave the menu immediately and starts BASIC
If C-64 programs do not work as expected anymore:
•Reset the configuration to its default values (“restore defaults” in the options menu) Many
programs are incompatible with one or more expansions emulated by the Chameleon
•Connect only one floppy drive to the system, including emulated and real drives Many
programs do not work when more than one drive is connected to the IEC bus
15

Overview
5. Overview
Upon power-up, Chameleon will load the OS from its on board flash It will then start the menu
system which lets you perform various actions (see chapter 6 Chameleon Menu System)
The outermost button (right button) is your reset button The middle button is the freeze and menu
button The left button can be used to perform various actions such as change disks in the emulated
floppy
Press and hold the reset button for more than 0 7 seconds to re-launch the Chameleon core This is
(almost) equivalent to a fresh power-up Press and hold the Freeze button for more than 0 7 seconds
to enter the menu system
Button PS/2 Key remote Function
Left button F11 GENLOCK Multi purpose, see chapter 6 4 Options
Middle button F12 CD/TV Freeze, hold longer than 0 7s to enter menu
Right button PrntScrn POWER Reset, enter menu if "reset to menu" option is enabled
5.1. Flash memory organization
There is a flash chip built into Chameleon that's purely for system purposes and hence can't be
utilized by the user The flash carries FPGA cores and their respective ROM files The FPGA core is
the true core of Chameleon's operations – it defines the hardware behaviour If we fix a bug in the
hardware (such as a VIC effect emulation or register functions of a freezer), we will provide the fix
in the form of an FPGA core file
The size of the on-board flash is 16 MByte, organized in 16 slots of 1 MByte each Every slot can
carry one FPGA core and the corresponding ROM file If Chameleon is powered up, the FPGA is
started from slot number 0
If starting the FPGA was not successful, then the micro-controller will tell you so by sending out a
blink code on the red LED of Chameleon The blink code will tell you which slot was attempted to
be used Just count the number of blinks, subtract one and you'll know which slot of the flash chip is
corrupted If for example slot 0 is corrupted, then the LED will flash once, then pause for a second
and start over If the LED blinks four times, then slot number three is the one you should take a
closer look at
16

Overview
5.2. Using disk images
5.2.1. Disk slot organization
There are two emulated 1541 floppy drives of which each handles up to 4 different disk images
which can be mounted via the file browser and then changed by pressing the left button (see chapter
6 4 Options)
5.2.2. Mounting images
Before you can mount a disk image, one of the emulated drives must be enabled, and to use more
than one disk slot per drive, the left button must be configured accordingly (see chapter 6 4
Options)
To mount a D64 or G64 image press CBM+M on the selected image or RETURN on a PRG file
inside an image (see chapter 6 5 1 Keys) You will then be prompted to select a drive and whether to
start a new list (“first disk”) or to add the image to the existing list (“next disk”) for this drive
Starting a new list means that all mounted images for this drive will get unmounted and the selected
image will become the first image in the list for the selected drive
5.2.3. Unmounting images
To write changes made to a mounted image back to the D64 file on SD card you will either have to
make a copy manually (see chapter 6 5 2 User / File menu ) or unmount it by pressing CBM+U (see
chapter 6 5 1 Keys) Also the menu will check if changes to an image have been made when
entering the menu system and when mounting images, and ask whether the image on SD card
should get updated or not
WARNING: If you choose to ignore this the menu system will “forget” about the respecti e
image being changed and not ask again. You will ha e to make sure to sa e the image
manually if you want to keep these changes.
Note: due to the current limits of the drive emulation, G64 images will not get written back
automatically (as the disk layout is not exactly preserved, which would most likely result in a
corrupted G64)
17

Overview
5.3. Using cartridges
Please note that a real-world cartridge consists of two major building blocks: The hardware, and the
software By switching a slot to a specific cartridge type, you merely select the hardware, but you
don't have the contained software yet Real C64 cartridges bring their software typically on
EPROMs, which are emulated in the RAM space of Chameleon Just choosing a cartridge type for a
slot therefore does not mean that you actually can already use the cartridge, because it would appear
like an empty shell to the computer Compared to a real-world cartridge, it can be compared to
removing the EPROM chips from the cartridge and then plugging it into the computer, which will
not work
Note that the EPROM contents of the Retro Replay freezer and the MMC64 come with every menu
system, which is why you can use these cartridges after power-up and without an SD-card
However, it would be a waste of memory space to keep all the EPROM contents of all supported
cartridges in the menu system: They would not even fit in Chameleon's memory! This is why all
other cartridges require the use of a crt or rom file containing a binary image of the cartridge
EPROM Please see chapter 5 3 2 Mounting cartridge images below for a detailed description of
how to use cartridge image files
5.3.1. Cartridge slot organization
There are 4 cartridge slots Slot 1 and 2 can hold cartridges of max 64k, slot 3 and 4 can hold max
1Mb Slot 1 and 2 will get loaded from flash when the Chameleon boots, by default there is a PAL
Retro Replay ROM in slot 1 and an NTSC Retro Replay ROM in slot 2 Additional/other cartridge
ROMs can be loaded by the boot-loader (see chapter 6 1 Boot Loader) or by the CRT loader in the
file-browser (see chapter 6 5 File Browser) Slot 3 is configured as expert cartridge by default, and
slot 4 remains empty
18

Overview
5.3.2. Mounting cartridge images
Cartridge images can be mounted by the boot loader (see chapter 6 1 Boot Loader) or the file
browser In the file browser simply press return on a ROM or CRT file Unless configured to always
use slot 4, you will be asked which cartridge slot to use and the cartridge will be started
Note that ROM files must be in a Chameleon specific layout (which may be different from what
you get from converting a CRT file to a flat binary using common tools such as cartconv), you can
create such files using the ROM saver in the file browser (see chapter 6 5 2 User / File menu ) Also
when using ROM files, you will have to set up the correct cartridge type manually (see chapter 6 4
Options)
19

Overview
5.3.3. some notes on specific cartridges
Expert Cartridge
The original expert cartridge has a 3-position switch that is emulated by the left button on the
Chameleon The button configuration must be set to ”cartridge” when using the expert emulation A
short press toggles the expert emulation between ON and OFF (green LED is lit when the cartridge
is on) A long press puts the expert in programming mode PRG (green LED is flashing when the
cartridge is in programming mode)
Please understand that this manual cannot cover the use of all cartridges in detail Using this
cartridge requires software on a disk (image) that is not included with Chameleon
As the Expert Cartridge is RAM based, it's contents may change – you may save the current
contents by using the ROM saver, see 6 5 2 User / File menu below
Easyflash
The Flash-ROM chip of the Easyflash is not emulated Instead if the EAPI signature is found in the
first ROM bank, the EAPI area will get replaced by one that properly updates the chameleon's
RAM That means actually flashing it using the regular programming tool will not work (because
there is no flash chip) – but cartridges that incorporate the EAPI will
You may save the current contents by using the ROM saver, see 6 5 2 User / File menu below
Retro Replay
The Flash-ROM chip of the Retro Replay is not emulated To permanently replace the default ROM
you may flash it as described in 3 1 Updating using update prg above
MMC 4
The Flash-ROM chip of the MMC64 is not emulated To permanently replace the default ROM you
may flash it as described in 3 1 Updating using update prg above
20