CSSE2010/CSSE7201 AVR Project

CSSE2010/CSSE7201 Semester 2 2024 AVR Project CSSE2010/CSSE7201 AVR Project Semester 2, 2024 - Version 1.01 (06/10/2024) Due: 4:00pm, Friday 25th October Weighting: 20% (100 marks) Clarifications and changes since the initial release of the project specification are in red. Objective As part of the assessment for this course, you are required to undertake an AVR project which will test you against some of the more practical learning objectives of the course, namely your C programming skills applied to the ATmega324A microcontroller. You are required to modify a program to implement additional features. The program is a basic template of the game “Sokoban” (described in detail on page 3) and has very basic functionality. It will present a start screen upon launch, respond to push button presses or a terminal input “s”/“S” to start the game, then display the first level which contains a map of game objects and a flashing player icon. You can add features such as moving the player, game logic, pausing, audio etc. The various features have different levels of difficulty and will each contribute a certain number of marks. Don’t Panic While this is a long project specification, there’s not actually that much code to write! You’ve been provided with approximately 2000 lines of code to start with! You are not expected to fully understand all of the provided code, and several intro/getting started videos are available on Blackboard, which contains a demonstration of some of the expected functionality to be implemented and walks through setting the project up with the provided base code, as well as how to submit. Note The requirements in this document take priority over anything shown in the feature demonstration videos. Academic Integrity 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. 1

CSSE2010/CSSE7201 Semester 2 2024 AVR Project 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, even after the completion of this course. You must not look at or copy code from any other student. All submitted files may be subject to electronic plagiarism detection and the electronic plagiarism detection can detect similarities in code structure even if comments, variable names, formatting etc. are modified. Your submission will be compared against the submissions of all other students, including submissions from previous semesters and 20 submissions generated by 5 different large language models (generative AIs). Furthermore, a random sample of 50 submissions will be spot checked and manually reviewed for academic integrity by the staff team. Formal misconduct proceedings will be instituted against students where plagiarism or collusion is suspected. Grading Note As described in the course profile, if you do not score at least 10% on this AVR project (before any 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 AVR project (before any penalty), then your course grade will be capped at a 5. Your AVR project mark (after any penalty) will count 20% towards your final course grade. This project has 17 features, broken into three tiers, and marks are distributed as follows: Tier A Tier B Tier C Available Marks 54 34 24 Max Mark 50 30 20 112 This means if you implement all features of tier A and score full marks for each feature, you will receive 54 marks, however it will be capped at 50 when the grade of your project is calculated. This also means that you do not need to score full marks for each feature to be able to achieve 100% for the project. Code Style and Restrictions There is no restriction on your code, as long as your code compiles with Microchip Studio installed on the lab computers. No marks are awarded nor deducted in the marking criteria for code style, however you are advised to follow a good code style for your own benefit and to make it easier for course staff to assist you. You may freely create and add .c/.h files, as well as include additional header files (eg: string.h, ctype.h) from the C Standard Library to any source file using #include. You may use any C language feature (e.g., switch statements, structures, pointers), provided that they are C99 compliant and supported by the GCC compiler used by Microchip Studio. 100 2

CSSE2010/CSSE7201 Semester 2 2024 AVR Project Provided Code You have been provided with some base code as a starting point for this project. You should import the base code files into a project, and you will be working on adding features to the provided base code. There is a documentation of the base code on Blackboard which you should read prior to implementing the features and refer to while working on the project. A setting up video on Blackboard shows how to create a new project and get the base code up and running. Sokoban Description This AVR project involves creating a replica of the classic game “Sokoban”. Sokoban is a classic puzzle video game in which the player pushes boxes around in a warehouse, aiming to get them to designated storage locations. There are 4 main object types in a game of Sokoban – player, wall, box and target. The player and boxes are movable, while walls and targets are not. In the original game, the player may push a box in 4 directions – left, right, up and down, provided that there is no wall or other boxes behind the box. 2 boxes cannot be pushed together. The player can move to empty or targetCSSE2010代做、代写c/c++编程设计 squares, but not to walls or boxes (boxes can be pushed, but player and box can never coexist on the same square). The level is complete when all boxes have been pushed onto the targets by the player. The number of boxes is always equal to the number of targets. For this AVR implementation, the warehouse is represented using the 16x8 LED matrix: Note When you create a new project in Microchip Studio, a main.c file will automatically be created, containing an empty main() function. project.c also contains a main() function, but Microchip Studio will preferentially look for the main() function in the main.c file, if it exists. Please ensure that you delete the main.c file so that Microchip Studio will look for the main() function in project.c. Note You may play the Sokoban game online at sokoban.info/ to gain a better understanding of the game. Please note however the version of Sokoban described in this project specification has differences compared to online version, and you must implement the game according to this specification. 3

CSSE2010/CSSE7201 Semester 2 2024 AVR Project Player (flashing) Wall Box Target Box on target (black/empty) Figure 1: Snapshot of a sample game, showing all game objects in action. The flashing player icon is rendered in this document as , meaning that particular pixel of the LED matrix flashes between dark green and black. Likewise, means a pixel which flashes between dark green and red (i.e., player on a target). Initial Operation The provided program has very limited functionality. It will display a start screen (see Figure 2) which detects the rising edge on the push buttons B0, B1, B2 and B3, as well as the input terminal character “s”/“S”. Pressing any of these will start a game of Sokoban and take you to the initial game board as illustrated in Figure 3. LED Matrix Terminal Figure 2: Start screen on the LED matrix (scrolling) and on the terminal. Once started, the provided program is capable of detecting a rising edge on the push button B0, but no action when the button is pressed (this will need to be implemented as part of the Move Player with Push Buttons feature). Legend: Figure 3: Initial game board after starting the game. 4

CSSE2010/CSSE7201 Semester 2 2024 AVR Project Terminal Layout The terminal used for marking will have 80 columns and 24 rows, and you are advised to keep this in mind when implementing the project. During gameplay, a message area one row in height is defined on the terminal, for displaying messages. Figure 4: Recommended in-game terminal layout. Wiring Advice When completing this AVR project, you will need to make additional connections to the ATmega324A microcontroller to implement particular features. To do this, you will need to choose which pins to make these connections to. There are multiple ways to do this, so the exact wiring configuration will be left up to you, and you must communicate this using your submitted feature summary form (on Blackboard). Hint Before implementing any features, read through them all, and consider what peripherals each feature requires and any pin limitations this imposes. If you do not do this, you may find yourself in a situation where the pins that must be used for a peripheral for a later feature are already connected to another peripheral, requiring you to rewire your breadboard and update your code before you can use the new peripheral. Some connections are defined for you in the provided base code and are shown in grey in the following table. Wiring Table Port Pin 7 A B C D Pin 6 Pin 5 Pin 4 Pin 3 Pin 2 Pin 1 Pin 0 SPI connection to LED matrix Button B3 Button B2 Button B1 Button B0 Serial RX Serial TX Baud rate: 19200 5

CSSE2010/CSSE7201 Semester 2 2024 AVR Project Program Features Marks will be awarded for features as described below. Part marks will be awarded if part of the specified functionality is demonstrated. Marks are awarded only on demonstrated functionality in the final submission – no marks are awarded for attempting to implement the functionality, no matter how much effort has gone into it, if there is no evidence of functionality when the program is run. You may implement higher-tier features without implementing all lower-tier features if you like (subject to prerequisite requirements). The number of marks is not an indication of difficulty. Marks may be deducted if features interact negatively with one another or affect gameplay experience. You may modify any of the code provided and use any of the code from learning lab sessions and/or posted on the course Blackboard site. Minimum Performance Minimum Performance Pass/Fail Your program must have at least the features present in the code supplied to you, i.e., it must build on Microchip Studio and run, show the start screen, and display the initial game when a push button or “s”/“S” is pressed. No marks can be earned for other features unless this requirement is met, i.e., your AVR project mark will be zero. Start Screen Start Screen Tier A: 4 marks Modify the program so that when it starts (i.e., the AVR microcontroller is reset) it outputs your name and student number to the serial terminal, in the indicated location (remove the placeholder text, including the chevrons <>). Do this by modifying the function start_screen in file project.c. Move Player with Push Buttons Move Player with Push Buttons Tier A: 6 marks The provided program does not allow moving the player. Modify the program so that when push button B0 (connected to port B pin 0) is pressed, the player moves right. Similarly, pressing push button B1 (connected to port B pin 1) should move the player down, push button B2 (connected to port B pin 2) should move the player up, and push button B3 (connected to port B pin 3) should move the player left. If the player would be moved off the LED matrix display, it must wrap around to the other side of the display. For example, if the player is on the far-right side of the LED matrix, then pressing B0 must move the player to the far-left side of the LED matrix (same is true for up/down). Whenever the player is moved, the flashing cycle of the player icon must be reset, such that the player icon instantly displays dark green and remains dark green for 200ms. The player should move when the button is pressed; no behaviour is expected when the button is released, nor if the button is held down. If the player is moved onto a target, the target must flash between dark green and red ( ). When the player is moved off the target, the target must revert to displaying solid red. You do not have to consider moving onto walls or boxes until the later Game Logic – Walls and Game Logic – Boxes features, respectively. 6

CSSE2010/CSSE7201 Semester 2 2024 AVR Project Hint The function play_game in project.c calls move_player(0, 1) in game.c when push button B0 is pressed. The move_player function is currently empty; start by filling it in according to the comments provided. Move Player with Terminal Input Move Player with Terminal Input Tier A: 6 marks The provided program does not register any terminal inputs once the game has started. Modify the program so that pressing “w”/“W” moves the player up, and “a”/“A”, “s”/“S”, and “d”/“D” move the player left, down, and right, respectively, in a similar manner to the previous task. Note that both the lowercase and uppercase versions of each letter must execute these movements as described. Also, note that the inbuilt serial functionality handles keyboard inputs that are held down for you. Just like in the previous task, the player must wrap around the edges, and the flashing must be reset whenever the player moves. Holding down a key will usually send multiple instances of that key to the terminal. Unlike the push buttons, this means holding down a key will result in the player repeatedly moving, which is fine and to be expected. Hint GameLogic–Walls On the start screen, the game can be started by pressing “s”/“S”; look at the function start_screen() to get an idea of how to read serial inputs from the terminal. Game Logic – Walls Tier A: 6 marks Requires Move Player with Push Buttons or Move Player with Terminal. When the player attempts to move onto a wall, nothing should happen, and a message must be printed to the message area of the terminal telling the player that they’ve hit a wall. Below is an example of moving to the right onto a wall. Before Action After Message [Previous Message] I've hit the wall.*1 Figure 5: Example of player moving to the right and hitting a wall. This is only one example; you must consider the player hitting walls after moving up, left and down as well. Given how often people run into walls, the message displayed must be randomly chosen from at least three different messages. You may decide on the messages to use; however, they must clearly indicate that the player has hit a wall, and the order in which the messages are displayed must be non- deterministic (random). As with the player movements, if the player is on the far-right side of the LED matrix, and there is a wall on the far-left side of the LED matrix, and the player moves to the right, they would hit the wall on the far-left side, and the move would be considered invalid. The same goes for all the other edges. Display → Terminal: “d”/”D” Buttons: B0 7

CSSE2010/CSSE7201 Semester 2 2024 Before AVR Project Action After Display → Terminal: “d”/”D” Buttons: B0 I've hit the wall.*1 Figure 6: Example of player moving to the right and hitting a wall after wrapping around. This is only one example; you must consider hitting walls after wrapping around in other directions too. A valid move is defined as a move that changes the player’s location, and whenever a valid move is made, the message area of the terminal must be cleared. Message [Previous Message] Hint The C Standard Library includes a function rand() for returning pseudo-random numbers. The numbers returned by the rand() function are deterministic (i.e. the first time you call it each time you start your program, it’ll always give you the same number), unless you seed the random number generator with a custom, pseudo-random seed. The random number generator can be seeded by calling the function srand(), with the appropriate seed as argument. Current time is often used by programmers as the random seed, and you are recommended to do so as well. You should only seed the random number generator once. Hint You will not be able to use the time() function for retrieving the current time, because it does not work by default on the AVR. You should instead search for functions given to you in the base code. Hint The time when, for example, initialise_hardware(), is called is always the same (e.g., 40 milliseconds after the microcontroller is reset), as it always takes a specific number of instructions to arrive at that particular line of code. The time when the player presses “s”/“S” or a push button to start the game on the other hand is completely dependent on the player - a good source of randomness. *1 Does not have to be this exact message and must be one out of 3 random messages that carries the same meaning. Game Logic – Boxes Game Logic – Boxes Tier A: 8 marks Requires Move Player with Push Buttons or Move Player with Terminal. When the player attempts to move onto a box: • If there is nothing behind the box the player is trying to move onto, the box must be pushed by one square in the direction of the player's move, and the player must also be moved one square in the same direction, such that the player icon ends up at the original location of the box. If there was a message displayed in the message area of the terminal, it must be cleared. 8

CSSE2010/CSSE7201 Semester 2 2024 Before Message [Previous Message] AVR Project Action After [No Message] Display → Terminal: “d”/”D” Buttons: B0 Figure 7: Example of player moving the box to the right. This is only one example; you must consider the player moving boxes in other directions too. • If there is a wall behind the box they are trying to move onto, nothing should happen, and the player must be notified via a message in the message area of the terminal saying that a box cannot be pushed onto the wall. Before Action After Message [Previous Message] Cannot push box onto wall.*2 Figure 8: Example of player moving a box to the right onto a wall. This is only one example; you must consider the player moving boxes onto walls in other directions too. • If there is another box behind the box they are trying to move onto, nothing should happen, and the player must be notified via a message in the message area of the terminal saying that a box cannot be stacked on top of another box. Before Action After Message [Previous Message] Cannot stack boxes.*2 Figure 9: Example of player moving a box to the right onto another box. This is only one example; you must consider the player moving boxes onto boxes in other directions too. When a box is moved onto a target square, that square must be rendered bright green, and a message indicating that a box has been moved onto a target must be displayed in the message area of the terminal. Boxes can also be pushed off target squares, and in that case, the target square must revert back to red. However, since the player would be on top of the target square immediately following the move, it should flash between dark green and red. If the player then moves the player icon off the target square, it should revert back to displaying solid red. Display → Terminal: “d”/”D” Buttons: B0 Display → Terminal: “d”/”D” Buttons: B0 9

CSSE2010/CSSE7201 Semester 2 2024 Before AVR Project Action After Display → Terminal: “d”/”D” Buttons: B0 Message Message [Previous Message] Before [Previous Message] Before Box moved onto target.*2 Action After [No Message] Action After Display → Terminal: “d”/”D” Buttons: B0 Display ← Terminal: “a”/”A” Buttons: B3 Message Figure 10: Example of player pushing a box onto and of-f a target square. As with the previous features, wrapping around the edges must be considered, meaning that if a box is at the far-left side and there’s nothing on the far-right side, and the player pushes that box further to the left, it would show up on the far-right side. Messages printed after invalid moves must also be cleared whenever a valid move is made, as before. *2 Does not have to be this exact message; you can come up with your own. Level Time Level Time Tier A: 4 marks Keep track of the amount of time the player has spent on the level by displaying the number of seconds elapsed since the start of the level on the terminal. The amount of time elapsed must be displayed in seconds and must not overflow (i.e., back to 0 or become negative) during a reasonable gameplay. When the level starts, the level time must be 0 (seconds), and it should increment to 1 after a whole second has passed. This feature must not spam the terminal. [Previous Message] [No Message] Note Terminal spamming happens when you send more data than needed. For example, you only need to update the time once per second, however if you update it 5 times per second with the same value, that is considered as terminal spamming and marks will be deducted. 10

CSSE2010/CSSE7201 Semester 2 2024 Seven-Segment Display Step Count Seven-Segment Display Step Count Requires Move Player with Push Buttons or Move Player with Terminal. AVR Project Tier A: 6 marks Dependencies Game Logic – Walls or Game Logic – Boxes Reason Needed for verifying that invalid moves do not cause the step count to increase. Max Mark if Not Implemented 5 Keep track of the number of steps that the player has taken since the beginning of the level and display the last two decimal digits of that count on the seven-segment display. When a level starts, the step count must be 0 and should increment by one whenever a valid move is made. When the step count reaches 99, it should overflow back to 0 on the seven-segment display when another valid move is made. If the value to be displayed on the seven-segment display is a single-digit number (i.e., 0-9), it must be displayed on the right digit and the left digit could either be turned off or display 0. →→→→ Figure 11: Seven-segment display overf-lowing correctly. The step count must not overflow at any other number. →→→→ Figure 12: Seven-segment display overf-lowing incorrectly. Both digits of the seven-segment display must be on at the same time, without flickering or ghosting, and the display must be appropriately bright. The seven-segment display must be off (display nothing) at the start screen and should display the step count only during a game (and in the future, at level victory). Hint Check out the Lab 15 tasks and Lab 13 Task 2 for how to display 2 digits simultaneously on the seven-segment display. You may copy code from lab exercise solutions. 11

CSSE2010/CSSE7201 Semester 2 2024 AVR Project Tier A: 6 marks Max Mark if Not Implemented 4.5 5 Terminal Game Display Terminal Game Display Dependencies Move Player with Push Buttons or Move Player with Terminal Game Logic – Boxes Reason Used for testing. Used for testing. Display a copy of the LED matrix display on the terminal (may be displayed at any reasonable location but see Terminal Layout section and Figure 4 for recommendations) using block characters (e.g., spaces) of various colours. This should allow the game to be played either by looking at the LED matrix or at the terminal. The game display on the terminal must be in sync with the LED matrix display (i.e., no apparent difference between the displays), with the exception that the play icon does not have to flash (it can if you want to; but extra marks will not be awarded). The speed of the gameplay must not be adversely affected by the presence of this feature (it is okay if the very start of a game lags a bit due to having to paint the entire map), and this feature must not spam the terminal. The colours displayed on the LED matrix must match the colours displayed on the terminal, with the exception that you may substitute colours that are used by the game but not defined in the terminal I/O code (dark green and orange) with other colours of your choice (e.g., blue, magenta, cyan). Please document the colours you have used in your feature summary. Hint Normally, a space looks like a solid black character, because it has a black background and no foreground. If you set the background colour to something else, for example red, then a space would look solid red. You can set background colour to, for example, red by including terminalio.h and calling set_display_attribute(BG_RED). Note Since the LED matrix pixels are square/round while terminal characters are not, it is fine for the terminal display of the game to look vertically squashed. You may improve the aesthetics of the terminal game display by using multiple characters for one pixel; however, that is not required. Level Victory Level Victory Tier A: 8 marks Max Mark if Not Implemented 7 7 Requires Game Logic – Boxes. Dependencies Seven-Segment Display Step Count Level Time Reason Used for testing. Used for testing. 12

CSSE2010/CSSE7201 Semester 2 2024 AVR Project When all targets have boxes on them, the game is over and the player wins. Implement logic to detect game over. Upon game over, the player must be notified on the terminal that they have completed the level and be shown the number of steps and the amount of time in seconds (rounded down to the nearest second) they took. In addition, a score should be displayed. The score is calculated by: Score = max(200 – S, 0) × 20 + max(1200 – T, 0) where S is the number of steps it took the player to complete the level (the actual number, not just the last two digits displayed on the seven-segment display), T is the time in seconds (rounded down to the nearest second) it took, and max is a function which returns the largest of its two parameters. The player must be able to restart the current level (at this stage, there is only one level) by entering “r”/“R” at the terminal or exit back to the start screen by entering “e”/“E”. You do not have to indicate these on the terminal, but you may do so if you wish (the base code prints it by default). When the level is restarted, all game objects (boxes, player) and states (step count, level time) must be reset. When the game is exited, the player should be returned to the start screen, and it must be possible to start a new game by pressing “s”/“S” or any of the push buttons. When the level is complete, the LED matrix should show the last box being on top of the last target (i.e., all target squares being bright green and no orange boxes left), and the player icon should be hidden. WX：codinghelp