1. DESCRIPTION
Kameleon is a behavior-rich, non-memoryless and time-aware generic simulator.
This simulator, or more precisely server, handles ordinary clients through a
TCP/IP connection. An instance of this client is an EPICS IOC or a Tango Device
Server.

Kameleon uses a user-defined file that describes the commands received from a
client and, optionally, the reaction to these through statuses sent back to the
client. Please check file "example.kam" to get an extensive explanation about
commands and statuses, and how to define these. To get an illustration of the
behaviors achieved when running Kameleon with this file, please check the
screenshot "example.png". Both files are stored in folder "simulators/example".

Several simulators of disparate devices (e.g. power supplies, oscilloscopes,
temperature sensors, heating circulators) can be found in folder "simulators"
and be used with Kameleon out-of-the-box.


2. FEATURES
The main features of Kameleon are the following:

   - Ubiquitous (runs in disparate platforms such as Windows and Linux).
   - Behavior-rich (predefined behaviors as well as user-defined):
        - FIXED (sends a fixed value to the client).
        - ENUM (sends a value - belonging to an enumeration - to the client).
        - INCR (sends an incremented value to the client).
        - RANDOM (sends a random value to the client).
        - CUSTOM (sends a value from a user-defined function to the client).
   - Non-memoryless (the state of the simulator can be preserved between events
     and/or elapsed time so that, for instance, a finite-state machine can be
     implemented).
   - Time-aware (a status can be sent to the client either event-based -
     whenever a certain command is received - or time-based - after a certain
     elapsed time).
   - Flexible (commands and statuses are described in a simple user-defined
     file - nothing is hard-coded in Kameleon).


3. DEPENDENCIES
To run Kameleon, a Python interpreter must be installed first. If there is
none installed in the machine, download one from http://www.python.org/download
and install it.


4. EXECUTION
To run Kameleon, open a terminal and execute:

   python kameleon.py

This will make Kameleon listen for incoming clients at (default) port 9999. To
have the tool simulating a device where its commands/statuses are described in
a user-defined file named "X" (for instance), execute:

   python kameleon.py --file=X

Finally, to see all valid parameters accepted by Kameleon, just execute:

   python kameleon.py --help


5. SUPPORT
Please contact ricardo.fernandes@esss.se in case a bug is found or a feature
is missing in Kameleon.