The University of Queensland
School of Information Technology and Electrical Engineering Semester 2, 2019
CSSE2010CSSE7201 PROJECT
Due: 5:00pm Friday October 25, 2019 Weighting: 20 100 marks
Updated version issued 13 October 2019clarificationsupdates shown in red.
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 Atmel Studio environment.
You are required to modify a program in order to implement additional features. The program is a version of PacMan. If youre unfamiliar with the game, there are versions playable online, e.g. https:www.webpacman.compacmanhtml5.php. The AVR ATmega324A microcontroller runs the program and receives input from a number of sources and displays output to a serial terminal andto be implemented as part of this projectthe LED matrix, a seven segment display and other LEDs.
The version of PacMan provided to you will implement some but not all required functionalityit will present a game field with a pacman character, pacdots and ghosts and allow the pacman and ghosts to move. You can add features such as scoring, multiple lives, use of the joystick, sound effects, etc. The different features have different levels of difficulty and will be worth different numbers of marks.
Dont Panic!
You have been provided with approximately 2300 lines of code to start withmany of which are comments. While this code may seem confusing, you dont 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. To start with, you should read the header .h files provided along with project.c and game.c. You may need to look at the AVR C Library documentation to understand some of the functions used.
Academic Merit, Plagiarism, Collusion and Other Misconduct
You should read and understand the statement on academic merit, plagiarism, collusion and other misconduct contained within the course profile and the document referenced in that course profile. You must not show your code to or share your code with any other student under any circumstances. You must not post your code to public discussion forums or save your code in publicly accessible repositories. You must not look at or copy code from any other student. All submitted files will be subject to electronic plagiarism detection and misconduct proceedings will be instituted against students where plagiarism or collusion is suspected. The electronic plagiarism detection can detect similarities in code structure even if comments, variable names, formatting etc. are modified. If you copy code, you will be caught.
CSSE2010CSSE7201 Project, Semester 2, 2019 1
Grading Note
As described in the course profile, if you do not score at least 15 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. Resubmissions prior to grade finalization are possible to meet the 15 requirement in order to pass the course, but a late penalty will be applied to the mark for final grade calculation purposes.
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.cthis 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.hgame.cthis file contains the implementation of the operations e.g. movements in the game. You should read this file and understand what representation is used for the game. You will need to modify this file to add required functionality.
buttons.hbuttons.cthis contains the code which deals with the IO board push buttons. It sets up pin change interrupts on those pins and records rising edges buttons being pushed.
ledmatrix.hledmatrix.cthis 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.
linedrawingcharacters.hthis file contains definitions of Unicode linedrawing characters used to draw the game field on the serial terminal.
pixelcolour.hthis file contains definitions of some useful colours for the LED matrix.
score.hscore.ca module for keeping track of and adding to the score. This module is
not used in the provided code.
scrollingchardisplay.hscrollingchardisplay.cthis contains code which provides
a scrolling message display on the LED matrix board.
serialio.hserialio.cthis 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.hspi.cthis file encapsulates all SPI communication. Note that by default, all SPI communication uses busy waitingthe 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.hterminalio.cthis encapsulates the sending of various escape sequences which enable some control over terminal appearance and text placementyou 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.htimer0.csets up a timer that is used to generate an interrupt every millisecond and update a global time value.
CSSE2010CSSE7201 Project, Semester 2, 2019 2
Initial Operation
The provided program responds to the following inputs:
Rising edge on the button connected to pin B3
Serial input escape sequence corresponding to the cursorleft key
Both of these cause the pacman to move towards the left of the screen if that is possible at the time the input is received. Note that your serial terminal display should have at least 32 rows.
The program also responds to:
Rising edge on the button connected to pin B0
Serial input escape sequence corresponding to the cursorright key
Both of these cause the pacman to move towards the right of the screen if that is possible at the time the input is received.
Code is present to detect the following, but no actions are taken on these inputs:
Rising edge on button connected to pins B1 and B2
Serial input escape sequences corresponding to the cursor up and down keys
Serial input characters p and P intended to be the pauseunpause key
Program Features
Marks will be awarded for features as described below. Part marks will be awarded if part of the specified functionality is met. Marks are awarded only on demonstrated functionality in the final submissionno marks are awarded for attempting to implement the functionality, no matter how much effort has gone into it, unless the feature can be demonstrated. You may implement higher level features without implementing all lower level features if you like subject to prerequisite requirements. The number of marks is not an indication of difficulty. It is much easier to earn the first 50 of marks than the second 50.
You may modify any of the code provided and use any of the code from learning lab sessions andor posted on the course Blackboard site. For some of the easier features, the description below tells you which code to modify or there may be comments in the code which help you.
Note that your serial terminal window will need at least 31 rows in order to play the game.
Minimum Performance Level 0PassFail
Your program must have at least the features present in the code supplied to you, i.e., it must build and run and output the PacMan game field to a serial terminal, show moving ghosts, and allow the pacman to be moved. No marks can be earned for other features unless this requirement is met, i.e., your project mark will be zero.
Splash Screen Level 14 marks
Modify the program so that when it starts i.e. the AVR microcontroller is reset it scrolls a message to the LED display that includes your student number. You must also change the message output to the serial terminal to include your name and student number. Do this by modifying the function splashscreen in file project.c.
Move Pacman Up and Down Level 15 marks
The provided program only allows the pacman to move left and right in response to the buttons and keypresses described above. You must update the input processing in the playgame function in project.c in order to enable the pacman to move up and down also. Note that this feature is required for most of the features below to be tested.
CSSE2010CSSE7201 Project, Semester 2, 2019 3
Movement Through the Wraparound Passageway Level 19 marks
The provided program does not allow the pacman to move through passageways in the middle of the left and righthand sides of the game field. Implement this moving behaviour, i.e. if the pacman moves to the left from the leftmost position in the lefthand passageway then it should reappear on the righthand side. Similarly, the pacman should be able to wraparound from the righthand side to the left. The functionality can be implemented within the movepacman function in game.c. There is noneed to allow the ghosts to wraparound but you may modify this behaviour if you wish. No marks are associated with allowing ghosts to wraparound.
Eating the PacDots Level 19 marks
The provided code just allows the pacman to move over the top of the pacdotsthey arent consumed. Add code to the eatpacdot function in game.c so that pacdots are consumed and a count of the remaining number of pacdots is shown in a fixed position on the serial display outside the game field. The count should be updated when and only when the number of pac dots changes.
New Game Level 19 marks
Add a feature so that if the n or N key is pressed, a new game is started at any timeincluding game over or if the current game is in progress. You can ignore n or N being pressed while the splash screen is displayed since a new game is starting anyway. The gamefield and score must be reset. If multiplelives are implemented see below then the lifecount should be reset also. The highscore if implementedsee Scoring below must not be reset. Game play should behave as it does for the first game after poweron. Your program must support an unlimited number of new games being started without crashing.
Scoring Level 19 marks
Add a scoring method to the program so that 10 is added to the score each time the pacman eats a pacdot. You should make use of the function addtoscoreuint16t value declared in score.h. You should call this function with an appropriate argument from any other function where you want to increase the score. If a .c file does not already include score.h, you may need to include it. You must also keep track of the high score initially 0 on poweron and update it whenever there is a new high scoreincluding during game play if the current game has the highest score. You must also add code to display the score and the high score to the serial terminal in a fixed position outside the game field and update the score display only when it changes and the high score display only when it changes. The scores must be displayed in a block that looks like this with identical column alignment:
Score
0
High Score
11240
The displayed scores must be rightaligned, i.e. the rightmost digit in each score must be in a fixed positionin line with the rightmost character in the titles Score and High Score. Hintconsider the format specifiers for printf. A score of 0 must be displayed when the game starts. A highscore of 0 must be displayed for the first game after poweron or hardware reset. For later games, the current high score should be shown. The score and highscore must remain displayed on gameover until a new game commences when the score should be reset but the highscore should continue to be displayed.
Moving Ghosts at Different Rates Level 19 marks
The provided program moves the ghosts all at the same time once every 500ms. Update the program so that each ghost moves at a different ratebut a constant rate for each ghost. These movement rates should range from once every 400ms to once every 600ms.
CSSE2010CSSE7201 Project, Semester 2, 2019 4
Multiple Lives Level 26 marks
The provided game is over as soon as soon as a ghost touches the pacman. Implement multiple lives so that the pacman has three 3 chances to complete the gamelevel. The number of lives remaining is shown using 3 LEDs L2, L1, L0 which initially are all switched on. When the third last life is lost and the game is over then all LEDs are off. The number of lives remaining 1 to 3 must also be shown on the serial terminal display in a fixed position. This number does not have to be but can be shown when the number is 0, i.e. the game is over. If you wish, you can add an additional life when a level is completed. This is not required and may not be tested.
When a ghost eats a pacman and a life is lost, you should not leave the pacmanghosts in the same position. You can either
return all the ghosts to the homeposition and pacman to its starting position this is what traditional PacMan does;
move the ghost that ate the pacman or all ghosts to the home position but leave the pac man where it is; or
move just the pacman to a new location not near any ghosts. The number of remaining pacdots stays the same when a life is lost.
Game Pause Level 26 marks
Modify the program so that if the p or P key on the serial terminal is pressed then the game will pause. When the button is pressed again, the game recommences. All other movement buttonkey pressesinputs should be discarded whilst the game is pausedi.e. will not affect the movement of the pacman when the game is later unpaused. The pacman and ghost movement rates must be unaffectede.g. if the pause happens 200ms before a ghost is due to move, then the ghost must not move until 200ms after the game is resumed, not immediately upon resume. The check for this key press is implemented in the supplied code, but does nothing.
If new game functionality is implemented see above then the n and N key presses are not ignored during game pausea new game should be started immediately.
If the EEPROM save game functionality is implemented see below then the s and S key presses are not ignoredthe current game state is saved. Similarly, the o and O key presses are not ignoredthe saved game state if available is restored immediately.
See Sound Effects below for details on the interaction between game pause and sound effects.
Joystick Level 26 marks
Add support to use the joystick to move the pacman in all directions. If at the time of pacman movement, the joystick position indicates a direction in which the pacman can move a valid direction, then the pacman should start moving in that direction. If the joystick position indicates an invalid direction then the pacman should continue in its current direction if possible, independent of any input received from buttons or serial input i.e. the joystick overrides other direction inputs, even if the joystick direction is not a valid movement direction, i.e. there is a wall in that direction. If the joystick is in its resting position, then the pacman should change direction as indicated by any button or serial input if valid or continue in its current direction. Game movement rates of the pacman and the ghosts should be the same when playing the game with the joystick as they are when playing with the buttons or serial input cursor keys.
Note that you must handle the joystick being held in diagonal positions and choose one of the two directions if both are possible or move in the valid direction if only one of the two is possible. Be sure to specify which AVR pins the UD and LR outputs on the joystick are connected to. Movement of the joystick in its LR direction must correspond to leftright movement of the pac man; movement of the joystick in its UD direction must correspond to updown movement of the
CSSE2010CSSE7201 Project, Semester 2, 2019 5
pacman. Be aware that different joysticks may have different minmaxresting output voltages and you should allow for this in your implementation e.g. allow for a deadzone over a range of ADC values in the centre of the X and Y ranges. Your code will marked with a different joystick to the one you test with.
Power Pellets Level 29 marks
Requires Scoring to be implemented.
Implement power pellets or energizers similar to those found in traditional PacMan. At the start of the game, there should be four power pellets, placed near but not at the four corners of the game fieldas indicated in the initial game field in game.c. These power pellets should be indicated with an appropriate character, and a foreground colour different to the pacdots and the pacman. Ghosts can move through power pellets in the same way they can move through pac dots. When a power pellet is eaten by the pacman, 50 points is added to the score and the ghosts should all turn blue. The pacman then has 15 seconds powerup period during which it can eat the ghosts to score additional points200 for the first ghost eaten in that period, 400 for the second, 800 for the third and 1600 for the fourth. The score should be updated on the display when and only when it changes. When a ghost is eaten it is returned immediately to its home position and stays there until the 15 second period is over. Immediately is intended to mean that the ghost teleports to the home position, but you can make the ghost travel through the maze to the home position if you wish. Ghost colours should return to normal at the end of the 15 second period and any in the home position can then move out of that position.
When the powerup period starts, the time remaining in that period in seconds must be shown on the two digit sevensegment display. When the number displayed is less than 10 then the left digit should be blanked. The time should be rounded up, i.e. 15 is shown while the time remaining is greater than 14 seconds and less than or equal to 15 seconds. 1 is shown when 1 second or less remains. The seven segment display digits should be blank when not in a power up period. You must specify which AVR pins the sevensegment display pins are connected to.
Note that, unlike traditional PacMan, you do not need to change the ghost movement algorithmghosts can continue to move in the same manner and with the same speed as before the pacman eats the power pellet. You can change the algorithm if you wish but there are no marks associated with this.
You can choose a whether power pellets are included in the count of remaining pacdots, and b whether all power pellets must be eaten to advance to the next level, or just all the pacdots.
If another powerpellet is eaten during a powerup period, you must still implement the behaviour above, i.e. 50 points is scored immediately and scoring for eating ghosts should reset to 200 for the first ghost eaten in that period. You may choose what happens to ghosts in the home position at the time of the second powerpellet being eaten, e.g.
ghosts remain in the home position until the end of the new 15 second period;
ghosts in the home position are immediately released at the time the second powerpellet
is eaten you can think of this as the first powerup period finishing early; or
ghosts in the home position are released 15 seconds after the start of the first powerup
period and can then be eaten during the remaining time of the second powerup period. You shouldnt be able to eat more than 4 ghosts in the powerup period we will not test the pac man entering the home position.
Sound Effects Level 35 marks
Add sound effects to the program which are to be output using the piezo buzzer. Different sound effects tones or combinations or tones should be implemented for at least four events. At least
CSSE2010CSSE7201 Project, Semester 2, 2019 6
two of these must be sequences of three or more tones for full marks. For example, choose four of:
Pacman eating pacdot
Pacman eating power pellet
Pacman changing direction
Ghost eating pacman i.e. game over or loss of life1
Pacman eating ghost during powerup period
game startup
constant background tune
You may choose game events other than those listed but do not choose an event that can not be demonstrated quickly, e.g. we will not look for nor award marks for a sound effect on a new level i.e. when all the pacdots are eaten.
Do not make the tones too annoying! Switch 7 on the IOboard must be used to toggle sound on and off 1 is on, 0 is off. You must specify which AVR pin this switch is connected to and which AVR pin the piezo buzzer must be connected to. The piezo buzzer will be connected from there to ground. Your feature summary form must indicate which events have different sound effects. Sounds must be tones not clicks in the range 20Hz to 5kHz. Sound effects must not interfere with game play, e.g. the speed of play should be the same whether sound effects are on or off. Sound must turn off if the game is paused and resume when the game is unpaused e.g. if a sound effect is incomplete, unless switch 7 is switched off while the game is paused.
You may choose what to do if a new game event with an associated sound happens while a sound effect is still being played from a previous game event, e.g. continuing to play the original sound and then playing the second sound; or terminating the first sound and then playing the second. Your choice should be reasonable, i.e., the sounds must interact well together and not result in spurious sounds when changing from one to the other.
When a new game is started by pressing the n or N keys then any sound effects playing from the previous game should stop immediately.
EEPROM Game Storage Level 36 marks
Implement storage of the complete game state in EEPROM. If the s or S key is sent from the serial terminal then the whole game state should be savedand a message indicating this should be output to the terminal. If the o or O key for Open is later sent possibly after the board is poweredoff and then back on, then the saved game should be retrieved and play should continue on in that game. You must handle the situation of the EEPROM initially containing data other than that written by your program. You may need to use a signature value to indicate whether your program has initialized the EEPROM for useit should not be possible to open a saved game if none was saved. When your game starts i.e. afterduring the powerup splash screen it should indicate on the terminal display whether a saved game exists in EEPROM or not.
The game state includes the following
location and movement direction of the pacman
locations and movement directions of all of the ghosts
locations of all uneaten pacdots
locations of all uneaten power pellets if implementedsee above
the current score
the high score
the number of lives remaining assuming multiple lives are implementedsee above
1 Loss of the last life game over can be treated as a separate event to loss of other lives if desired.
CSSE2010CSSE7201 Project, Semester 2, 2019 7
whether the game is in a powerup period, and if so, how much time remains if power pellets are implemented. The time need only be remembered to the nearest secondi.e. the number displayed on the 7segment display should be the same after the game is restored.
Game state does not include
whether the game is paused or notthe game will resume in an unpaused state when
opened;
whether a sound effect is playing and what fraction of a soundeffect has played; or
the timing of pacman and ghost movement, i.e. how much time to the next movement or from the last movementthough you can record this if you wish for no marks.
You may choose only one of the two following LED matrix options.
LED Matrix DisplayOption OneInfo Display Level 35 marks
Assumes scoring and multiple lives are implemented.
Use the LED matrix to display the current score and the remaining lives. These should be updated on the display as soon as they change. The upper five of the eight rows should show the score in red using up to four digitswhere each digit occupies a space 5 pixels high and 3 pixels widewith a blank column between them. You should use the following font.
Scores higher than 9999 are unlikely to be tested, but if they are then your program should handle this appropriately i.e. not crash and not display garbage. The bottom three rows should show the remaining pacman lives, i.e. initially twodown to zero when the pacman is on its last life. The number of pacmen shown here will be one fewer than the number of LEDs illuminatedsee multiple lives above. The remaining pacman lives should each be shown with a 33 yellow image:
LED Matrix DisplayOption TwoScrolling Game Display Level 38 marks
The LED matrix must show an 168 window on the game fieldcentred on the pacman. As the pacman moves, the LED matrix display should update so as to keep the game centred on the pac man. The following colours should be used:
pacmanyellow
ghostsgreen
wallsred
pacdotsvery pale red
empty spaceblack LED off
powerpellets if implementedorange
ghosts during the powerup periodpale green
For example, the initial display will look something like the following:
CSSE2010CSSE7201 Project, Semester 2, 2019 8
22
The pacman will always be shown at the same location on the LED matrix. If it moves left in the game, then the LED matrix view scrolls right so as to keep the pacman in the same location.
Assessment of Program Improvements
The program improvements will be worth the number of marks shown above. You will be awarded marks for each feature up to the maximum mark for that feature. Part marks will be awarded for a feature if only some part of the feature has been implemented and demonstrated or if there are bugsproblems with your implementation which may include issues such as incorrect data direction registers, flickering, intermittent misbehaviour, etc.. Your additions to the game must not negatively impact the playability or visual appearance of the game. Note also that the features you implement must appropriately work together, for example, if you implement game pausing then sound effects should pause.
Features are shown grouped in their levels of approximate difficulty level 1, level 2, and level 3.
Submission Details
The due date for the project is 5:00pm Friday October 25, 2019. The project must be submitted via Blackboard. You must electronically submit a single .zip file containing ONLY the following:
All of the C source files .c and .h necessary to build the project including any that were provided to youeven if you havent changed them;
Your final .hex file suitable for downloading to the ATmega324A AVR microcontroller program memory; and
A PDF feature summary form see below.
Please do not submit .rar or other archive formatsthe single file you submit should be a zip format file. All files must be at the top level within the zip filedo not use foldersdirectories or other ziprar files inside the zip file.
If you make more than one submission, each submission must be completethe single zip file must contain the feature summary form and the hex file and all source files needed to build your work. We will only mark your last submission and we will consider your submission time for late penalty purposes to be the time of submission of your last submission.
The feature summary form is on the last page of this document. A separate electronicallyfillable PDF form will be provided to you also. This form can be used to specify which features you have implemented and how to connect the ATmega324A to peripherals so that your work can be marked. If you have not specified that you have implemented a particular feature, we will not test for it. Failure to submit the feature summary with your files may mean some of your features are missed during marking and we will NOT remark your submission. You can electronically
2 These squares were shown in the incorrect colour in the original specification.
CSSE2010CSSE7201 Project, Semester 2, 2019 9
complete this form or you can print, complete and scan the form. Whichever method you choose, you must submit a PDF file with your other files.
Assessment Process
Your project will be assessed during the revision period the week beginning Monday 28 October 2019. You have the option of being present when this assessment is taking place, but whether you are present or not should not affect your mark provided you have submitted an accurate feature summary form. Arrangements for the assessment process will be publicised closer to the time.
Incomplete or Invalid Code
If your submission is missing files i.e. wont compile andor link due to missing files then we will substitute the original files as provided to you. No penalty will apply for this, but obviously no changes you made to missing files will be considered in marking.
If your submission does not compile andor link in Atmel Studio 7 for other reasons, then the marker will make reasonable attempts to get your code to compile and link by fixing a small number of simple syntax errors andor commenting out code which does not compile. A penalty of between 10 and 50 of your mark will apply depending on the number of corrections required. If it is not possible for the marker to get your submission to compile andor link by these methods then you will receive 0 for the project and will have to resubmit if you wish to have a chance of passing the course. A minimum 10 penalty will apply, even if only one character needs to be fixed.
Compilation Warnings
If there are compilation warnings when building your code in Atmel Studio 7, with default compiler warning options then a mark deduction will apply1 mark penalty per warning up to a maximum of 10 marks. To check for warnings, rebuild ALL of your source code choose Rebuild Solution from the Build menu in Atmel Studio and check for warnings in the Error List tab.
Late Submissions
Late submission will result in a penalty of 10 plus 10 per calendar day or part thereof, i.e. a submission less than one day late i.e. submitted by 5:00pm Saturday 26 October, 2019 will be penalised 20, less than two days late 30 and so on. The penalty is a percentage of the mark you earn after any of the other penalties described above, not of the total available marks. Requests for extensions should be made via the process described in the course profile before the due date and be accompanied by documentary evidence of extenuating circumstances e.g. medical certificate. The application of any late penalty will be based on your latest submission time.
Notification of Results
Students will be notified of their results at the time of project marking if they are present or later via Blackboards My Grades.
CSSE2010CSSE7201 Project, Semester 2, 2019 10
The University of QueenslandSchool of Information Technology and Electrical Engineering Semester 2, 2019CSSE2010CSSE7201 ProjectFeature Summary
Student Number Family Name Given Names
An electronic version of this form will be provided. You must complete the form and include it as a PDF in your submission. You must specify which IO devices youve used and how they are connected to your ATmega324A.
Port
A B C
D
Feature
Splash screen
Move UpDown
Passageway Movement
Eating Pacdots New Game Scoring
Ghost Move Rate Multiple Lives Game Pause Joystick
Power Pellets
Sound Effects
EEPROM Game Storage
Info Display
Game Display
Pin 0
Button B0
Pin 7
Pin 6 Pin 5
SPI connection to LED matrix
Pin 4
Pin 3
Button B3
Pin 2
Button B2
Pin 1
Button B1
Serial RX
Baud rate: 19200
Mark
u if attempted
Comment
Anything you want the marker to consider or know?
Choose one only
LED Matrix
Penalties: code compilation, incorrect submission files, etc. Does not include late penalty Final Mark: excluding any late penalty which will be calculated separately
8 19 Total: out of 100, max 100
Serial TX
4
5
9
9
9
9
9 54 6
6
6
9 27
5
6
5
Reviews
There are no reviews yet.