CSSE2010/CSSE7201 Assignment 2 Semester 1, 2022

Objective

As part of the assessment for this course, you are required to undertake a project which will test you against some of the more practical learning objectives of the course. The project will enable you to demonstrate your understanding of

•   C programming

•   C programming for the AVR

•   The Microchip Studio environment.

You are required to modify a program in order to implement additional features. The program is a basic template of the board game Teeko (a description is given on page 3).

For IN students: the AVR ATmega324A microcontroller runs the program and receives input from a number of sources and outputs a display to an LED matrix, with additional information being output to a serial terminal and – to be implemented as part of this project – a seven segment display and other devices.

For EX students: the AVR ATmega328P microcontroller runs the program and receives input from a number of sources and outputs a display to a serial terminal and – to be implemented as part of this project – a seven segment display and other devices.

The version of Teeko provided to you has very basic functionality – it will present a start screen upon launch, respond to button presses or a terminal input ‘s’ to start the game, then display the starting board for the game Teeko with a cursor that flashes on and off. You can add features such as moving the cursor, placing pieces, detecting legal moves, timing, pausing, sound effects, etc. The different features have different levels of difficulty and will be worth different numbers of marks.

Don’t Panic!

You have been provided with approximately 2000 lines of code to start with – many of which are comments. Whilst this code may seem confusing, you don’t need to understand all of it. The code provided does a lot of the hard work for you, e.g., interacting with the serial port and the LED display/serial terminal. To start with, you should read the header (.h) files provided along with game.c and project.c. You may need to look at the AVR C Library documentation to understand some of the functions used. A getting started video has been provided on Blackboard.

Academic Merit, Plagiarism, Collusion and Other Misconduct

Grading Note

As described in the course profile, if you do not score at least 10% on this project (before any late penalty) then your course grade will be capped at a 3 (i.e. you will fail the course). If you do not obtain at least 50% on this project (before any late penalty), then your course grade will be capped at a 5. Your project mark (after any late penalty) will count 20% towards your final course grade.

Program Description

The program you will be provided with has several C files which contain groups of related functions. The files provided are described below. The corresponding .h files (except for project.c) list the functions that are intended to be accessible from other files. You may modify any of the provided files. You must submit ALL files used to build your project, even if you have not modified some provided files. Many files make assumptions about which AVR ports are used to connect to various IO devices. You are encouraged not to change these.

• project.c – this is the main file that contains the event loop and examples of how time- based events are implemented. You should read and understand this file.

• game.h/game.c – this file contains the implementation of the board used to store the state of the game and the position of the cursor. You should read this file and understand what representation is used for the board state and the cursor position. You will need to modify this file to add required functionality.

• display.h/display.c – this file contains the implementation for displaying the current state of the board. This file contains useful functions for displaying the board to the LED matrix (internal students) or the terminal display (external students). This file contains the same functions for IN and EX students but with significantly different implementations.

• buttons.h/buttons.c – this contains the code which deals with the push buttons. It sets up pin change interrupts on those pins and records rising edges (buttons being pushed) . For EX students this code also handles button debouncing.

• ledmatrix.h/ledmatrix.c (IN students only) – this contains functions which give easier access to the services provided by the LED matrix. It makes use of the SPI routines implemented in spi.c

• pixel_colour.h (IN students only) – this file contains definitions of some useful colours. Colours are defined in terminalio.h for EX students.

• serialio.h/serialio.c – this file is responsible for handling serial input and output using interrupts. It also maps the C standard IO routines (e.g. printf() and fgetc()) to use the serial interface so you are able to use printf() etc for debugging purposes if you wish. You should not need to look in this file, but you may be interested in how it works and the buffer sizes used for input and output (and what happens when the buffers fill up).

• spi.h/spi.c (IN Students only) – this file encapsulates all SPI communication. Note that by default, all SPI communication uses busy waiting (i.e. polling) – the “send” routine returns only when the data is sent. If you need the CPU cycles for other activities, you may wish to consider converting this to interrupt based IO, similar to the way that serial IO is handled.

• terminalio.h/terminalio.c – this encapsulates the sending of various escape sequences which enable some control over terminal appearance and text placement – you can call these  functions  (declared  in terminalio.h)  instead  of remembering  various  escape sequences. Additional information about terminal IO will be provided on the course Blackboard site.

• timer0.h/timer0.c – sets up a timer that is used to generate an interrupt every millisecond and update a global time value that is used to time various game events.

Teeko Description

This project involves creating a replica of the board game ‘Teeko’ . Teeko is a turn-based game played between two players on a 5x5 board. Each player has a set of 4 coloured pieces (green for player 1, red for player 2) they must take turns placing on the board. A player wins the game if they manage to place all of their pieces in a line (which may be a diagonal, vertical or horizontal line). Note that these lines do not wrap around the edges of the board.

The game consists of two phases, referred to in this document as game phase 1 and game phase 2.

1.   In game phase 1, the two players take turns placing their 4 pieces on the board. These pieces may be placed on any empty space on the board. This phase ends when all 8 pieces (4 green pieces + 4 red pieces) have been placed on the board.

2.   In game phase 2, players take turns picking up one of their pieces and moving it to one of the adjacent empty spaces. An adjacent space is one of the 8 surrounding spaces but does not wrap around the edges of the board. A piece cannot be placed in the same space it was picked up.

Note: In proper Teeko, players can also win by placing each of their pieces in a square of 4 adjacent spaces, however for this assignment you DO NOT need to consider this.

These rules are also described well on the Teeko Wikipedia page. Another useful resource is teeko.cc, which is an online version of the game you may wish to compare your implementation against. NOTE: these two resources allow players to win by placing pieces in a square as in the note above. Once again, you do not need to implement this behaviour.

The following figures illustrate the game layout and some of the expected game functionality.

Figure 1: The initial game board. Note the coordinate system used.

Figure 2: The valid moves when picking up a piece

are shown in light green.

Figure 3: An example of the green player winning the game.

Initial Operation

The provided program has very limited functionality. It will display a start screen which detects the rising edge on the push buttons B0, B1, B2 and B3, and also the input terminal character ‘s’ . Pressing of any of these will start a game with the start configuration and a flashing cursor.

Once started, the program detects a rising edge on the button B3, but no action is taken on this input.

Wiring Advice

When completing this assignment, you will need to make additional connections to the ATmega324A/ ATmega328P. To do this, you will need to choose which pins to make these connections to. For IN students, there are multiple ways to do this, so the exact wiring configuration will be left up to you, and you should communicate this using your submitted feature summary form.

Due to the reduced number of external pins available with the Arduino Uno for EX students, all pins have

to be used to add all features and working out a valid configuration could be quite tricky. As a result, a configuration is provided below which you are encouraged to use to ensure everything fits. Note that pins D1 and D0 are the TX/RX pins, which are being used to communicate to the serial terminal and no connections should be made to them.

Recommended EX wiring