.oO[ Mastermind v1.0 AVR ]Oo.
An 8-bit mastermind of logic!
http://www.BattleDroids.net/downloads/mastermind.html
$Id: README.txt,v 1.2 2009/08/21 09:04:02 gian Exp $

1. License
2. Background
3. System Requirements
4. Installation


License
----------------------------------------------------------------------------
Copyright (c) 2009, B. Gian James.
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, 
are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this 
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation 
and/or other materials provided with the distribution.
3. You may base commercial works off of this software/firmware but the work 
must retain the above copyright notice and reference to where the user can
download the original source code.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 
DAMAGE.

Background
----------------------------------------------------------------------------
This is the AVR version of the famous logic game Mastermind.  In this game,
the MCU will choose four colors out of seven and you will try to deduce
what colors the MCU picked.  The MCU's color choices may include duplicates.
For example, the MCU may pick "blue red white white."  Your task is to 
figure out the target color sequence by using logic.  The available colors
are: blue red yellow green white black orange.  The standard game continues
for eight rounds.

The MCU will give you two pieces of information upon which to base your next
color choice: the number of colors in your sequence that are also in the target
sequence and the number of colors that are correct that are also in the correct
slot.  For instance, if the target sequence is "blue red white white" and you
picked "blue white green yellow" the MCU would inform you that you have two
colors that are correct, and one of them is in the right slot.  If you chose
"white white green yellow" the MCU would inform you that you have two colors
correct, but none of them are in the right slot.

High score and configuration information is written to EEPROM.

System Requirements
----------------------------------------------------------------------------
I wrote this for a hardware-based game of Mastermind with RGB LED's but since
the code was already there, I just added in the UART and text information to
make this an AVR-based UART stand-alone game.  I built my system on an 
ATmega328p with a 20MHz crystal.  Also, for fun in randomization, I connected 
a Light Determining Resistor (LDR) so that when the AVR randomly choses its
color sequence, it uses an analog conversion based on the amount of ambient 
light at the time it samples the pin.  The firmware will work without an LDR.
You will also need a serial terminal program. It works best with AVR Terminal
available from http://www.BattleDroids.net/downloads/avr-terminal-1.0.zip as
special characters are sent for input and color formatting.  This firmware
will work with any serial terminal, but you must use fixed-width (monospace)
fonts else you will have ugly formatting issues.

Installation
----------------------------------------------------------------------------
If you have built the system, you can use your programmer via ISP to load 
the Mastermind-57600.hex file.  The serial connection speed is 57600.  If you
are using an Arduino or clone, upload the Mastermind-arduino.hex file and
connect AVR Terminal or another serial terminal at 9600 baud.  Give it a
second because there's a lot of text and 9600 baud transfers data at a 
glacial pace.  

If you wish to build from source, copy the appropriate makefile to makefile.
Arduino: copy Makefile-arduino to Makefile.
ATmega328p: copy Makefile-usbtiny to Makefile. You may have to edit it to change
F_CPU if you are running at a speed other than 20MHz.  You will also have to
change AVRDUDE setting to reflect your programmer if you are not using a
USBTiny programmer.

For both, type make, then make program to upload it to your MCU. If you are 
using an Arduino don't forget to hit the reset button a microsecond before 
you type 'make program.'
