***************************************** Laboratory 2: Timed Game: Colordle ***************************************** Laboratory Description ********************** In this lab, a simple game is built consisting of switches and pushbuttons to control the color of an RGB LED in order to match a pattern. A timer is used to limit the answer window time and to provide program delays. Laboratory Goals ---------------- This laboratory is designed to further a student's understanding of: * Using state diagrams, flow charts, and/or pseudocode to aid in algorithm development, * The use of timers in producing delays and timed events, and * The implementation of interrupts. * Techniques to produce more accurate and efficient code. Preparation ----------- Students should complete Activities 6, 7, and 8 prior to starting the laboratory. Hardware and Tools ------------------ * |rslk_long| * Breadboard * Components (provided): * 1x Pushbutton and 1x 1kΩ Resistor * Wire (available in classroom) Game Description **************** .. important:: The description of this lab is done almost entirely through text and video demonstration; as opposed to providing a supplementary flowchart as was done in Lab 1. Future labs will generally have additional figures or pseudocode to aid in understanding and development. This laboratory is effectively a modification of the game `Wordle `_ to use colors instead of letters and words. It is similar to the game Mastermind (`Wikipedia `_) with scoring modifications. The main game loop consists of the player trying to guess an unknown color pattern, 4 elements long. The players enters a guess by pressing the six bumper buttons, each corresponding to a color, in the desired sequence. Once a guess has been entered (four bumper buttons pressed), the program will respond by flashing the RGB four times, where each flash corresponds with the guess position and indicates: 1. Green: The guessed color in the corresponding position is correct. 2. Yellow: The guessed color exists in the pattern, but not in the correct position. 3. Red: The guessed color does not exist in the pattern. For example: if the unknown sequence is *Green-Magenta-Blue-Red*, a guess of *Red-Green-Blue-Yellow* would result in a response sequence of *Yellow-Yellow-Green-Red*, indicating that the first two positions have colors in the pattern but not in the correct locations, the third position is correct, and the fourth guessed color doesn't exist in the pattern. Afterwards, the guess and response will be printed on the terminal for the player to refer back to. Duplicate colors in the guess or answer are handled by indicating one-to-one matches; that is, if the answer has one *Blue* and the guess has two *Blues*, the first *Blue* in the guess would be marked correct with either *Green* or *Yellow*, depending on the position. The second *Blue* would be marked as incorrect (*Red*). The player has a maximum of 30s (may be changed) to enter a guess; otherwise the guess is marked as incorrect (*Red-Red-Red-Red*) and any partially entered guess is discarded. The player may clear their current guess and start again by pressing the pushbutton prior to the timeout; however, this does not reset the guess timeout timer. The guess reset should be noted with a 500 ms *White* flash from the RGB LED. When the guess is completely correct, the RGB LED should continuously blink *Green* and the total time taken to determine the unknown sequence is printed on the terminal along with the number of guesses used. A new game starts with the press of the pushbutton. At the start of a new game, the program generates the unknown sequence randomly. Once the sequence is set, the program should wait 1-5 seconds (up to programmer) prior to receiving the first guess; where this startup wait is indicated to the player by the RGB LED being lit *White* and then turning off. Prior to the new game pushbutton being pressed, the program should monitor the bumpers and light up the corresponding LED (while pressed) so the player can identify the color associations. This is only necessary upon first starting and may be omitted on subsequent games. A demonstration of the laboratory functionality is provided in the video below *without narration*. .. youtube:: kb9YXBtmW1E :align: center Notes ----- * The RGB LED is LED2 on the |devboard| and |rslk|. * When the player enters an element of a guess, the RGB LED should light with the corresponding color while the bumper is pressed. * The generated sequences may have duplicate colors. * RGB LED timed blinking should always be 0.5 seconds on, 0.5 seconds off. * The total round timer should be accurate to 0.1 second and should start after the RGB LED turns off after showing *White* at the beginning of the game. * If a bumper is currently pressed and another bumper or the pushbutton is pressed, the second pressed may be ignored. * It may be assumed that any presses of the bumpers or pushbuttons are short; therefore, it is allowable for the code to pause until released (the code does not have to continuously check timeout, etc., during a press). * The player should have a maximum number of allowed guesses. A suggested number is 5. .. hint:: Using a simplistic solution algorithm (test one color each guess, except last color), the pattern may always be found in 6 or less guesses. This may be very useful in debugging. Part A: Planning and Preparation ****************************************** The first checkoff of this lab consists of producing a plan for implementing the game. The group should work together to build a comprehensive program design. This design must consist of one or more flow charts thoroughly describing the actions the program must take. The flow charts elements must describe single events or actions taken; they should not be summaries of multiple functionalities. For example: * Good flow chart items: * *light RGB LED required color* * *check for bumper 0 press* * *wait 1 second* * Bad flow chart items (without clarification): * *adjust RGB LED with bumper presses* * *Display response* * *Read user's sequence* Groups are encouraged to explore the possible use of state diagrams, though they are not required. Likewise, the program may be implemented using either a linear progression type implementation or a finite state machine; as described in the lecture; or any other means as viable. Groups should be aware that two functions, :code:`checkGuess()` and :code:`printResult()`, are provided to them, as discussed in Part C. These two functions can be represented in the group's plan as a single block each in the flow chart as opposed to describing the contained algorithms in depth. As this game consists of repeatedly guessing and checking 4-position guesses, it implies that the solution, guesses, and guess results be stored in 4-element arrays; with :code:`for` loops used to increment through them as necessary. **Checkoff:** The design produced by the group should be submitted to :xref:`Gradescope`. These designs will not be graded in-person. Do not expect feedback for these designs prior to working on the lab in earnest. Part B: (Class 2) Preliminary Development ***************************************** Download and use the :download:`Lab2_template.zip <../_static/ccs_projects/Lab2_template.zip>` template project for this lab. Groups are expected to build pieces of the full game. This includes finishing: * GPIO Initialization: * Bumpers, pushbutton, and RGB LED all initialized and working. * Timer Initialization: * Timer configured with 32 bit divider and a period that easily adds to 100 ms and 500 ms. The timer configuration from Activity 8 is acceptable. * Required Functions: * A function :code:`void setRGB(int8_t color)` which will light the RGB LED to the requested color, which is specified by a number :code:`color`. Number/color association matches the bumper/color association as provided in the next subsection. * A function :code:`int8_t readBumpers()` that when called will check to see if any bumper is pressed and will subsequently wait for it to be released. While the bumper is pressed, the corresponding color should be lit. The function should return a number corresponding to the bumper pressed (the *x* in BMPx) or -1 if no bumper was pressed. * Game Starting Logic * Printing of instructions, wait for pushbutton press and monitoring of bumper presses/lighting of RGB LED while waiting. The functions as required above should be used in this "monitoring". * Initial support for displaying a color pattern with correct timings. * The code will be used to display the result array. This array will consist of the numbers 0, 1, and 3, corresponding to Red (incorrect color), Green (correct color/position), and Yellow (correct color, incorrect position), respectively. * This may be tested/demonstrated by hardcoding a 4-element result array and looping through it. .. important:: While Activity 8 introduced the use of interrupts with the GPIO, we *highly suggest* that **GPIO interrupts are not used** in this lab as they can be very difficult to implement and debug for this type of program. Timer interrupts will still be needed, however. GPIO Selection -------------- Groups may decide which port pins to use for each component but should limit pin selection to those not used by the RSLK. The pin map: :download:`RSLK_MAX_pin_map.pdf <../_static/hardware/RSLK_MAX_pin_map.pdf>`, specifies all default connections. Do not use any pins that have an entry in the "TI_RSLK Connections" column. For the purposes of this lab, groups only need to select a pin for the pushbutton. As listed in this document, the RGB LED is connected to: * P2.0: Red Channel * P2.1: Green Channel * P2.2: Blue Channel where each segment of the LED is connected to ground (such that outputting a HIGH signal will turn the channel on). Secondary colors (Yellow, Magenta, Cyan) may be generated by turning two channels on at once and white is produced when all channels are on: .. figure:: img/lab2_rgb-mixing.svg :align: center RGB Additive Color Combinations All six of the bumper buttons must be used in this lab. These should be associated to the colors as shown in the following table. Similarly, the association between argument :code:`color` for function :code:`setRGB` is also included: +--------+---------+-----------+ | Bumper | Color | ``color`` | +========+=========+===========+ | | Off | -1 | +--------+---------+-----------+ | BMP0 | Red | 0 | +--------+---------+-----------+ | BMP1 | Green | 1 | +--------+---------+-----------+ | BMP2 | Blue | 2 | +--------+---------+-----------+ | BMP3 | Yellow | 3 | +--------+---------+-----------+ | BMP4 | Magenta | 4 | +--------+---------+-----------+ | BMP5 | Cyan | 5 | +--------+---------+-----------+ | | White | 6 | +--------+---------+-----------+ Wiring of all the external components should be consistent with the wiring required for Laboratory 1. Considering only an external pushbutton is required, it is acceptable to build and leave the associated circuit constructed on the car protoboard. All inputs should have :ref:`debouncing ` added for both presses and releases. This may be done with the :code:`__delay_cycles()` function, as opposed to with the Timer; however, using the Timer to provide this functionality is acceptable. A suggested delay for debouncing is 10 ms. Delays ------ The timer usage as presented in Activities 7 and 8 show how to measure time but do not show how to produce delays. Delays in code may be done through :code:`while` loops, waiting for the delay condition to be met. For the case of timers, the code can be configured to wait for a specific number of timer resets/interrupts to occur. Code may be added within the delay :code:`while` loop if additional functionality is required, otherwise the loop can be empty, :code:`{}`, or terminated with a semicolon, :code:`;`. .. code-block:: C timer_resets = 0; // assuming this variable is incremented in timer ISR while(timer_resets < 10); // wait for 10 timer resets. .. hint:: Multiple global variable counters can be added to a single timer overflow/reset ISR to keep track of different timed events that may occur simultaneously. These delays **must be** implemented using interrupts and not through the methods presented in Activity 7. Checkoff -------- A successful checkoff for this portion of the lab will include a demonstration of the components as listed above. These components may be demonstrated independently (e.g., commenting/uncommenting code, two separate projects, etc.). The grader will also request to see the associated GPIO and Timer initializations. Be prepared to discuss the implementation. Part C: (Class 3) Finished Game ******************************** Complete the remainder of the game, get checked off, and submit your code to the :xref:`Gradescope` assignment. The algorithm for producing the guess results (correct positions, incorrect positions, incorrect colors) can be very complicated. Therefore, this segment of code is provided in the template project as function :code:`checkGuess()`. There is documentation provided for this function within the :code:`main.c` file on how to use it. Similarly, a :code:`printResult()` function is also provided to display the player's guess and result on the terminal. For the code submission, your code **must** have group member names, RINs, and section added within the comment block at the top of the code. The laboratory will not be considered complete if this information is lacking.